How SkillCatalog works

In Getting started, Dana wrote a skill in Acme's catalog, delivered it to her AI tools, and shared one repository's skills with Sam. This page explains the model behind those steps, in the order you met them, and then what SkillCatalog leaves to you.

Every skill in that example took the same path, from the catalog on Acme's Git host to the folders Claude Code reads:

acme-skills on your Git host                       the catalog
       |  ^
  pull |  | push                                   skc sync, desktop saves
       v  |
~/.skillcatalog/catalogs/acme-skills               your clone of the catalog
       |
       |  profiles choose entries                  Home profile, payments-api
       v
~/.claude/skills/review-checklist/                 delivered by the Home profile
payments-api/.claude/skills/release-notes/         delivered by the payments-api project profile

• Skills are written and changed in the catalog, and reach everyone through Git, so your Git host provides their history, access control, and review.
• Profiles decide which skills reach which folders. You choose the skills you want everywhere, and each repository lists the skills it needs.
• The delivered files at the bottom are copies, which SkillCatalog keeps up to date.

Catalogs

Acme keeps its skills in one Git repository, acme-skills, so every engineer pulls the same versions. Once a repository is added to SkillCatalog, it is a catalog, and SkillCatalog works in your clone of it under ~/.skillcatalog/catalogs/. That clone is where you edit skills by hand, and it is what delivery reads.

Each catalog has a catalog id, the id in its catalog.yaml. Profiles and team manifests name a catalog by that id, which is the same on every machine, so the team manifest Dana wrote works unchanged on Sam's machine.

The desktop app also adds the Essentials catalog, whose skills teach AI tools how to use SkillCatalog. It comes with the app, and an app update that changes those skills also updates your copy.

Skills, stacks, and bundles

Dana's review checklist is a skill: a folder skills/review-checklist/ in the catalog, with a SKILL.md that tells an AI tool when to use it and what to do. The folder may also hold companion files, such as a script or a template the instructions refer to, and delivery copies them along with SKILL.md.

Acme's reviewers later use two skills together, review-checklist and review-security. To deliver both with one entry, Acme lists them in a stack, code-review. A bundle lists stacks in the same way, for a larger set such as everything a new engineer needs.

Profiles

Dana wants the review checklist in every repository, but release-notes only in payments-api. She needs two profiles for that, because a profile delivers its entries to one place:

A project profile starts from the team manifest, which everyone who works in the repository shares through Git. Each person may also keep a local manifest in their checkout, which stays out of Git, to add entries or leave team entries out for themselves alone.

Delivery

When Dana added the checklist to her Home profile, SkillCatalog wrote it into ~/.claude/skills/review-checklist/ at once. Adding, removing, or reordering a profile's entries delivers that profile at once, skc sync delivers every profile after it pushes, and skc deliver delivers every profile again on request.

Delivery copies a skill's files as they are, except SKILL.md. In that file, it adds a few metadata fields and turns references to other skills into paths the AI tool can follow.

SkillCatalog records every file it delivers, so later deliveries know which files are theirs. They update a file when the catalog changes, restore it when you delete it, and remove it when no entry selects the skill any more or you turn the tool off. A file you edited is drift, as Dana saw in step 5: delivery never overwrites it, and reports it until you delete it. Delivered files and drift lists every case.

Saving and syncing

When Dana changed the checklist in the catalog and synced, Sam got the change on his next sync. To sync is to commit your catalog changes, pull every catalog, push, and then deliver, whether you run skc sync or use the Sync Center in the desktop app. For one checkout, skc update does a smaller job.

In the desktop app, saving a skill commits and pushes it at once. A file you edit by hand in your clone stays on your machine until you sync, as Keep catalogs in sync explains.

Each catalog also has a sync policy, which decides where those pushes go. With direct, the default, each change goes straight to the catalog's branch. With review-branch, each change waits on its own branch as a proposal until someone reviews and merges it, as Review changes before they reach a catalog describes.

What SkillCatalog does not do

SkillCatalog manages only your tools' skills folders. It does not manage rules files, MCP servers, or other tool settings, and your AI tool decides when to read a skill and how to follow it.

SkillCatalog checks that skills are well formed: each name matches its folder, required fields are present, and references point to skills that exist. It cannot tell whether a checklist gives good advice, so review changes to skills as you review code.

SkillCatalog copies the files in a skill's folder as they are, scripts included, without inspecting or running them. Anyone who can push to a catalog can change what your AI tools read and run, so add catalogs only from people you trust.

SkillCatalog does not copy edits in a delivered file back to the catalog. To change a skill for everyone, edit it in the catalog and sync, as Dana did.

SkillCatalog does not add the folders it delivers into to a repository's .gitignore, so you keep delivered files out of Git yourself.

SkillCatalog sends the text of your skills off your machine only through Git, and to your AI provider when you score or improve a skill. When a catalog names a metrics address, everyone who has that catalog also sends it anonymous usage metrics, which stay on until you turn them off. Apart from that, the desktop app checks GitHub for new versions.