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=<id> 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/<name>/. 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

git clone <this repo>
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

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/<pack-name>/skills/<skill-name>/SKILL.md with frontmatter:

   ---
   name: my-new-skill
   description: <one paragraph — what, when to use>
   category: <one of the 16 ids>
   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)