Targets and security¶

Repertoire copies a validated skill directory into one or more agent-specific skill roots. By default those roots are under the home directory (Global root). Use --project for the Project root column. With no --target, it detects existing client configuration or skill directories, and in global scope also well-known CLIs on PATH. An explicit target creates its skills directory when needed. The special --target all value expands to every target in the table, including clients that are not currently detected.

The all value is accepted by add, install, and update. For bulk operations, these commands apply the override to every selected skill:

repertoire install --target all
repertoire update --target all

The expanded concrete target names (not all) are saved in the manifest and lock, keeping installation state explicit.

Catalog commit signatures¶

A catalog registration can name the public keys allowed to sign that catalog. The key files sit next to the manifest that registers the catalog, and each fingerprint has to match its armored file. Repertoire checks the commit in a temporary keyring created for that check. Your GnuPG home is left untouched, and no keyserver is contacted.

The check runs for remote catalogs, local paths, and --override or REPERTOIRE_OVERRIDES checkouts. A registration with no trust block is unchanged and does not invoke GnuPG. A failed check stops materialize and names the catalog, the skill, and the commit, and says the commit signature failed. add, install, update, and bootstrap share that step, so they stop before writing the lock.

Skill digest signatures¶

A trusted catalog skill also carries REPERTOIRE.digest.asc beside SKILL.md. That file is a detached ASCII signature over the skill's content digest: the exact hex text Repertoire hashes from paths, modes, symlink targets, and file bytes. The signature file itself is left out of the hash.

Verification imports only the public keys named in the catalog's trust block into a temporary keyring, after each file's fingerprint matches the registration. Your GnuPG home is left untouched, and no keyserver is contacted. Either declared key may sign. The same file works for a skill in a loose catalog. A local path or an override does not skip the check when the registration lists trusted keys.

Verification fails when gpg is missing, the signature file is missing or not a regular file, the skill bytes change, the fingerprint does not match, or the signature was made by a key outside the trust block. The error names the catalog, the skill, and the commit, and says the digest signature failed. add, install, update, and bootstrap check it before they write the lock. A catalog with no trust block is not checked.

When both checks pass, the lock records the fingerprint that signed the catalog commit (commit_fingerprint) and the fingerprint that signed the skill digest (digest_fingerprint). Those fields sit on the skill entry and on a project-artifact entry for that skill. A catalog with no trust block omits them. Older lock files that omit them still load, and the lock schema stays at 1.

Privacy¶

Repertoire does not collect usage telemetry and does not phone home. Catalog access uses your system Git credentials (SSH agent, credential helper, or provider CLI). Tokens and passwords never belong in catalog URLs or manifests; Repertoire rejects credential-bearing URLs. bootstrap installs from local catalogs and whatever catalog state is already cached, so it does not fetch from the network.

Installation safety¶

• SKILL.md must have valid YAML frontmatter with a matching name and a non-empty description.
• Optional stubs.yaml entries must have valid names, descriptions, instructions, and contained paths resolving to regular files.
• Catalog paths must stay inside the repository. Symlinks are allowed only when they resolve inside the skill directory.
• Repertoire hashes paths, modes, symlink targets, and file content.
• Installation is staged beside the destination and then renamed atomically.
• An unmanaged or locally modified destination is preserved. Replacement requires an explicit --force.
• Skill scripts are copied as data and are never executed during installation.
• Catalogs may declare always-on project instructions and optional managed artifacts. Repertoire supports whole-file copies, marked Markdown sections, and additive JSON-object merges.
• Project instructions install whenever their target is installed in project scope. Bootstrap also installs them into the worktree for global-scope skills while keeping the full skill under the user's home directory.
• Interactive add prompts before installing optional hooks and integrations; noninteractive commands require --with-hooks.
• Hook configuration committed to a repository should invoke tools by binary name through PATH, never through a machine-specific absolute executable path.
• --no-hooks removes previously managed optional artifacts while retaining project instructions. Unrelated Markdown, JSON entries, and locally modified files are preserved or rejected unless --force is explicit.