Skip to content
Docs: Repositories and overlays

Managing skills

Repositories and overlays

What each repo gets (global, assigned and its own skills), how overlays tailor them, pinning, and reading drift.

On this page

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/skills or both.
  • Notes: Markdown added to its AGENTS.md block 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:

text
…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

Drift
StateWhat it meansWhat to do
CurrentThe repo has exactly what it should.Nothing.
BehindA newer version (or a changed overlay) is waiting.Run node .skillify/cli.mjs sync and commit.
Edited locallySomeone changed the skill’s files in the repo.Propose the edit, or sync --force to drop it.
MissingThe skill is assigned but not on disk.Run sync.
ExtraA skill on disk that is no longer assigned.Run sync; it removes skills it installed.
No reportNothing 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.