Repertoire¶

The apt-get for AI agent skills.

Repertoire is a package manager for agent skills: named catalogs, a lock with content digests, and a manifest you commit so every laptop and CI job gets the same skills. It never overwrites edits you made by hand and never phones home.

A skill is a folder with a SKILL.md file that teaches an AI coding agent how to do something: review code against your style guide, write docs for your static site generator, use an internal tool. Codex, Claude Code, Cursor, Gemini CLI, Copilot and many others all read the same format, but each one looks for skills in a different directory.

repertoire add zensical --target all

That one line finds zensical in a skill catalog, checks that the package is well formed, copies it into each agent's own skills folder, and records what was installed so a later repertoire update can refresh it safely.

Why a package manager and not a copier¶

Copying a SKILL.md into an agent folder is enough for a one-off try. Repertoire treats skills as packages instead:

• A catalog is a named Git source. Skills resolve by catalog and by source-qualified ID, so two catalogs can both offer review without a silent pick.
• A lock file records the catalog commit and a content digest per target. update and remove refuse to touch a copy you edited by hand unless you pass --force.
• A committed manifest (repertoire.yaml) plus bootstrap or sync reproduces the same set on a new laptop and in CI.

Coming from a one-off skill installer¶

You can keep using another installer to try a skill. Repertoire ignores copies it does not manage, so the two can sit in the same agent folders. When a skill is worth keeping, register its repository as a catalog (repertoire catalog add or repertoire add <git-url>), then repertoire add so the lock tracks it. From then on update, bootstrap, and doctor own that copy.

Install¶

Repertoire ships as a single self-contained binary. Choose the method that fits your platform.

irm https://raw.githubusercontent.com/phillarmonic/repertoire-ai/master/install.ps1 | iex

$env:REPERTOIRE_VERSION = "v1.2.3"; irm https://raw.githubusercontent.com/phillarmonic/repertoire-ai/master/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/phillarmonic/repertoire-ai/master/install.sh | bash

curl -fsSL https://raw.githubusercontent.com/phillarmonic/repertoire-ai/master/install.sh | bash -s -- v1.2.3

go install github.com/phillarmonic/repertoire-ai/cmd/repertoire@latest

Verify the installation, and update in place when needed:

repertoire --version
repertoire --self-update

Quick start¶

If you have used a Linux package manager, the model is familiar: a catalog is a repository, add installs a package, and repertoire.yaml is the manifest you commit so others get the same set. Underlined terms across these docs link to the glossary; hover one for a short definition.

repertoire list --available

Shows every skill offered by the catalogs you have configured. With a fresh install that is the built-in phillarmonic catalog.

repertoire add zensical --target all

Installs zensical into every supported agent and records it as something you want kept installed. Drop --target all to install only into agents Repertoire detects on your machine, or name agents explicitly with --target codex --target claude.

To install from a repository you have not registered yet:

repertoire add /path/to/agent-skills --target all

That registers a catalog named after the directory and installs every skill it offers. Pass --name and --skill (or a /<skill> tail) to choose the catalog name and a subset.

repertoire list

Shows what Repertoire manages on this machine, where each skill came from, and which agents have it.

repertoire update

Fetches catalog changes and refreshes every installed skill. If you edited an installed copy by hand, update stops with an error instead of overwriting it.

Which command do I want?¶

• Install a skill and remember it: repertoire add <skill>
• Install from a Git URL or local repo: repertoire add <git-url>
• Start a project manifest without installing: repertoire init
• Inspect where an installed skill came from: repertoire show <skill>
• Scaffold a new catalog repository: repertoire catalog init
• Preview a mutating command without writing: add --dry-run
• Reinstall or repair skills already declared: repertoire install
• Pull newer versions: repertoire update
• Install everything a project declares (new machine, CI): repertoire bootstrap
• Same, but fetch catalog changes first: repertoire sync
• Something looks broken: repertoire doctor, then repertoire doctor --fix
• Use a private or local catalog: repertoire catalog add <source>
• Remove a skill: repertoire remove <skill>

Every command is described in the command reference.

Let your agent drive Repertoire¶

Repertoire ships with a skill about itself. Install it once and your coding agent knows how to run Repertoire for you:

repertoire add repertoire --target all

Then ask in plain language: "install the zensical skill for Codex and Claude", "create a private skill catalog repository for our team", or "add a repertoire.yaml to this project". The agent knows the commands, the manifest formats, and the safety rules, and can scaffold a whole new catalog repository from scratch. See Let your agent drive Repertoire for what it covers and what it will refuse to do.

Next steps¶

• Set up a project or team: commit a repertoire.yaml so every contributor and CI job gets the same skills.
• Private and company catalogs: publish your own skills from a private Git repository.
• Let your agent drive Repertoire: install the built-in repertoire skill and delegate all of the above to your agent.
• Command reference: every command, flag, and edge case.
• Troubleshooting: what the common error messages mean and how to fix them.
• Glossary: the handful of terms Repertoire uses, in one place.
• Concepts: Manifests and state, Catalogs, Targets and security.
• Contributing: build and test Repertoire itself.