better-thinking: Instructions file for Claude Code

CLAUDE.md

This repo is the source for the better-thinking Claude Code plugin: a library of composable Agent Skills encoding thinking procedures. See README.md for what it is and how it's structured, and CONTRIBUTING.md for the rules a skill must follow (template, atomic vs. composite, token budgets, no personas).

Working in this repo

• Skills are NOT one-directory-per-skill. Most skills — every atomic and composite skill in the library — are flat files at skills/library/<name>.md. Only the two orchestrators have their own directory + SKILL.md: skills/better-thinking/SKILL.md (the dispatcher) and skills/better-thinking-recipes/SKILL.md (the recipe runner). When looking for a skill by name, check skills/library/<name>.md first — don't assume skills/<name>/SKILL.md or search for a directory that doesn't exist.
• Whichever file a skill lives in (skills/library/<name>.md or skills/<name>/SKILL.md) is the source of truth for it. skills/INDEX.json is a generated-by-hand mirror of every skill's frontmatter that the /better-thinking dispatcher reads to route — it must stay in sync with the actual files, not the other way around.
• catalog/*.md holds full prose specs by category. A spec living in catalog/ is not the same as a skill existing — only an actual file under skills/ (skills/library/<name>.md, or skills/<name>/SKILL.md for the two orchestrators) makes it real. Don't let a catalog entry imply a skill exists when it doesn't.
• Library skills (skills/library/<name>.md) are not independently invocable — Claude Code's harness only exposes top-level plugin skills (better-thinking, better-thinking-recipes) as directly callable. A library skill is only reachable by being routed to: better-thinking's dispatcher picks it via INDEX.json/ROUTE_INDEX.json, or better-thinking-recipes invokes it as a named dependency of a recipe stage. There's no /interview-synthesis-style direct slash command for a library skill.
• skills/ROUTE_INDEX.json is a generated TF-IDF lexical index (name/one_line/triggers/category/Examples, field-weighted, stemmed) built from skills/INDEX.json + each skill file's Examples section (skills/library/<name>.md, or skills/<name>/SKILL.md for the two orchestrators) by scripts/build_route_index.py. The dispatcher (skills/better-thinking/SKILL.md step 3) runs scripts/route.py "<task>" against it for a lexical shortlist before confirming against INDEX.json — a token-overlap aid, not a semantic/embeddings search, so it can still miss a good match phrased very differently from the skill's own vocabulary. Never hand-edit ROUTE_INDEX.json.
• After adding, editing, removing, or renaming any skill (or its related/dependencies, one_line, triggers, or ## Examples section), run both:

  python3 scripts/build_route_index.py
  python3 scripts/check_consistency.py
  

  check_consistency.py checks frontmatter validity, INDEX.json↔filesystem↔frontmatter sync, dangling [[wiki-links]], and catalog specs with no corresponding built skill. Fix everything it reports before considering the change done — this is exactly the class of drift that accumulates silently otherwise (see git history around 2026-07-09 for the incident that motivated writing it: a fully-specified scientific-method composite that several other skills depended on but that was never actually built — since resolved, the skill is built and registered). build_route_index.py must be re-run any time the text it's built from changes, or the router's shortlist goes stale relative to the actual skills.
• There is no other build/test step. A change to this repo is a change to markdown and JSON files (plus regenerating ROUTE_INDEX.json when its inputs change).