Start here
Concepts
The dozen words the dashboard, the CLI and these docs use, and how they fit together.
On this page
How the pieces fit
The library holds skills. Each skill has numbered versions and a scope: global (every repo), library (any repo you add it to) or repo (one repo only). A repo gets its global skills, the library skills assigned to it and its own repo skills. Together they make the repo's bundle, which sync writes into the repo. Every sync reports back, and the difference between what the repo has and what it should have is its drift. Skills change through proposals.
Three ways to have a skill
- Import from GitHub and use it as-is, or extend it with your team's additions (Markdown and extra files). Re-imports replace the upstream part and keep your additions. For deeper changes, fork it into a team skill.
- Write a team skill, available to add to any repo.
- Write a skill for one repo, installed there and nowhere else.
Any skill can be made global so that every repo gets it, including repos added later. A repo can opt out of a global skill unless it is marked required.
A skill in layers
The SKILL.md a repo receives is built from up to three layers, each with one owner:
the skill itself ← upstream, or your team skill
## Our additions ← team-wide, imported skills only
## In this repository ← this repo's overlayEach layer updates on its own: a new upstream import keeps your additions, and a new version keeps every repo's overlay.
The library
- Skill
- A folder with a SKILL.md (a name and a description agents read) and any files it needs. Agents load it when the task matches.The description is always in the agent’s context; the body is read only when the skill is used. A skill can hold scripts, templates and references beside SKILL.md.Also: SKILL.md
- Description
- The frontmatter line that tells an agent when to use a skill. It is in every session’s context, so keep it short and specific.Say what the skill does and when to use it ("Use when reviewing a pull request"). Lint warns over 400 characters and when there is no "use when".
- Version
- A saved, numbered copy of a skill’s files. Versions never change; an edit or an approved proposal makes the next one.Any version can be compared with another, restored (which makes a new version with its files) or pinned in a repo.Also: v1, v2
- Scope
- Where a skill applies: every repo (global), any repo you assign it to (library), or one repo only (repo).Also: global, library, repo
- Global skill
- A skill every repo gets, including repos added later. Repos can opt out unless it is marked required.Use it for the few standards that hold everywhere, like how to review a pull request. Each one adds to every session’s context, so keep the list short.Also: scope: global, required
- Source
- The GitHub repository a skill was imported from, such as mattpocock/skills. Skillify checks it daily for changes.Also: upstream
- Upstream update
- The source has commits the library has not imported yet. Review the diff, then import to make new versions.Skillify never imports on its own: a change to a shared skill reaches every repo that tracks it, so a person looks first.Also: update available
- Our additions
- Team-wide Markdown and files added to an imported skill, under “Our additions”. Re-imports keep them.The upstream part is replaced on each import, so updates keep flowing; your additions are carried onto every new version.Also: extension, ## Our additions
- Fork
- A team copy of a skill under a new name, for changes too deep for additions. The original’s later changes stay visible.The fork is a team skill: edit it freely. Skillify shows what changed in the original since you forked, so you can catch up by hand.
- Lint
- Checks on a skill before it is saved: name, description, size, file paths, and anything that looks like a secret.Errors block saving (a bad name, a secret, a path outside the skill). Warnings do not (a long description, a broken link).Also: lint_skill, findings
Repositories
- Repo
- A GitHub repository registered in Skillify by owner/name. It gets the skills assigned to it, written into its own files.Also: repository, owner/name
- Target
- Where a repo’s skills are written: .agents/skills (Codex, Cursor and others) and .claude/skills (Claude Code).Most repos want both. Turn one off in the repo’s settings if no one on the team uses that agent.Also: .agents/skills, .claude/skills
- Assignment
- A skill added to a repo. It tracks the latest version unless pinned, and can carry an overlay for that repo.Also: add_skill_to_repo
- Pin
- Hold a repo on one version of a skill. New versions show as available but do not reach the repo until you unpin.Also: pinned
- Overlay
- Markdown for one repo, added to the end of a shared skill under “In this repository”. The shared skill stays the same.It is the last layer: the skill’s own text, then the team’s additions (imported skills), then the overlay. The layers above it keep updating.Also: set_repo_overlay, In this repository
- Kit
- A named set of skills, like “Review” or “Frontend”, added to a repo in one step. Later changes to the kit do not touch repos.
In the repo
- Bundle
- Everything a repo should contain right now: its skills with overlays, the AGENTS.md block and the config. Sync writes it.
- Sync
- node .skillify/cli.mjs sync: writes the repo’s bundle into its files. Commit the result so every clone has the skills.Sync refuses to overwrite a skill someone edited in the repo; it says which one and how to keep the change (a proposal) or drop it (--force).Also: skillify sync
- AGENTS.md block
- The part of AGENTS.md that Skillify writes: a table of the repo’s skills and its notes, between two marker comments.Everything outside <!-- skillify:start --> and <!-- skillify:end --> is yours and never changed. If there is no CLAUDE.md, sync adds one that says @AGENTS.md.Also: skillify:start, skillify:end
- Lock file
- .skillify/lock.json records which version of each skill was written and its hash, so local edits can be spotted.Also: .skillify/lock.json
- Drift
- How a repo’s files differ from what it should have, from its last status report: current, behind, edited locally, missing.Each sync and status run reports which skills are on disk and their hashes. Behind means a newer version is waiting; edited locally means someone changed the files in the repo.Also: current, behind, modified, missing, extra
- Ingest key
- A write-only key in .skillify/config.json. It can only report status and usage, so it is safe to commit.It cannot read skills or change anything. Rotate it in the repo’s settings if you want to cut off old clones.Also: ik_, ingestKey
Review and usage
- Proposal
- A suggested change to a skill, with its diff and lint results. Approving it makes the next version.People propose from the dashboard; agents propose over MCP. Agents can never approve.Also: propose_skill_change
- Two-person rule
- A proposal is approved by someone other than its author. The author can withdraw it, never approve it.
- Stale proposal
- The skill changed after the proposal was made. Approving applies its edits on top of the latest version; check the diff again.
- Usage
- How often agents loaded each skill, per repo and day. Counts only: repo, skill name and time, nothing from the session.An optional Claude Code hook reports each Skill tool call with the repo’s ingest key. Turn it off with "usage": false in .skillify/config.json.Also: uses, usage hook
- Context cost
- Roughly how many tokens a repo’s skill descriptions add to every agent session, used or not.Estimated as characters ÷ 4. Skills nobody uses still cost this on every session: the usage page shows which ones to drop.