Give a repository its own skills

In Getting started, Dana committed a team manifest to payments-api that lists release-notes, and Sam installed it in his checkout. This page continues from there. The payments team adds a skill from a second catalog, Sam makes changes that only he gets, and Dana uses the same skills in a second checkout and in a folder that has no manifest.

You manage team manifests with skc. The desktop app shows project profiles and can make your personal changes to them, but it cannot create or install a team manifest.

Add skills to a team manifest

skc init created the payments-api team manifest in Getting started. It writes a new manifest only and refuses to change one that exists, so to add skills later, you edit the file.

The payments team wants the platform team's incident-response skill for everyone on call. Dana declares the platform-skills catalog under catalogs: and adds its entry under entries:, so .skillcatalog/skillcatalog.yml reads:

profile:
  id: payments-api
  display_name: Payments API
catalogs:
  acme-skills:
    source: git@github.com:acme/acme-skills.git
  platform-skills:
    source: git@github.com:acme/platform-skills.git
entries:
  - catalog_id: acme-skills
    kind: skill
    slug: release-notes
  - catalog_id: platform-skills
    kind: skill
    slug: incident-response

• Every catalog that an entry uses needs a line under catalogs: with its URL, so that a teammate's install can clone it.
• The key under catalogs: and each entry's catalog_id are the catalog id, the same on every machine.

Before she commits, Dana tries the change in her own checkout:

skc update

Dana removed the platform catalog from her machine earlier, so skc update clones and adds it again from the manifest's URL, then delivers incident-response into the checkout. If an entry names a skill that its catalog does not have, skc update fails and delivers nothing into the checkout, so a misspelled slug shows up here before it reaches the team. Dana commits and pushes the manifest:

git add .skillcatalog/skillcatalog.yml
git commit -m "Add incident-response for on-call"
git push

Keep delivered files out of Git

In Getting started, Dana added each tool's skills folder to the repository's .gitignore. Those folders stay out of Git because every teammate's install writes its own copies, and the copies differ between machines: a delivered SKILL.md in a checkout can hold absolute paths, such as the path of a script. Install also refuses to take over skill folders it did not write, even identical ones, so committed copies would make every teammate's install fail.

SkillCatalog also keeps two files of its own for personal changes, which the sections below cover. It adds them to .gitignore the first time someone makes a personal change in a checkout, which leaves .gitignore modified in that person's checkout. Dana adds the two lines now and commits them, so SkillCatalog finds them already there and everyone's git status stays clean:

.skillcatalog/skillcatalog.local.yml
/.skillcatalog/.skc-recovery/

If the repository already commits its own skills in a tool's skills folder, ignore each delivered skill folder instead of the whole skills folder, such as .claude/skills/release-notes/.

Update a checkout

When a teammate changes the team manifest, everyone else pulls the change and updates their checkout. Sam does both in payments-api:

git pull
skc update

Registered catalog 'platform-skills' from git@github.com:acme/platform-skills.git (declared in ~/payments-api/.skillcatalog/skillcatalog.yml).
Updated profile 'payments-api'.
...
Scoped delivery: created 1, restored 0, replaced 0, updated 0, removed 0, failed 0.

The manifest names a catalog that Sam had not added, so skc update cloned and added it, as a first install does, and then delivered incident-response.

Run skc update at the top of the checkout, in the folder that holds .skillcatalog/, because it does not look for a manifest in parent folders. Sync or update? compares it with skc sync.

Make personal changes

Sam reviews security changes and wants review-security in payments-api, but he does not write release notes. Neither change suits the whole team, so he makes them for himself. On a project profile, skc profile add and skc profile remove leave the team manifest alone. They write to your local manifest, .skillcatalog/skillcatalog.local.yml, a file in your checkout that Git ignores.

Both commands take the profile id, payments-api, which is the id under profile: in the team manifest:

skc profile add payments-api --catalog-id acme-skills --kind skill --slug review-security
skc profile remove payments-api --catalog-id acme-skills --kind skill --slug release-notes

Both commands deliver at once. Sam's local manifest now holds his entry and an exclusion, which leaves a team manifest entry out of delivery for him:

catalogs:
  acme-skills:
    source: git@github.com:acme/acme-skills.git
entries:
  - catalog_id: acme-skills
    kind: skill
    slug: review-security
excludes:
  - catalog_id: acme-skills
    kind: skill
    slug: release-notes

Dana and the rest of the team still get release-notes, because the team manifest did not change. An exclusion leaves out the whole team entry, so excluding a stack drops every skill in it. To keep one of those skills, add it as your own entry. To undo an exclusion, delete it from excludes: and run skc deliver payments-api.

In the desktop app, open Profiles and choose the project profile. The minus button next to an entry under Inherited from the team manifest excludes it, and Add to profiles on a skill, stack, or bundle page adds your own entry.

See what a project delivers

With entries from two files, Sam wants to see what his checkout gets now:

skc profile show payments-api --effective

Profile 'payments-api' (Payments API)
...
Local manifest entries:
1. skill:review-security@acme-skills
Team manifest entries:
1. skill:release-notes@acme-skills (excluded by local manifest)
2. skill:incident-response@platform-skills
Effective entries:
1. skill:review-security@acme-skills (local)
2. skill:incident-response@platform-skills (team)

The effective entries are what delivery uses, top entry first. Your own entries come before the team's, so yours wins when both deliver a skill with the same slug. If you add an entry that the team also has, the team's entry is marked (shadowed by local entry), and yours stays even if the team later removes theirs.

Use the skills in a second checkout

Dana starts a hotfix in a Git worktree, a second checkout of the repository. A project profile belongs to one checkout, so skc install in the worktree stops:

git worktree add ../payments-api-hotfix
cd ../payments-api-hotfix
skc install

Error: profile-id-conflict
profile id 'payments-api' already belongs to '~/payments-api', not '~/payments-api-hotfix'.
...

Instead, Dana points the existing project profile at the worktree. She runs this in payments-api:

cd ../payments-api
skc install --target-dir ../payments-api-hotfix

SkillCatalog moves the delivered skills out of payments-api and into each tool's skills folder under payments-api-hotfix, which must already exist. It saves that folder with the project profile, so later installs, updates, and deliveries write there too. The manifests still come from payments-api, so Dana keeps running skc update there, not in the worktree.

When the hotfix is merged, Dana moves the skills back before she deletes the worktree:

skc install --target-dir .

If the saved folder is deleted first, delivery skips the profile and says so until you run this command.

Use a personal profile

Dana wants release-notes in ~/code/spikes, a folder of experiments, but not in every repository. That folder has no team manifest, so she creates a personal profile, which delivers to one folder and exists only on her machine:

skc profile create "Spikes" ~/code/spikes --entry skill:acme-skills:release-notes
skc deliver spikes

Created profile 'spikes' (Spikes) at ~/code/spikes.
Delivered profile 'spikes': created 1, restored 0, replaced 0, updated 0, removed 0, failed 0.

The profile id, spikes, comes from the name. skc profile create does not deliver, so Dana runs skc deliver spikes once. After that, skc sync and skc deliver keep the folder up to date like any other profile.

The folder must exist, and it can have only one profile. For a checkout that already has a project profile, use your local manifest instead. skc profile delete spikes removes the profile and the skills it delivered, except files you edited.

In the desktop app, open Profiles, choose New profile, enter a Profile name, pick the folder with Choose, then choose Create profile.

Remove a project profile

Sam moves to another team and no longer needs the payments skills in his checkout. skc uninstall deletes the project profile and the skills it delivered, including any in a folder saved with --target-dir. It keeps both manifests and your catalogs:

skc uninstall

Removed profile 'payments-api'.
Cleanup: removed 2, failed 0.

Files you edited stay, listed under Preserved edited files, not removed:. SkillCatalog remembers them, so a later skc install in the same checkout keeps your edits. skc profile delete payments-api does the same as skc uninstall, from any folder.