Managing skills
Repositories and overlays
What each repo gets (global, assigned and its own skills), how overlays tailor them, pinning, and reading drift.
Add a repo
Repos → Add repo takes owner/name. Skillify does not need access to GitHub; the repo is a name until someone installs into it. Each repo has:
- Skills: its assignments.
- Targets: where skills are written,
.agents/skills,.claude/skillsor both. - Notes: Markdown added to its
AGENTS.mdblock under "Repository conventions". - An ingest key: the write-only key its CLI uses to report status and usage.
What a repo gets
A repo's skills come from three places, and its Skills tab shows each one's origin:
- Global skills arrive on their own, in every repo, including repos added later. Opt out of one that does not fit (a frontend skill in a backend service) unless it is marked required.
- Library skills you add, one at a time or with a kit.
- Repo skills written for this repo alone.
Each tracks the latest version unless pinned: when a skill changes, the repo shows as behind until someone runs sync.
Overlays
An overlay is Markdown that one repo adds to the end of a skill. It is the last of up to three layers, so the agent reads the shared text first and the local notes last:
…the skill itself… (upstream, or your team skill)
## Our additions (team-wide, imported skills only)
- Use Vitest. Tests sit next to the code.
## In this repository (this repo's overlay)
- Money is integer cents. Flag any float.
- Webhooks must be idempotent; ask for the test.Use overlays for what only this repo needs: its test command, its folders, its rules. The shared text keeps updating underneath, which is the point: no fork to keep in step. If an overlay would help every repo, propose it to the skill (or, for an imported skill, to its additions) instead.
Pin a version
Pinning holds a repo on one version. Newer versions show as available, and the repo stays where it is until you unpin or pin a newer one. Pin while you try a big change in one repo first.
Preview
Preview on any assignment shows the exact SKILL.md this repo gets, overlay included, and the repo's context cost: roughly how many tokens its skill descriptions add to every session.
Drift
| State | What it means | What to do |
|---|---|---|
| Current | The repo has exactly what it should. | Nothing. |
| Behind | A newer version (or a changed overlay) is waiting. | Run node .skillify/cli.mjs sync and commit. |
| Edited locally | Someone changed the skill’s files in the repo. | Propose the edit, or sync --force to drop it. |
| Missing | The skill is assigned but not on disk. | Run sync. |
| Extra | A skill on disk that is no longer assigned. | Run sync; it removes skills it installed. |
| No report | Nothing has synced from this repo yet. | Install it. |
Drift comes from the repo's last report, sent by every sync and status. It is only as fresh as that run; put status --check in CI to keep it current and to fail builds that drift.