# SkillCatalog

> The workspace for your team's AI skills.

SkillCatalog is a desktop app and CLI for managing, organizing, and delivering AI skills (prompt instructions) to tools like Claude Code, Cursor, and Codex. Skills are Markdown files with YAML frontmatter stored in Git-backed catalogs. The CLI (`skc`) handles catalog registration, local profile lifecycle, delivery-target settings, catalog inspection, delivery, validation, status reporting, scoring, proposal inspection, and improvement publish flows. Authoring and taxonomy changes stay in the desktop app and editor-agent workflows.

## Quick start

Install the desktop app from https://skillcatalog.dev, or use the CLI directly:

    skc catalog add <url>           # register a remote catalog
    skc catalog policy set <id> review-branch --primary main --review skillcatalog/review
                                      # publish SkillCatalog writes as review branches
    skc proposal list --catalog-id <id>
                                      # inspect pending proposal records
    skc install                     # install from .skillcatalog/skillcatalog.yml
    skc skill score <slug>          # score a directory-form skill
    skc skill improve <slug>        # preview a scored SKILL.md improvement
    skc skill improve <slug> --proposal-out <path>
                                      # write a reviewed proposal document
    skc skill improve --apply-proposal <path>
                                      # apply a reviewed proposal document
    skc skill publish-accepted --proposal <path> --message <msg>
                                      # commit and publish the accepted result
    skc status                      # view current state
    skc validate                    # check for issues
    skc help-json                   # full CLI reference as JSON

Most commands support `--json` for the standard JSON envelope, including `skill improve`. Parser failures also use that envelope when `--json` is present. Built-in help/version output, `help-json`, `completions`, successful `skill score`, and `skill score-history` output are raw.

Skills use the official Agent Skills directory form: `skills/{slug}/SKILL.md`. Optional scoring history is stored beside the skill in `skills/{slug}/SCORE.json` and is not delivered. Delivery rewrites `@skill:slug` references and expands `@skill-dir` inside delivered `SKILL.md`; companion files are copied byte-for-byte. Catalogs can use the default `direct` sync policy or `review-branch`, where SkillCatalog writes become isolated proposal branches with local records under `~/.skillcatalog/proposals/`.

Installed desktop builds register `skc://` links. Two routes are supported: `skc://catalog/add?source=<encoded-remote-git-url>[&name=<encoded-name>]` opens an Add catalog confirmation, and `skc://share/install?v=1&kind=<skill|stack|bundle>&catalog_id=<id>&slug=<slug>&source=<encoded-remote-git-url>` opens an install confirmation for one shared catalog item. Both wait for confirmation before any clone, registry write, or profile change, and the source follows the same remote-only rules as `skc catalog add`. Share install rechecks the moving source before profile mutation and rejects source drift, unsafe paths, dirty existing clones, wrong branches, non-fast-forward divergence, or incomplete tracked worktrees.

## Links

- Full agent reference: https://skillcatalog.dev/llms-full.txt
- Agent integration docs: https://skillcatalog.dev/docs/agent-integration
- Human documentation: https://skillcatalog.dev/docs
- JSON schema index: https://skillcatalog.dev/schemas/index.json
  - Skill frontmatter: https://skillcatalog.dev/schemas/skill-frontmatter.schema.json
  - Stack: https://skillcatalog.dev/schemas/stack.schema.json
  - Bundle: https://skillcatalog.dev/schemas/bundle.schema.json
  - Catalog metadata: https://skillcatalog.dev/schemas/catalog.schema.json
  - Committed project manifest (.skillcatalog/skillcatalog.yml): https://skillcatalog.dev/schemas/skillcatalog-yml.schema.json
  - Local project manifest (.skillcatalog/skillcatalog.local.yml): https://skillcatalog.dev/schemas/skillcatalog-local-yml.schema.json

Fetch the index at its explicit path. The bare /schemas/ directory has no
listing and falls through to the site's HTML shell with HTTP 200.