Skip to content
Docs: Skills library

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/skills
  • mattpocock/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.

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

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

Lint rules
RuleBlocks savingWhat it checks
skill-md, frontmatterYesA SKILL.md at the root that starts with a --- frontmatter block.
nameYesPresent, lowercase letters, digits and single hyphens, at most 64 characters.
descriptionWhen missing or over 1,024 charactersWarns over 400 characters, and when it does not say when to use the skill.
bodyWhen emptyInstructions after the frontmatter. Warns when SKILL.md is over 500 lines.
sizeYesAt most 100 files, 512 KB a file, 4 MB a skill.
pathYesPaths are relative and stay inside the skill (no /…, no ..).
secretYesNothing that looks like an API key, token or private key.
remote-execNoWarns on piping a download into a shell (curl … | sh).
linkNoWarns when a relative link points at a file the skill does not have.