# SkillCatalog: Full Agent Reference > The workspace for your team's AI skills. SkillCatalog manages AI skills (prompt instructions stored as Markdown files with YAML frontmatter) in Git-backed catalogs. A desktop app handles interactive authoring. The CLI (`skc`) handles catalog registration, profile management, delivery, validation, and status reporting. Skills are delivered to AI tools (Claude Code, Cursor, Codex) as SKILL.md files in tool-specific directories. ## CLI reference Binary: `skc` ### Global options (available on every command) --json Render output as JSON when the command supports it. --quiet Suppress non-essential command output. --config-dir PATH Override the SkillCatalog configuration root directory. ### Commands #### skc init Alias for `skc profile init`. Scaffold a committed `skillcatalog.yml` in the current directory. Fails if one already exists. --source SOURCE Remote Git URL via SSH (git@host:path), ssh://, or HTTP(S). --catalog-alias ALIAS Alias key to write into the manifest's catalogs block. --id SLUG Stable committed profile id. --display-name NAME Human-readable profile display name. --entry KIND:SLUG Initial entry (repeatable). KIND is skill, stack, or bundle. #### skc install Alias for `skc profile install`. Reads `skillcatalog.yml` from the current directory only (no parent search). Creates or refreshes the local child profile, then runs scoped delivery. No additional arguments. #### skc uninstall Alias for `skc profile uninstall`. Removes the local profile for the current checkout and cleans up delivered files. No additional arguments. #### skc update Refresh the current directory's manifest-linked catalogs and installed profile. Reads `skillcatalog.yml` from the current directory only. Never performs an implicit install or broadens into a global sync. No additional arguments. #### skc profile init Same as `skc init`. See above. #### skc profile install Same as `skc install`. See above. #### skc profile uninstall Same as `skc uninstall`. See above. #### skc profile deliver [PROFILE_ID] Deliver profile content to enabled target directories. Without PROFILE_ID, delivers every profile. With PROFILE_ID, delivers only that profile. PROFILE_ID Optional positional argument. Deliver only this profile. --dry-run Compute the delivery report without writing files. --check Check for drift only. Returns non-zero exit if drift exists. #### skc catalog add URL Register and clone a catalog from a remote Git URL. URL Positional argument. The catalog source URL. #### skc catalog remove ID Unregister a catalog by its registered id. ID Positional argument. The catalog id to remove. --keep-clone Leave the existing clone directory on disk. #### skc catalog sync [CATALOG_ID...] Pull upstream changes for all registered catalogs (or a subset) and rerun delivery unless --no-deliver is set. CATALOG_ID Optional positional arguments. Limit sync to these catalogs. --no-deliver Skip the follow-on delivery pass after pulling. #### skc validate Validate managed local state and the current checkout manifest. By default runs all checks. Use flags to scope. --drift Run only drift checks. --settings Run only settings-file checks. --profiles Run only local profile-file checks. --manifest Run only committed-manifest checks. --path PATH Limit validation to a specific checkout or catalog path. --no-drift Skip drift checks (conflicts with --drift). #### skc status Summarize registered catalogs, local profiles, enabled targets, and drift. No additional arguments. #### skc completions SHELL Generate shell completion scripts. SHELL Positional argument: bash, zsh, fish, or powershell. #### skc help-json Dump the full CLI command tree as structured JSON. Useful for programmatic discovery of all commands, arguments, types, and descriptions. No additional arguments. Always outputs JSON regardless of --json flag. ## Exit codes Exit 0 means success. Non-zero exit codes are command-specific: 10 User input error (invalid argument, non-canonical checkout path) 11 Manifest malformed (skillcatalog.yml parse error) 12 Manifest path not canonical 13 Manifest reference missing (entry slug not found in catalog) 14 Manifest reference wrong kind 15 No profile at checkout / missing install state 16 Catalog source invalid / installed profile missing 17 Catalog not found / missing registered catalog source 18 Manifest already exists / manifest profile mismatch 19 Manifest missing (no skillcatalog.yml in current directory) 20 Install path conflict (two profiles write to the same path) 21 Profile id conflict 22 Catalog removed (registered catalog no longer exists) 23 Catalog clone unreadable / registered catalog unreadable 24 Profile write failed 25 Delivery failed 26 Drift detected (with --check) 27 Manifest write failed 28 Manifest malformed (delivery context) 29 Checkout directory conflict 30 Local state validation failure 31 Manifest validation failure 32 Inconsistent state (status command) 40 Catalog clone failed (git clone error) 41 Sync partial failure (one or more requested catalogs failed to pull) 42 Catalog refresh failed 43 Delivery I/O error 44 Sync all failed (every requested catalog failed to pull) 70 Internal error In --json mode, errors are returned as: {"outcome": "...", "message": "...", "exit_code": N} ## File formats ### Skill file (skills/{slug}.md) A Markdown file with YAML frontmatter. The body is plain Markdown. Cross-references to other skills use the syntax @skill:other-slug. --- name: "My Skill" description: "One-sentence summary of what this skill does." category: "my-category" owner: "my-team" author: "Jane Doe" tags: ["debugging", "testing"] created_at: "2026-01-15T10:00:00Z" updated_at: "2026-01-15T10:00:00Z" --- Skill body in Markdown. Can reference other skills with @skill:other-slug. Required fields: description, created_at, updated_at. Optional fields: name (defaults to slug), category, owner, author, tags. JSON schema: https://skillcatalog.dev/schemas/skill-frontmatter.schema.json ### Stack file (stacks/{slug}.yaml) YAML frontmatter followed by a YAML body with a skills array. --- name: "My Stack" description: "Groups related skills together." tags: ["workflow"] owner: "my-team" author: "Jane Doe" created_at: "2026-01-15T10:00:00Z" updated_at: "2026-01-15T10:00:00Z" --- skills: - skill-one - skill-two - skill-three Required fields: name, description, created_at, updated_at, skills. Additionally required at validation time: author. Optional fields: tags, owner. JSON schema: https://skillcatalog.dev/schemas/stack.schema.json ### Bundle file (bundles/{slug}.yaml) YAML frontmatter followed by a YAML body with a stacks array. --- name: "My Bundle" description: "Packages stacks for distribution." owner: "my-team" author: "Jane Doe" created_at: "2026-01-15T10:00:00Z" updated_at: "2026-01-15T10:00:00Z" --- stacks: - stack-one - stack-two Required fields: name, description, created_at, updated_at, stacks. Additionally required at validation time: author. Optional fields: owner. JSON schema: https://skillcatalog.dev/schemas/bundle.schema.json ### Catalog metadata (catalog.yaml) Root file of a catalog repository. Defines catalog identity and taxonomy. name: "My Team Catalog" description: "Shared skills for the engineering team." taxonomy: categories: - slug: "debugging" name: "Debugging" children: - slug: "rust-debugging" name: "Rust Debugging" - slug: "testing" name: "Testing" owners: - slug: "platform" name: "Platform Team" tags: - "performance" - "security" - "workflow" Required fields: name. Optional fields: description, taxonomy. Category and owner nesting: max depth 2 (root + one child level). JSON schema: https://skillcatalog.dev/schemas/catalog.schema.json ### Project manifest (skillcatalog.yml) Committed to the project repository root. Declares the project's catalog references and entries. A single profile can mix entries from any number of registered catalogs by declaring multiple aliases in the catalogs block. profile: id: "my-project" display_name: "My Project" catalogs: shared: source: "git@github.com:myteam/skills.git" reviews: source: "https://github.com/myorg/review-skills.git" entries: - catalog: "shared" kind: "bundle" slug: "core-bundle" - catalog: "shared" kind: "stack" slug: "debugging-stack" - catalog: "reviews" kind: "bundle" slug: "reviewer" Required fields: profile (id, display_name), catalogs, entries. Entry kinds: skill, stack, bundle. Profile id must not be "home" (reserved for the global home profile). Each entry must name a catalog alias declared in the catalogs block. Catalog references in a committed manifest use source: only; id: is rejected (catalog UUIDs are local-machine artifacts and cannot travel). No duplicate entries with the same catalog, kind, and slug. No duplicate source values across aliases in the same catalogs block. Strict schema: unknown fields are rejected. Child profiles (local profile.yml under ~/.skillcatalog/profiles//) inherit the parent manifest's alias namespace and may add their own aliases. Declaring an alias in both parent and child is a hard validation error (profile-alias-conflict), even when both resolve to the same source. An entry tagging an alias that is not in the composed namespace is rejected as profile-alias-undeclared. JSON schema: https://skillcatalog.dev/schemas/skillcatalog-yml.schema.json ## Catalog directory structure my-catalog/ catalog.yaml skills/ my-skill.md another-skill.md stacks/ my-stack.yaml bundles/ my-bundle.yaml ## Slug conventions All slugs (skill, stack, bundle, category, owner, profile id): - Start with a lowercase letter. - Contain only lowercase letters, digits, and hyphens. - No trailing or consecutive hyphens. - Pattern: ^[a-z][a-z0-9-]*$ ## Cross-references Skill bodies can reference other skills with @skill:slug-name. These references are validated against catalog content and resolved during delivery. ## Delivery paths Skills are delivered as SKILL.md files to tool-specific directories: Claude Code (home profile): ~/.claude/skills/{slug}/SKILL.md Claude Code (project profile): {checkout}/.claude/skills/{slug}/SKILL.md Cursor (home profile): ~/.cursor/skills/{slug}/SKILL.md Cursor (project profile): {checkout}/.cursor/skills/{slug}/SKILL.md Codex (home profile): ~/.agents/skills/{slug}/SKILL.md Codex (project profile): {checkout}/.agents/skills/{slug}/SKILL.md Delivered files have simplified YAML frontmatter (name and description only) followed by the skill body with cross-references resolved. Do not edit delivered files directly. They are overwritten on the next delivery. ## Local state directory ~/.skillcatalog/ settings.toml App settings and delivery-target toggles catalogs/ catalogs.yml Catalog registry my-catalog/ Cloned catalog repo profiles/ home/ profile.yml Home profile metadata delivery-manifest.json Delivery tracking my-project/ profile.yml Project profile metadata delivery-manifest.json Delivery tracking ## Environment variables SKILLCATALOG_LOG Tracing filter directive (e.g., skillcatalog_infrastructure=debug) GIT_TIMEOUT_LOCAL Timeout for local git operations (seconds) GIT_TIMEOUT_NETWORK Timeout for network git operations (seconds) ## Embedded catalog The desktop app ships with a built-in catalog named SkillCatalog Essentials (catalog id: skillcatalog-essentials). It is cloned into ~/.skillcatalog/catalogs/skillcatalog-essentials/ on first launch, never pulled from a network, and updates only with new app releases. The Essentials catalog contains three stacks: sc-guide Evergreen concept skills that teach agents what SkillCatalog is. Delivered by default. sc-authoring Schemas, authoring workflows, validation rules, and scaffolding commands. Delivered by default. sc-operate Local profile, settings, catalog, and delivery-target management. Not delivered by default. The default first-launch bundle is `sc-essentials`, which delivers `sc-guide` and `sc-authoring`. Users who also want `sc-operate` can choose the catalog-wide `sc-everything` bundle. The embedded catalog is a read-only source to user code; its content is refreshed from the app bundle whenever the installed version changes. ## Common agent workflows ### Install a project profile cd /path/to/project skc profile install --json ### Add a catalog skc catalog add git@github.com:team/skills.git --json ### Refresh after upstream changes skc update --json ### Check for delivery drift skc profile deliver --check --json ### Validate everything skc validate --json ### View current state skc status --json ### Discover all CLI commands programmatically skc help-json