git:20260825.0bcd8a2 to git:20260825.cb9851a

7 added, 0 removed. Audit A to A.

# 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](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)

**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.

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):

```bash

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, and every description must carry a trigger clause ("Use when ..."). `pnpm format` fixes Biome formatting.

## Adding an item

```bash

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.

- 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.