Managing skills
The skills library
Three ways to have a skill: import it from GitHub (as-is or extended), write a team skill, or write one for a single repo.
On this page
Whichever way a skill arrives, it is versioned, linted, reviewed and installed the same way.
Import from GitHub
Skills → Import takes a GitHub repository in any of these forms:
mattpocock/skillsmattpocock/skills@main(a branch, tag or commit)acme/handbook/agent-skills(only one folder of the repo)https://github.com/mattpocock/skills
Skillify downloads the repo, finds every folder with a SKILL.md and shows each one with its lint results. Pick the ones you want. A skill's name comes from the name in its frontmatter, so it has one source: a second source, or a team skill, cannot reuse the name.
Use it as-is, or extend it
An imported skill can be used exactly as upstream wrote it. To make it yours without losing updates, extend it: add Markdown under Our additions and, if you need them, extra files (a checklist, a script). Every repo that gets the skill gets your additions.
…upstream's SKILL.md…
## Our additions
- Use Vitest. Tests sit next to the code.
- See checklist.md before you open a PR.When the source changes, re-importing replaces the upstream part and carries your additions and files onto the new version. If upstream adds a file with the same name as one of yours, upstream's wins and the diff shows it.
Fork for deeper changes
Additions go at the end. If you need to rewrite the middle, fork the skill: Skillify copies it under a new name as a team skill that you edit freely. The original stays tracked, and the fork's page shows what changed in the original since you forked, so you can bring over what you want by hand.
Write a team skill
Skills → New skill opens an editor for SKILL.md and any other files. A team skill lives in the library and can be added to any repo. The frontmatter needs a name (lowercase letters, digits and hyphens) and a description:
---
name: review
description: Use when reviewing a pull request. Reads the diff, runs the tests, leaves one comment per issue.
---
# Review
1. Read the PR description first.
2. …The description is what an agent reads to decide whether to load the skill, and it sits in every session's context. Say when to use it, in one or two sentences.
Skills for one repo
Some knowledge belongs to one codebase: its domain rules, its deploy, its odd corners. Write it as a repo skill from the repo's Skills tab, or pick that repo as its scope when you create it. It is installed in that repo only and never offered to others. It is still versioned and reviewed like any other skill.
Global skills
Any skill can be made global: every repo gets it, including repos added later, without anyone assigning it. A repo can opt out of a global skill from its Skills tab, unless the skill is marked required. Keep the global list short; each one adds to every session's context in every repo.
Versions and diffs
Every save makes a new version; versions never change. The Versions tab compares any two, file by file. Restore makes a new version with an old version's files, so history only grows. Saving identical files does nothing.
Upstream updates
Every morning Skillify checks each source for new commits, and a skill whose source moved shows Update available. Open it to see the diff, then import to make a new version. Nothing is imported on its own: a change to a shared skill reaches every repo that tracks it, so a person looks first.
Archiving
Admins can archive a skill that no repo uses. It leaves the library and the MCP listings; its versions stay.
Lint rules
| Rule | Blocks saving | What it checks |
|---|---|---|
skill-md, frontmatter | Yes | A SKILL.md at the root that starts with a --- frontmatter block. |
name | Yes | Present, lowercase letters, digits and single hyphens, at most 64 characters. |
description | When missing or over 1,024 characters | Warns over 400 characters, and when it does not say when to use the skill. |
body | When empty | Instructions after the frontmatter. Warns when SKILL.md is over 500 lines. |
size | Yes | At most 100 files, 512 KB a file, 4 MB a skill. |
path | Yes | Paths are relative and stay inside the skill (no /…, no ..). |
secret | Yes | Nothing that looks like an API key, token or private key. |
remote-exec | No | Warns on piping a download into a shell (curl … | sh). |
link | No | Warns when a relative link points at a file the skill does not have. |