# claude-code-skills A categorized, deterministically-ranked catalog of `SKILL.md` files for Claude Code. Ships as one npm package — `claude-code-skills` — that exposes an MCP server **and** a CLI. Zero LLM calls in the hot path. Zero backend. Zero API keys. The LLM browses the catalog the way a developer browses npm: open a category page, scan the descriptions, install the one that fits. --- ## Tree of npm packages ``` claude-code-skills ← top-level npm package + CLI ├── @claude-code-skills/core types, frontmatter parser, validators ├── @claude-code-skills/categories authoritative category taxonomy (JSON) ├── @claude-code-skills/signing Ed25519 sign + verify (tweetnacl) ├── @claude-code-skills/context detect framework / language from cwd ├── @claude-code-skills/ranker deterministic BM25 + tag + framework boost ├── @claude-code-skills/registry static catalog loader, bundle builder ├── @claude-code-skills/installer write SKILL.md to .claude/skills/ ├── @claude-code-skills/ingest build index.json from skill-packs/* + _research/* ├── @claude-code-skills/mcp MCP stdio server (5 tools, see below) │ └── skill-packs/ ← first-party SKILL.md content ├── @claude-code-skills/pack-frontend shadcn/Radix, Tailwind v4, Next 15, Astro 5 ├── @claude-code-skills/pack-backend Hono, Drizzle, BullMQ, Zod-contract APIs ├── @claude-code-skills/pack-video FFmpeg, Remotion, word-level subtitles ├── @claude-code-skills/pack-ai-video Whisper, AI dubbing, text-to-video prompting ├── @claude-code-skills/pack-ui-design elevation protocol, typography, backgrounds, motion ├── @claude-code-skills/pack-devops Docker Compose, GitHub Actions monorepo CI ├── @claude-code-skills/pack-testing Playwright visual, Vitest TDD ├── @claude-code-skills/pack-data-engineering DuckDB analytics in Node ├── @claude-code-skills/pack-security OWASP review for 2026 Node apps └── @claude-code-skills/pack-docs-workflow writing plans discipline ``` Each `pack-*` ships with an `index.js` marker and a `peerDependenciesMeta` block listing the open-source npm packages the skills recommend (e.g. `framer-motion`, `@remotion/cli`, `tailwindcss`, `drizzle-orm`, `fluent-ffmpeg`). Consumers see exactly what to install when they pick a skill. --- ## How the LLM uses it (no internal-LLM librarian) The MCP server exposes six tools. The LLM is expected to **browse**, not query a black-box ranker: | Tool | Purpose | | ------------------- | ------- | | `list_categories` | First call. Returns 16 categories with id, title, description, count, sample skills. | | `list_skills` | Pass `category=` to see all skills in that category. | | `get_skill` | Full metadata for one skill: tags, recommended_npm, source repo, license. | | `search_skill` | Fall-back free-text query. Deterministic BM25 + tag/framework boost. No LLM. | | `install_skill` | Writes the SKILL.md to `.claude/skills//`. Verifies Ed25519 signature when present. | | `list_installed` | What's already on disk. | The intended flow is **`list_categories` → pick → `list_skills` → pick → `install_skill`**. `search_skill` is a convenience for free-text intent; ranking is a pure function — same input always produces the same output. --- ## Categories (16) ``` frontend backend ui-design motion-graphics three-d-graphics video-editing ai-video-generation image-generation devops testing data-engineering security mobile ai-tooling docs-workflow accessibility ``` Each has a description, keywords, and a list of recommended open-source npm packages. See `packages/categories/data/categories.json`. --- ## Quickstart — local dev ```bash git clone cd claude-code-skills npm install # installs all workspaces npm run build # tsc across packages/* # Build the catalog from skill-packs/* and (optionally) _research/* node packages/ingest/dist/build-index.js # first-party only node packages/ingest/dist/build-index.js --include-research # + 254 community skills # Use the CLI node dist/cli.js categories node dist/cli.js list video-editing node dist/cli.js show ffmpeg-pipeline-broadcast node dist/cli.js search "framer motion stagger reveal" node dist/cli.js install design-elevation-protocol --scope=project # Smoke-test node scripts/smoke.mjs ``` --- ## Register the MCP server with Claude Code ```bash claude mcp add claude-code-skills -- npx -y claude-code-skills mcp ``` Then ask Claude anything that touches a topic in the catalog. Claude calls `list_categories`, picks the relevant one, and either lists or installs. --- ## Adding new skills 1. Put a SKILL.md under `skill-packs//skills//SKILL.md` with frontmatter: ```yaml --- name: my-new-skill description: category: version: 0.1.0 tags: [tag1, tag2] recommended_npm: ["pkg-a", "pkg-b"] license: MIT --- ``` 2. Re-run `node packages/ingest/dist/build-index.js`. The categorizer will place it in your stated category; if you omit `category`, the rules in `packages/ingest/src/categorize.ts` infer one from name+description+tags. 3. Done. The MCP server picks it up next start. --- ## Architecture decisions - **Static index, not a server.** The catalog ships as `packages/registry/data/index.json` inside the npm package. No backend, no network round-trip, no rate limit, no API key. - **Deterministic ranker.** BM25 over (name + description + tags + category) with multiplicative boosts for tag overlap, framework match (from `package.json` detection), and trust tier. Same query always returns the same ranking. - **First-party priority.** Skills under `skill-packs/*` are tagged `verified` with a 1.5× weight, so curated content surfaces before scraped content. - **Ed25519 signing kept.** `@claude-code-skills/signing` exposes `signBundle` / `verifySignedBundle` with the same canonicalization as before, in case you want to publish signed bundles via a future backend or registry. - **Cross-vendor by design.** SKILL.md is a multi-vendor format (agentskills.io). The MCP tools work with any client that speaks MCP. --- ## What moved to `legacy/` The original `backend/` (Hono + Postgres + Anthropic ranker) and `proxy/` (`@skillport/mcp`) live under `legacy/`. Nothing in the workspace imports from there. Delete it safely if you don't need the reference. --- ## Status - ✓ 14 first-party `skill-packs/` SKILL.md files across 10 categories - ✓ 254 total skills after `--include-research` ingest - ✓ Smoke test passes 18/18 — categories, list, show, search (general + scoped), install, signature verify - ✓ Ranker dist contains zero LLM SDK imports (`grep -i anthropic|openai|google` on `packages/ranker/dist` returns empty)