Write skills

In Getting started, Dana wrote review-checklist by hand and synced it. Pull requests that touch payments need more than that checklist, so she now writes a security review, review-security. It comes with a script that finds likely secrets in a change, and it builds on the checklist instead of repeating it. At the end, she groups both skills in a code-review stack, so that one profile entry delivers both.

This page follows that skill from its first draft to the commit that shares it. The last section shows how Sam brings in a skill he wrote before Acme used SkillCatalog.

Write a skill by hand

Dana works in her clone of the catalog, ~/.skillcatalog/catalogs/acme-skills, where she wrote the checklist. She creates skills/review-security/SKILL.md:

---
name: review-security
description: Use when a pull request touches authentication, payments, or personal data. Adds security checks to the Acme review.
---

# Security review

Check that:

- Every new endpoint checks who is calling it.
- User input is validated before it reaches a query or a shell command.
- Card numbers, tokens, and passwords never appear in logs.
- API keys expire after 90 days, as required since 2026-07-01.

name and description are the only required fields. AI tools read description to decide when to use the skill, so Dana names the pull requests it applies to.

Dana wants to try the skill in her own tools before her teammates get it. Delivery reads the files in her clone whether or not she has synced them, so she adds the skill to her Home profile now:

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

The skill stays on her machine until she syncs, so she can keep changing it while she tries it.

Write a skill in the desktop app

The desktop app offers a second way to start a skill. Open Skills, choose New skill, fill in Display name, Description, and Content, then choose Create skill. The editor makes the slug from the display name and writes the same SKILL.md, with the display name, your Git name as author, and the dates added under metadata.

The two paths differ in when the skill leaves your machine. Create skill saves the skill: SkillCatalog commits and pushes it at once, then delivers your profiles again, so there is nothing to sync. The editor writes only SKILL.md, so you add scripts and other files in the clone, as the next section shows.

To change a skill later, open it and choose Edit. Save changes asks for a Change description, which becomes part of the commit message. The skill's History tab lists the last 50 commits that changed its SKILL.md, each with its diff.

Add scripts and other companion files

Dana's script lives next to SKILL.md, in skills/review-security/scripts/find-secrets.sh. Any file in a skill's folder other than SKILL.md is a companion file, like a script, a template, or a longer reference document. Delivery copies companion files with the skill, so the AI tool can open or run them.

To run the script, the tool needs its path, and that path differs for each tool and each checkout. Dana writes @skill-dir in its place, in a new line at the end of SKILL.md:

To list added lines that look like secrets, run `bash "@skill-dir/scripts/find-secrets.sh" main`.

Delivery replaces @skill-dir in SKILL.md with the absolute path of the folder it delivers the skill to. It copies companion files as they are and replaces nothing in them. Dana delivers again to see the result:

skc deliver

Delivered all profiles: created 1, restored 0, replaced 0, updated 1, removed 0, failed 0.

created 1 is the script, which was not delivered before.
updated 1 is SKILL.md, which gained the new line.

In Dana's Claude Code copy, the line now reads:

To list added lines that look like secrets, run `bash "/Users/dana/.claude/skills/review-security/scripts/find-secrets.sh" main`.

Keep the quotes around the path, because a checkout's folder name can contain a space, such as ~/Code Projects/payments-api.

Delivery keeps a script's executable bit. It never copies a symbolic link, and it skips any skill whose folder holds one, so copy a shared script into the skill's folder instead of linking to it.

Refer to other skills

The security review builds on the checklist. A copy of the checklist's text would have to be kept in step with the original, so Dana refers to the skill instead, with @skill: followed by its slug. She changes the line Check that: to:

Work through @skill:review-checklist first. Then check that:

Delivery replaces the reference with the path where the same profile delivers the checklist for the same tool. After skc deliver, the line in Dana's Claude Code copy reads:

Work through ~/.claude/skills/review-checklist/SKILL.md first. Then check that:

The skill you refer to must be in the same catalog. skc validate, described below, reports a reference to a skill that the catalog does not have, such as a misspelled slug.

A reference is only a path, so it works only when the profile also delivers the skill it names. Dana's Home profile has the checklist, but a teammate who adds only review-security would get a path to a file that is not there. The next section fixes that.

Group skills into stacks and bundles

Anyone who adds the security review also needs the checklist. A stack is an ordered list of skills that a profile selects with one entry, so Dana puts both skills in a code-review stack. She creates stacks/code-review.yaml:

---
name: Code review
description: The checks every Acme pull request review covers.
author: Dana Reyes
created_at: "2026-09-23T09:00:00Z"
updated_at: "2026-09-23T09:00:00Z"
---
skills:
  - review-checklist
  - review-security

The file name, without .yaml, is the stack's slug.
The front matter between the --- lines needs description, author, and both dates. name is the display name.
skills lists skills from the same catalog, in the order they are delivered.

A stack must also include every skill that its skills refer to, so that each @skill: path points to a delivered file wherever the stack goes. If Dana left out review-checklist, skc validate would fail.

A bundle is the same idea one level up: a file bundles/<slug>.yaml with the same front matter, which lists stacks under stacks:. Acme can use one later for everything a new reviewer needs.

In the desktop app, open Stacks, choose New stack, then choose Create stack. A stack reaches your tools only when a profile selects it, which Choose the skills your tools get covers.

Organize with categories, owners, and tags

As Acme's catalog grows, Dana wants people to find skills on the desktop app's Skills page, which filters by category, owner, and tag. A skill can use only the values its catalog declares, so she first declares them in catalog.yaml, at the top of the clone:

id: acme-skills
name: Acme Skills
taxonomy:
  categories:
    - slug: security
      name: Security
  owners:
    - slug: platform
      name: Platform team
  tags:
    - security
    - review

Then she adds them under metadata in the front matter of review-security. The tags are a JSON list written inside a YAML string, so keep the quotes:

metadata:
  skillcatalog/category: security
  skillcatalog/owner: platform
  skillcatalog/tags: '["security", "review"]'

A value that catalog.yaml does not declare makes skc validate fail.

In the desktop app, open Taxonomies to declare categories, owners, and tags, then pick them in the skill editor.

Dana's changes are ready, and her SKILL.md now reads:

---
name: review-security
description: Use when a pull request touches authentication, payments, or personal data. Adds security checks to the Acme review.
metadata:
  skillcatalog/category: security
  skillcatalog/owner: platform
  skillcatalog/tags: '["security", "review"]'
---

# Security review

Work through @skill:review-checklist first. Then check that:

- Every new endpoint checks who is calling it.
- User input is validated before it reaches a query or a shell command.
- Card numbers, tokens, and passwords never appear in logs.
- API keys expire after 90 days, as required since 2026-07-01.

To list added lines that look like secrets, run `bash "@skill-dir/scripts/find-secrets.sh" main`.

Before she shares anything, she checks her work:

skc validate

Info: validate
Selected checks: catalog, profiles, settings, drift
Diagnostics: 1
- [validation.time-sensitive.outside-old-patterns] catalog '~/.skillcatalog/catalogs/acme-skills' skill 'review-security' validation: validation.time-sensitive.outside-old-patterns (line 17-17): Review whether this date or version still describes the intended guidance; explicit dates and version pins may be appropriate.
...

skc validate checks every catalog you added, as well as your profiles, settings, and delivered files. An error, such as a reference to a skill that does not exist, makes the command fail, and so does a warning. Information, like this finding about the date on line 17, never does. The same catalog checks run before each commit that skc sync or a desktop save makes, and an error stops the commit, so an error that skc validate reports now would stop Dana's sync later.

Four of the content checks, including this one, are advice that you can turn off. Dana's date is deliberate, so she turns off the date check for this skill with one more line under metadata. The value is a JSON object written inside a YAML string:

metadata:
  skillcatalog/category: security
  skillcatalog/owner: platform
  skillcatalog/tags: '["security", "review"]'
  skillcatalog/validation: '{"validation.time-sensitive.outside-old-patterns": false}'

To turn a check off for every skill in the catalog, put its check id in a validation: map in catalog.yaml instead. A skill's own setting wins over the catalog's.

skc validate no longer reports the date. Dana shares the skill, its script, the stack, and the new categories, owners, and tags in one commit:

skc sync --message "Add security review and code-review stack"

Her teammates get all of it at their next sync, and each of them chooses whether to add the stack to a profile.

Bring existing skills into a catalog

Sam kept skills by hand in ~/.claude/skills/ before Acme used SkillCatalog. To share his write-migrations skill, he copies its folder into his clone of the catalog, checks it, and syncs:

cp -R ~/.claude/skills/write-migrations ~/.skillcatalog/catalogs/acme-skills/skills/
skc validate
skc sync --message "Add write-migrations"

skc validate tells him if the skill needs changes first, such as a name that does not match its folder.

His original folder is still in ~/.claude/skills/, and delivery never overwrites a folder that SkillCatalog did not write. If he added the skill to his Home profile now, delivery would keep his old copy and report the skill as failed. So he moves the original out of the way first, then adds the skill:

mv ~/.claude/skills/write-migrations ~/write-migrations.bak
skc profile add home --catalog-id acme-skills --kind skill --slug write-migrations

His tools now read the catalog's copy, which his teammates can add to their own profiles.