Remote Skill Sources

Share skills from a central git repo — every project stays in sync automatically

Point agents at a git URL — every project picks up the latest skills without a manual install.

Quick Start

1. Sync from the CLI

   Pull the latest skills and cache them locally. Every agent on this machine picks them up automatically — no code change needed.

   # Pull the latest and cache it locally
   praisonai skills sync https://github.com/acme/team-skills
   
   # Pin to a branch / tag / commit for reproducible builds
   praisonai skills sync https://github.com/acme/team-skills --ref v1.2.0

2. Declare once, sync bare

   Add sources to your project praisonai.yaml, then run sync with no arguments:

   skills:
     urls:
       - https://github.com/acme/team-skills
       - url: https://github.com/acme/internal-runbooks
         ref: main

   praisonai skills sync

   sync reads skills.urls (or the alias skills.sources) from the project’s praisonai.yaml/praisonai.yml first, then falls back to the user-global ~/.praisonai/config.yaml.

3. From Python

   Pass a git URL to sources= and discovery fetches, caches, and validates it:

   from praisonaiagents import Agent
   from praisonaiagents.skills import discover_skills
   
   skills = discover_skills(sources=["https://github.com/acme/team-skills"])
   
   agent = Agent(
       name="Reviewer",
       instructions="You review pull requests using our team's shared skills.",
       skills=[str(s.path) for s in skills],
   )
   
   agent.start("Review PR #42")

How It Works

Sync shallow-clones the repo (with GIT_TERMINAL_PROMPT=0 so a credential prompt cannot hang it), resolves the commit, atomically swaps it into a versioned cache, and points current at it. Each git call has a 120-second deadline. If git fails or stalls, the last-good current alias is returned so agents keep working offline.

Configuration Options

Two YAML shapes are supported — pick either. skills.sources is an alias for skills.urls.

# String form
skills:
  urls:
    - https://github.com/acme/team-skills

# Dict form with ref pinning
skills:
  urls:
    - url: https://github.com/acme/team-skills
      ref: v1.2.0

When both project and user config define sources, project entries win and are listed first; duplicates are removed while order is preserved.

CLI — praisonai skills sync:

Python API:

sources items may be a URL str, a {"url": ..., "ref": ...} dict, or any object with a .fetch(cache_dir) -> List[Path] method.

Which entry point should I use?

Team Workflow

This feature shines for teams: one lead pushes a skill, everyone syncs.

Common Patterns

Pin for reproducible builds

Always pass a ref in CI so builds don’t drift onto an upstream commit.

praisonai skills sync https://github.com/acme/team-skills --ref v1.2.0

Local-wins layering

Put per-project overrides in ./.praisonai/skills/. The remote cache is lowest precedence, so a local skill with the same name always wins a collision.

Offline-first

The last-good cache is served automatically on any network failure or stalled remote — no code change needed.

Best Practices

Related