dotclaude

Personal Claude Code registry: skills, agents, commands, and hooks, distributed via the shadcn registry and a Claude Code plugin marketplace. Full contributor guide: CONTRIBUTING.md.

The one rule: source vs generated

Every item lives at <type>/<category>/<name>/<MANIFEST> (SKILL.md, AGENT.md, COMMAND.md, or HOOK.md). Everything else is derived by pnpm gen:

• each item's registry.json and the root registry.json
• the README catalog, badges, and plugins table (between <!-- ... --> markers)
• everything under .claude-plugin/ (marketplace + per-plugin trees)
• site/data.json, the one file the catalog site reads
• one crawlable page per item and per plugin under site/<type>/<name>/ and site/plugins/<name>/ (plus each item's index.md), site/sitemap.xml and site/llms-full.txt, all from scripts/site-pages.ts
• NOTICE.md, the attributions collected from every manifest's ## Attribution section

Never hand-edit generated files. Edit the source manifest, run pnpm gen, and commit the regenerated output. pnpm gen:check fails CI when anything is stale.

The catalog site lives in site/: static HTML, CSS, and JS with no build step and no runtime dependencies, deployed to dotclaude.khaledsaeed.tech by .github/workflows/pages.yml on every push to main that touches site/. Its only data source is the generated site/data.json, so the site never needs editing when items change; index.html, styles.css, app.js and 404.html are hand-written and Biome-linted like the rest of the repo. Three marked regions inside index.html (meta, rows and jsonld) and site/llms.txt are generated too, so crawlers that do not run JavaScript still see the full catalog. The home page keeps its filters in the query string (/?q=&type=&category=&plugin=&sort=); old #/ hash links redirect. Every other page is generated by scripts/site-pages.ts: the per-item and per-plugin pages (the canonical URLs for search and answer engines, with their own title, description, Open Graph, BreadcrumbList and SoftwareSourceCode JSON-LD, the rendered manifest, a table of contents and the plugin's sibling items), site/plugins/index.html and site/install/index.html. The shared header and footer live in site-pages.ts and in index.html; change both together. Preview locally with any static server, e.g. python3 -m http.server 4173 --directory site, and run pnpm test:e2e (Playwright, e2e/) after touching anything under site/ or site-pages.ts; CI runs it on a desktop and a phone profile.

One thing deliberately sits outside that rule: .agents/skills/improve/, surfaced to this repo's own sessions through the .claude/skills/improve symlink. It is tooling for working on the registry, not an item in it, so it is invisible to gen and validate, follows none of the item conventions, and ships to nobody. Anything under skills/, agents/, commands/, or hooks/ is a registry item; .agents/ is not.

Verification gate

Run before considering any change done (same as CI):

pnpm typecheck && pnpm lint && pnpm test && pnpm gen:check && pnpm validate

pnpm coverage reports how much of hooks/ and scripts/ the suite actually executes, and fails below 90%. It exists because the suite is black-box, hooks run as child processes, so ordinary coverage tooling instruments only the runner and reports a confident, wrong 0%. This collects V8 coverage from the children and merges it. Use it to find untested branches, not to chase 100%: some branches are platform-specific and unreachable on a given OS.

pnpm smoke is the slower end-to-end check CI also runs, kept out of the line above because it drives the real Claude Code CLI: it installs every generated plugin into a throwaway config dir, diffs the installed tree against the generated one, and runs each bundled hook script from its installed path (including that the deny rules still block). Run it after touching gen.ts's plugin logic or any hook script. It needs no auth or network beyond resolving the CLI, and leaves nothing behind.

pnpm validate also enforces content rules: no <TODO: scaffold markers in manifests, every description carries a trigger clause ("Use when ..."), no em dash anywhere in an item's markdown (manifest or companion file), an ## Attribution section (required on any item adapted from elsewhere) names a source URL and a permissive licence, an ## Inspired by section (for a shape followed with nothing copied) names a source URL, and a cross-reference like "the paper-reader skill" or "the /pr command" must name an item that exists. pnpm format fixes Biome formatting.

Adding an item

pnpm new --type skill --category engineering --name my-skill \
         --description "What it does. Use when ..."

The scaffolder writes a stub manifest and regenerates. Fill in the stub (validate fails while <TODO: remains), then run the gate.

Layout constraints worth knowing

• Agents and commands are file-layout: their folder must contain only the manifest; pnpm gen rejects extras. Skills and hooks are folder-layout: companion files ride along.
• Item names are globally unique across all four types and must match their folder name.
• Hooks that take settings read <project>/.claude/dotclaude.json (one key per hook, documented in each HOOK.md and the README) and fall back to defaults when it is absent or unreadable.
• A plugin may pull in a skill from another category with extraSkills in its PLUGINS entry (humanize ships in both thesis and writing). Each plugin carries a semver version; bump the minor when items are added, the patch when they change.
• Hook scripts are standalone, zero-dependency .mjs files (Node stdlib, node >= 18, deliberately below the repo's own engines.node >= 20, because hooks run in the user's environment, not this repo's toolchain) that fail open (exit 0 on any internal error, exit 2 to block). They are copied verbatim into plugin trees, so a shared runtime module is not possible, command-guard and smart-approve intentionally duplicate their deny rules, and the parity table in scripts/__tests__/hooks.test.ts is the drift guard: change the rules in both files and the table together.
• Tests are black-box: hooks are spawned with the event JSON on stdin; gen/validate/new run against fixture repos in temp dirs. Follow those patterns.

Voice

Items address the agent in the second person, imperative, third-person descriptions with an explicit "Use when ..." clause. No AI/co-authorship mentions inside items or their output.