File formats

This page lists the files SkillCatalog reads, their fields, and the rules and limits it enforces. skc validate --path <folder> checks a catalog folder against these rules, and skc validate --manifest checks the team manifest in the current folder. JSON schemas describe the same shapes for editors and other tools. See skillcatalog.dev/schemas/index.json.

Skill folders

Each skill is a folder, skills/<slug>/, named after the skill's slug. It holds a SKILL.md and any companion files: every other file in the folder, such as a template or a script.

skills/
  review-checklist/
    SKILL.md
    templates/
      review-comment.md

SKILL.md starts with YAML front matter between two --- lines, followed by the Markdown body. Its schema is skill-frontmatter.schema.json.

---
name: review-checklist
description: Checklist for reviewing a pull request at Acme. Use when reviewing code changes.
metadata:
  skillcatalog/category: quality
  skillcatalog/owner: platform
  skillcatalog/tags: '["review"]'
---

# Review checklist

1. Read the pull request description.
2. Check that tests cover the change.
3. Use the comment template in @skill-dir/templates/review-comment.md.

SkillCatalog ignores other top-level fields. It does not deliver them, and the desktop app removes them when it saves the skill.

Any other key that starts with skillcatalog/ is an error. The body can be empty and is at most 1 MiB (1,048,576 bytes).

Each delivered SKILL.md gets new front matter with name, description, license, compatibility, allowed-tools, and metadata. In that copy only, SkillCatalog fills in skillcatalog/display_name, skillcatalog/created_at, and skillcatalog/updated_at when the source lacks them. Delivery also replaces two tokens in the body of SKILL.md, not in companion files:

SkillCatalog recognizes @skill:<slug> at the start of the body, after a space, tab, or line break, and right after one of (, [, {, ", ', <, code blocks included. After any other character, such as a backtick or the * of bold text, the text stays as written and is not checked. skc validate reports a reference to a skill that the catalog does not have, and a skill that refers to itself.

SkillCatalog replaces @skill-dir wherever no letter, digit, -, or _ touches it, even inside backticks, so @skill-directory and user@skill-dir stay as written. See Refer to other skills.

To write either token as text, put a backslash before it: \@skill-dir and \@skill:<slug>. Delivery removes the backslash and replaces nothing, so the delivered copy shows @skill-dir and @skill:<slug>, and skc validate does not check an escaped reference. A backslash before any other text stays as written.

Delivery copies companion files byte for byte and keeps their executable bit. It never copies a symbolic link: when a skill folder holds one anywhere, delivery withholds that skill, leaves its delivered files as they are, delivers the other skills, and reports the skill as failed. skc validate reports the link as an error. See A skill folder holds a symbolic link.

A special file, such as a named pipe, or a file over 10 MiB in a skill folder stops the whole delivery run until you remove it, and skc validate reports neither. Delivery skips these files:

If Git ignores the SKILL.md itself, delivery stops with an error. See Add scripts and other companion files.

Stack files

A stack is a file stacks/<slug>.yaml. SkillCatalog reads only files that end in .yaml and skips a .yml file without a message. The file holds front matter between --- lines, then a YAML body with the list of skills. Its schema is stack.schema.json.

---
name: Code review
description: Skills for reviewing Acme pull requests.
author: Dana Reyes
owner: platform
tags: [review]
created_at: 2026-09-23T09:00:00Z
updated_at: 2026-09-23T09:00:00Z
---
skills:
  - review-checklist
  - review-security

When a skill in the stack refers to another skill with @skill:, that skill must be in the stack too. Other fields are ignored.

Bundle files

A bundle is a file bundles/<slug>.yaml with the same layout as a stack. It lists stacks in its body and has no tags. Its schema is bundle.schema.json.

---
name: Reviewers
description: Everything an Acme reviewer needs.
author: Dana Reyes
created_at: 2026-09-23T09:00:00Z
updated_at: 2026-09-23T09:00:00Z
---
stacks:
  - code-review

name, description, author, owner, created_at, and updated_at follow the stack rules. stacks lists stacks of the same catalog: at least one, no duplicates. Each of those stacks must include, on its own, every skill that its skills refer to.

A skill, a stack, and a bundle in one catalog cannot share a slug. See Group skills into stacks and bundles.

catalog.yaml

catalog.yaml sits at the root of a catalog. Its schema is catalog.schema.json.

id: acme-skills
name: Acme Skills
description: Review and release skills for Acme engineers.
taxonomy:
  categories:
    - slug: quality
      name: Quality
      children:
        - slug: security
          name: Security
  owners:
    - slug: platform
      name: Platform team
  tags: [review, release]
validation:
  validation.body.too-long: false
metrics_url: http://metrics.acme.internal:9090/api/v1/otlp/v1/metrics

In taxonomy, each category and owner has a slug and a name, and may have children one level deep. Slugs cannot repeat within categories or within owners.

tags is a list of names, and each name becomes a slug: Code Review becomes code-review. Two names cannot give the same slug, and skills and stacks refer to tags by slug. SkillCatalog ignores other keys, including categories, owners, or tags placed outside taxonomy.

A metrics_url is valid when it starts with http:// or https://, names a host, has a path that ends in /v1/metrics, has no user name, password, query, fragment, or surrounding spaces, and is at most 2,048 bytes. A blank value, null, or no key means the catalog has no address. SkillCatalog ignores any other value, such as a list or an address that breaks a rule: the catalog stays readable, no counts are sent for it, and skc validate --path warns about it. See Collect usage counts for your catalog.

A catalog also needs a skills/ folder next to catalog.yaml. Git does not keep empty folders, so keep a file such as .gitkeep in it. A registered catalog whose clone lacks skills/ cannot be read. stacks/ and bundles/ are optional: a missing one counts as empty. When present, none of the three can be a symbolic link or a file. README.md is optional.

Content checks

skc validate runs these four checks on every skill:

All four run by default. false turns a check off, and true turns it back on for a skill in a catalog that turned it off. A skill's skillcatalog/validation metadata wins over the catalog's validation map. An unknown check id makes catalog.yaml unreadable, and a skill with one fails skc validate.

skc validate also runs validation.conflict-markers, which cannot be turned off. It reports an error for a leftover Git conflict block in a SKILL.md: a <<<<<<< line, then a ======= line, then a >>>>>>> line, each marker at the start of its line. A <<<<<<< line inside a fenced code block starts no block, so marker examples belong in fenced code, and a real conflict inside a fenced code block goes unreported. The check reads only SKILL.md, not companion files. See A commit stops on leftover conflict markers.

See Check a skill before you share it.

Team manifest

The team manifest is .skillcatalog/skillcatalog.yml in a repository. It lists the entries that repository wants for everyone. Its schema is skillcatalog-yml.schema.json.

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

Unknown keys make the manifest invalid. SkillCatalog also reads a skillcatalog.yml at the repository root when .skillcatalog/skillcatalog.yml does not exist. When both exist, skc install, skc update, and skc update --check fail. skc init refuses to write when either file exists.

skc init writes this file from its flags. It pairs each --source with the --catalog-id in the same position. A --catalog-id without a paired --source uses the URL registered for that catalog. See Add skills to a team manifest.

Local manifest

The local manifest is .skillcatalog/skillcatalog.local.yml: your own additions and exclusions for one checkout. SkillCatalog adds it to the checkout's .gitignore when it first writes it. Every key is optional. Its schema is skillcatalog-local-yml.schema.json.

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

Unknown keys make the file invalid. A skillcatalog.local.yml at the repository root is read when this file does not exist. Both at once is an error. See Make personal changes.

settings.toml

~/.skillcatalog/settings.toml holds your settings. SkillCatalog creates it when you first change a setting, and you may edit it by hand. SkillCatalog ignores keys it does not know and keeps them when it saves the file.

[targets.claude_code]
enabled = true

[targets.cursor]
enabled = false

[targets.codex]
enabled = false

[scoring.enabled_providers.claude-code-local]
enabled = true
model = "sonnet"
effort = "high"

[proposals]
archive_retention_days = 30
remote_only_discovery_cap = 200

[telemetry]
enabled = false

A [proposals] table must hold both of its keys, because with only one, every command that reads settings fails. SkillCatalog ignores a theme key.

skc links

The desktop app opens two kinds of skc:// links. Values in a link are URL-encoded. A fragment, a repeated parameter, or a parameter not listed here makes a link invalid.

For example, these links add the Acme catalog and install its review checklist:

skc://catalog/add?source=git%40github.com%3Aacme%2Facme-skills.git&name=Acme%20Skills
skc://share/install?v=1&kind=skill&catalog_id=acme-skills&slug=review-checklist&source=git%40github.com%3Aacme%2Facme-skills.git

The desktop app makes share links for skills, stacks, and bundles. No command makes catalog links, so write them yourself. See Share with a link.

Names and limits

Reading a symbolic link, a special file, or a file with more than one hard link inside a catalog fails.