SkillCatalog/Documentation

Getting started

This page follows Acme, a small engineering team, as it sets up SkillCatalog. Acme wants two things:

  • Every engineer's AI tools follow the same review checklist, in every repository.
  • The payments team's release-notes skill is available only in its payments-api repository.

Dana sets this up, and her teammate Sam joins in step 7. Each step shows the command Dana runs with skc, the command-line tool, and then says how to do the same in the desktop app when it can.

To follow along, you need an empty repository on a Git host you can push to, such as GitHub or GitLab, and from step 6 a project repository as well. SkillCatalog accepts only remote Git URLs, not paths to folders on your disk. Use your own repository URLs and names wherever the page uses Acme's.

Output on this page shows your home folder as ~, where your terminal prints the full path.

1. Install SkillCatalog and choose a tool

Follow Install SkillCatalog for your platform.

SkillCatalog writes skills only for the AI coding tools you turn on: Claude Code, Cursor, or Codex. Dana uses Claude Code, so she turns it on:

skc settings enable claude-code
Enabled delivery target 'claude-code'.

The CLI calls a tool a delivery target, with the ids claude-code, cursor, and codex. You can turn on more than one. The desktop app asks the same question the first time it opens, on its Choose your tools step.

2. Create your team's catalog

Acme's skills need one place that every engineer can pull from. A catalog is a Git repository of skills that you add to SkillCatalog.

Dana created an empty repository, acme-skills, on Acme's Git host. She left out the README that GitHub and GitLab offer to add, because SkillCatalog can set up a new catalog only in an empty repository. Then she adds the repository:

skc catalog add git@github.com:acme/acme-skills.git
Added catalog 'Acme Skills' (acme-skills). Clone: ~/.skillcatalog/catalogs/acme-skills

SkillCatalog cloned the repository to ~/.skillcatalog/catalogs/acme-skills, where you write and edit skills, and pushed the starter files every catalog needs.

acme-skills, in parentheses, is the catalog id, made from the repository name. Later commands name the catalog by its id, so use yours wherever a command on this page says acme-skills.

In the desktop app, open the catalog menu at the top of the sidebar and choose Add catalog. Fill in Catalog name (Acme Skills, which becomes the id acme-skills) and Source, then choose Add catalog.

3. Write a skill

Dana starts with the review checklist. She writes it as a skill: a folder under skills/ in the catalog, holding a SKILL.md and any other files the skill needs. In her clone of the catalog, she creates skills/review-checklist/SKILL.md:

---
name: review-checklist
description: Use when reviewing a pull request. Lists the checks every Acme review covers.
---

# Review checklist

Before you approve a pull request, check that:

- New behavior has tests, and the tests pass.
- Errors are handled and logged with enough context to debug them.
- No secrets, tokens, or customer data appear in code, logs, or fixtures.
- Public functions and endpoints have up-to-date documentation.
  • name must match the folder name, which is the skill's slug: lowercase words joined by hyphens.
  • description tells AI tools when the skill applies.
  • The body is what the AI tool follows when it uses the skill.

The file exists only on Dana's machine so far. To share it, she syncs: SkillCatalog commits her catalog changes, pulls, and pushes, for every catalog she added:

skc sync --message "Add review checklist"
Synced 1 catalog (0 commits pulled, 1 commit pushed, 0 deliveries).
...

SkillCatalog committed the skill as [skillcatalog] Add review checklist and pushed it, so anyone with the catalog can now pull it.

In the desktop app, open Skills, then choose New skill. When you choose Create skill, the app commits and pushes the skill itself, so there is nothing left to sync.

4. Deliver the skill to your tools

The checklist is in the catalog now, but Claude Code does not read catalogs. It reads skills from its own skills folder, ~/.claude/skills/. SkillCatalog delivers a skill by writing it into the skills folder of each tool you turned on.

Dana wants the checklist in every repository she works in. A profile lists the skills that SkillCatalog delivers together to one place, and your Home profile, with the id home, delivers to the skills folders in your home folder, which your tools read in every repository. Dana adds the checklist to her Home profile:

skc profile add home --catalog-id acme-skills --kind skill --slug review-checklist

The command adds an entry, which names a skill by its kind, catalog id, and slug. skc profile add saves the entry and delivers the profile right away, so Claude Code now finds the skill at ~/.claude/skills/review-checklist/SKILL.md:

---
name: review-checklist
description: Use when reviewing a pull request. Lists the checks every Acme review covers.
metadata:
  skillcatalog/created_at: ...
  skillcatalog/display_name: Review checklist
  skillcatalog/updated_at: ...
---

# Review checklist
...

Delivery added a few metadata fields and left the body unchanged. From now on, skc sync also delivers, after it pushes, so every sync keeps this copy up to date.

In the desktop app, open the skill, choose Add to profiles, then choose Add next to your Home profile.

5. See what happens when a delivered file changes

Delivered files are ordinary files, and anyone can edit them. Dana wants to try a new check before she proposes it to the team, so she adds it to her own copy first:

echo "- Database migrations can be rolled back." >> ~/.claude/skills/review-checklist/SKILL.md

Dana's copy no longer matches what SkillCatalog wrote, and SkillCatalog calls that drift. skc deliver --check looks for drift without changing anything:

skc deliver --check
Error: delivery-check-drift
Drift check for all profiles: drift detected, 1 manually edited, 0 deleted, 0 unreadable.

Manually edited:
- ~/.claude/skills/review-checklist/SKILL.md [claude-code] Review checklist
Hint: Inspect the drifted files. To overwrite local edits with the catalog version, delete the file and rerun `skc deliver`. To keep the edits, leave them in place.

The check fails when it finds drift, so a script or CI job can stop on it. Later deliveries leave Dana's edited copy in place, but a deleted file is different, because delivery writes it again. In the desktop app, your Home profile's page runs the same check with Check for changes.

Dana wants the catalog version back, so she deletes her copy and delivers again:

rm ~/.claude/skills/review-checklist/SKILL.md
skc deliver
Delivered all profiles: created 0, restored 1, replaced 0, updated 0, removed 0, failed 0.

An edit to a delivered file stays on one machine. In step 8, Dana makes the same change in the catalog, where everyone gets it.

6. Give a repository its own skills

The payments team wants its release-notes skill only in payments-api, so the Home profile is the wrong place for it. Dana first writes skills/release-notes/SKILL.md in the catalog and syncs it, as in step 3:

---
name: release-notes
description: Use when writing release notes for the payments API. Explains the format and what to include.
---

# Release notes

Write release notes for merchants who call the payments API:

- Start with changes that require action from merchants.
- Name every endpoint, field, and error code that changed.
- Link each change to its pull request.
skc sync --message "Add release notes skill"

To give the skill to everyone who works in payments-api, Dana lists it in a team manifest, a file committed in the repository. She starts by cloning the repository:

git clone git@github.com:acme/payments-api.git
cd payments-api

In her checkout, her clone of payments-api, she creates the team manifest:

skc init --catalog-id acme-skills --id payments-api --display-name "Payments API" --entry skill:acme-skills:release-notes

skc init writes the team manifest, .skillcatalog/skillcatalog.yml, and nothing else:

profile:
  id: payments-api
  display_name: Payments API
catalogs:
  acme-skills:
    source: git@github.com:acme/acme-skills.git
entries:
  - catalog_id: acme-skills
    kind: skill
    slug: release-notes
  • profile comes from --id and --display-name.
  • catalogs comes from --catalog-id, with the catalog's URL, so a teammate's install can clone the catalog.
  • entries comes from each --entry, written as kind, catalog id, and slug joined by colons.

The manifest only describes what the repository needs. skc install acts on it for this one checkout: it reads the team manifest and creates a project profile, which delivers into the checkout. Dana runs it:

skc install

The skill is now in payments-api/.claude/skills/release-notes/, so Claude Code finds it only in this repository. The review checklist from Dana's Home profile applies here too.

Every teammate's install writes its own copies of the delivered skills, so they do not belong in Git. Sam and others may use Cursor or Codex, so Dana adds every tool's skills folder to .gitignore:

.claude/skills/
.cursor/skills/
.agents/skills/

Then she commits the team manifest and .gitignore, and pushes them:

git add .gitignore .skillcatalog/skillcatalog.yml
git commit -m "Add SkillCatalog team manifest"
git push

7. Share the repository with a teammate

Sam joins the payments team. On his own machine, he clones payments-api, turns on Claude Code, and installs the repository's project profile:

git clone git@github.com:acme/payments-api.git
cd payments-api
skc settings enable claude-code
skc install
Cloning into 'payments-api'...
Enabled delivery target 'claude-code'.
Registered catalog 'acme-skills' from git@github.com:acme/acme-skills.git (declared in ~/payments-api/.skillcatalog/skillcatalog.yml).
Installed profile 'payments-api'.
Scoped delivery: created 1, restored 0, replaced 0, updated 0, removed 0, failed 0.

Sam never added acme-skills himself. The install read the catalog's URL from the team manifest, cloned it, and reported it on the Registered catalog line, then delivered release-notes into his checkout.

The review checklist did not arrive, because Dana added it to her own Home profile, and each person's Home profile lives on their own machine. Sam adds it to his:

skc profile add home --catalog-id acme-skills --kind skill --slug review-checklist

To give a skill to everyone who works in a repository instead, list it in that repository's team manifest.

8. Keep everyone up to date

The rollback check Dana tried in step 5 belongs in everyone's checklist. She adds it to the catalog's copy of the skill, in her clone, and syncs:

echo "- Database migrations can be rolled back." >> ~/.skillcatalog/catalogs/acme-skills/skills/review-checklist/SKILL.md
skc sync --message "Check that migrations can be rolled back"

Sam gets the change with his own sync, which pulls every catalog and delivers every profile on his machine:

skc sync
Synced 1 catalog (1 commit pulled, 0 commits pushed, 1 delivery).

Catalogs:
- Acme Skills (acme-skills): pull updated (1 commit pulled), push nothing to push - 1 update applied

Delivery report: created 0, restored 0, replaced 0, updated 1, removed 0, failed 0.
Delivered files:
  Acme Skills:
    - updated Review checklist -> Claude Code (~/.claude/skills/review-checklist/SKILL.md)

In the desktop app, open the Sync Center with the sync button at the top of the window, then choose Sync.

A change to the team manifest reaches Sam through the repository instead. When a teammate adds an entry to it, Sam pulls the repository and runs skc update, which updates this one checkout:

git pull
skc update

Where to go next

To see how the pieces you used fit together, read How SkillCatalog works. Then pick the guide for your next task:

Back to homepageQuestions? hi@skillcatalog.dev