Skillsets

What is a Skillset?

By default, the skillrepo CLI syncs your whole team library to every repo it runs in. That is the right model when one library maps cleanly to one codebase. But teams run their agents across many repositories, and a repo rarely needs every skill the team has adopted — a marketing repo doesn’t need the database-migration playbook, and your finance repos shouldn’t receive production-deploy tooling at all.

A skillset solves this. It is a named, curated subset of your team library — “engineering”, “marketing”, “finance” — that a repository opts into. The repo receives exactly the skillset’s skills, at the versions your team has approved, and nothing else.

Two Ways to Deliver Skills

A repository receives skills one of two ways. The difference is a single file: whether the repo commits a skillrepo.json that declares a skillset.

The two run side by side. A repo with no skillrepo.json keeps the whole-library behavior exactly as before — adopting skillsets anywhere in your team changes nothing for repos that haven’t declared one. You move a repo onto a skillset when you’re ready, one commit at a time.

Declaring a Skillset with skillrepo.json

A repository opts into a skillset by committing a skillrepo.json file at its root. On the next skillrepo update (or SessionStart auto-sync), the CLI resolves the declaration and delivers that skillset’s skills instead of the whole library.

{
  "skillset": {
    "version": 1,
    "name": "checkout-service",
    "use": "acme/engineering"
  }
}

name

How this repo identifies itself across your team’s repos. You choose it — it is a label, not a lookup.

use

The skillset to run, as owner/name (your team slug and the skillset name). A repo runs exactly one skillset.

The CLI looks for the declaration from your working directory up to the repository root, so skillrepo update resolves the same skillset from any subdirectory. If a declaration is present but invalid, the sync fails closed and writes nothing rather than falling back to the whole library. See the CLI Reference for the full declaration schema, resolution rules, and the exit-code contract.

Curating a Skillset

Skillsets are created and edited from Skillsets in the dashboard. Create a skillset, give it a name, and add skills to it from your team library. Membership is the whole job: a skillset is just the list of skills a class of repo should run.

• A skillset can only contain skills that are already in your team library — adopted from a publisher or authored by your team. Add a skill to the library first, then to the skillset.
• A single skill can belong to any number of skillsets. Your code-review skill can be in “engineering”, “marketing”, and “finance” at once.
• Removing a skill from a skillset only changes that skillset. The skill stays in your library and in any other skillset that uses it.

Versions and the Approved Pin

Skillsets don’t carry versions. A skillset is a list of which skills to deliver; which version of each is decided in one place — the library’s approved-version pin. This keeps version control in a single spot no matter how many skillsets a skill appears in.

Skills your own team authors advance as you publish them. For skills adopted from other publishers, a team lead can turn on review mode: an update from a publisher then waits in a review queue until a lead approves it, instead of reaching your repos on the next session. Once approved, the new version becomes the pin every skillset serves. See Teams for the review queue and trusted publishers.

Compliance and Drift

Every time a repo syncs a skillset, it reports back which skillset it declared and the exact skills and versions it received. The Skillsets view rolls those reports up into a per-repo picture: for a given skillset, which repositories are in line with the approved set, and which have drifted.

Compliance measures delivery — what reached each repo — not what an agent did with a skill once it was there. It answers “are our repos running the approved setup?”, which is a configuration question, not a usage metric.

Governance

Skillsets are a team-lead surface. A few account-wide settings shape how they behave for everyone:

Review mode

Freeze the versions you serve today and route publisher updates through an approval queue before they roll out.

Trusted publishers

An allowlist of publishers whose updates advance automatically, skipping the review queue.

These live in account settings and on the Teams page, alongside who on your team can create and curate skillsets.