Skip to main content

Architecture

skills/ is the source of truth​

Every skill lives at skills/<name>/, containing:

  • SKILL.md — name + description frontmatter (the description drives triggering, and should start with "Use when...") followed by the actual playbook.
  • metadata.json — version, organization, date, and an abstract (a longer, catalog-facing summary distinct from the SKILL.md trigger description).
  • optional references/, agents/ — heavier reference material or agent-specific instructions kept out of SKILL.md to stay under its 500-line budget.

.claude-plugin/marketplace.json lists every skill path and bundles them into one installable plugin, cw. This is what /plugin marketplace add catesandrew/skills + /plugin install cw@skills reads.

packages/ is generated, not hand-edited​

Each skill also ships as its own scoped npm package, @catesworks/skill-<name>, under packages/skill-<name>/. These are derived from skills/<name>/ by the release pipeline — don't hand-edit files under packages/, edit the source in skills/ and regenerate.

The pipeline (pnpm release at the repo root, package.json):

node bin/generate-skill-package-json.mjs --check   # verify packages/*/package.json matches skills/*/metadata.json
node bin/sync-skill-content.mjs --all               # copy SKILL.md/metadata.json/references/etc. into packages/*
node bin/validate-skill-package.mjs --all           # sanity-check the generated package contents
changeset publish                                    # publish any versioned packages to npm

Versioning goes through Changesets (.changeset/); pnpm version-packages bumps versions, then runs bin/sync-metadata-version.mjs to keep each skill's metadata.json.version in lockstep with its package's package.json.version.

docs/published-skills.json tracks which @catesworks/skill-* package names are actually live on npm — used by the release scripts to distinguish a first publish from a version bump.

This docs site​

website/ is a Docusaurus site. website/docs/skills-catalog.md and the per-skill pages under website/docs/skills/*.md are generated by bin/generate-skill-docs.mjs from skills/*/SKILL.md + skills/*/metadata.json — regenerate with:

node bin/generate-skill-docs.mjs           # regenerate the catalog table
node bin/generate-skill-docs.mjs --check   # CI: fail if the catalog is stale or a deep-dive page is missing

The catalog table (abstract, use case, install command) is fully mechanical. The deep-dive pages' prose (what a skill does, how to use it, gotchas, and — where real commit history supports it — why it exists) is hand-written, not template-generated, and lives permanently under website/docs/skills/.

Relationship to next-starters and dotfiles​

This repo is the public, generic sibling of next-starters's own skills/ plugin (ns) — that repo keeps its skills tightly coupled to Next.js starter templates and stack conventions; this repo holds everything stack-agnostic. Most of the 52 skills here originated in a private dotfiles collection (~/.dotfiles/agent-skills/skills/) and were migrated out once they proved generic and client-agnostic enough to publish. See the "Scope" section of the root README.md for the exact bar a skill has to clear to live here versus stay in a private collection.