| name | claude-md |
| description | Write effective CLAUDE.md files containing only tacit knowledge. Use when asked to create, review, or improve a CLAUDE.md file, or when setting up project context for AI agents. Enforces the "tacit knowledge only" quality bar — rejects content derivable from code, linters, or tooling, with an exception for information that is technically derivable but practically hard to get right. |
| argument-hint | [path-or-action] |
| autouse | false |
CLAUDE.md Skill
Write or review CLAUDE.md files that contain only tacit knowledge — information an AI agent cannot derive by reading the codebase, running tools, or inspecting configuration files.
Core Principle
If a linter, compiler, ls, or grep can tell the agent the same thing, it does not belong in CLAUDE.md.
CLAUDE.md transfers understanding that lives in engineers' heads: architectural invariants, non-obvious constraints, known violations awaiting cleanup, and workflow gotchas that require tribal knowledge.
Supported Actions
- Create: Write a new CLAUDE.md for a directory
- Review: Evaluate an existing CLAUDE.md against the quality bar
- Improve: Refactor an existing CLAUDE.md to remove derivable content and strengthen tacit knowledge
Step 1 — Determine Action and Scope
Parse the user's request:
- If they specify a directory path, scope to that directory.
- If no path, default to the project root.
- Determine action: create, review, or improve.
CLAUDE.md files can be placed in any directory to cover that subtree. A subdirectory CLAUDE.md supplements (does not replace) parent CLAUDE.md files.
Step 2 — Gather Context
Before writing or reviewing, understand the codebase:
- Read existing CLAUDE.md files in the target directory and its parents.
- Inspect the directory — run
ls, read key config files (Makefile, package.json, go.mod, BUILD, .eslintrc, tsconfig.json, etc.).
- Identify what tooling already covers — linter rules, formatter configs, CI pipelines, type systems.
- Mine PR review comments — extract tacit knowledge from code review history (see Step 2a).
- Talk to the user — ask what non-obvious constraints, gotchas, or architectural decisions exist that the code doesn't express.
Step 2a — Mine PR Review Comments
PR code reviews are one of the richest sources of tacit knowledge. Reviewers often explain why something is wrong in ways that never make it into documentation. Mine this knowledge with gh:
gh pr list --state merged --limit 30 --json number,title,url
gh api repos/{owner}/{repo}/pulls/{number}/comments --jq '.[] | {path, body, diff_hunk}'
gh api repos/{owner}/{repo}/pulls/{number}/reviews --jq '.[] | select(.state != "APPROVED") | {body, state}'
What to look for in review comments:
| Signal | Example | Extracts To |
|---|
| "Don't do X because..." | "Don't import pkg/internal from here — it breaks the dependency boundary" | Architectural boundary |
| "This broke prod when..." | "Last time someone changed this serialization, the mobile app crashed for 2 hours" | Operational gotcha |
| "The convention is..." | "We always put migration SQL in migrations/ not inline — the deploy pipeline expects it there" | Workflow procedure |
| "This needs to match..." | "This enum must stay in sync with the proto definition in repo X" | Cross-team constraint |
| Repeated corrections | Same feedback given across multiple PRs | Undocumented rule worth capturing |
| "Why" explanations | "We use X instead of Y because Y has a memory leak under Z conditions" | Non-obvious design rationale |
Process:
- Fetch the last 20–30 merged PRs touching the target directory.
- For each PR, read inline review comments and review-level feedback.
- Filter for comments that explain constraints, boundaries, gotchas, or rationale — skip style nits and typo fixes.
- Group recurring themes — if the same feedback appears in 2+ PRs, it is almost certainly undocumented tacit knowledge.
- Apply the quality bar (Step 3) to each extracted item before including it.
Limitations: Only mine reviews if the repo is hosted on GitHub and gh is authenticated. Skip this step if gh auth status fails or the repo has no PR history.
Step 3 — Apply the Quality Bar
Every piece of content must pass this checklist:
| Check | Question |
|---|
| Tacit knowledge | Would an agent reading source code and tool configs miss this? |
| Non-derivable or hard-to-derive | Can ls, grep, linter output, or config files reproduce this? If yes, would an agent reliably get it right on the first try? |
| Architectural invariant | Does it describe a rule not enforced by tooling? |
| Known violations | If documenting a rule, are existing violations called out? |
| Actionable | Does it give concrete steps, not vague guidance? |
| Not code explanation | Does it avoid restating what functions do? |
| Concise | Uses tables, short bullets, or headings — not prose walls? |
Hard-to-Derive Exception
Some information is technically derivable but practically hard to get right. Apply this test:
Even if an agent could find this by searching, would it reliably find the correct answer on the first try?
If the answer is probably not — because the information is buried, ambiguous, or commonly confused — it belongs in CLAUDE.md despite being technically derivable.
| Category | Example |
|---|
| Niche tool flags | A CLI flag that looks like it does one thing but behaves differently in this project's context |
| Subtle config interactions | Two settings that are individually documented but whose combination produces unexpected behavior |
| Error-prone defaults | A tool where the obvious usage is wrong and the correct invocation requires project-specific knowledge |
| Version-pinned behavior | A tool invocation where the default behavior changed between versions and the project pins an older version |
This exception does not apply to content that is straightforward to derive — directory listings, standard lint rules, or well-documented API usage remain excluded.
The Natural Language Execution Test
If you gave this CLAUDE.md to a competent engineer who has never seen the codebase, would they avoid a mistake they would otherwise make?
If yes, keep it. If no — because tooling or code review would catch it — remove it.
Step 4 — Write or Revise Content
Content That Belongs
| Category | Example |
|---|
| Architectural boundaries | "Vendor formats must be parsed only inside topomap/ — all other packages use topomap.Graph" |
| Non-obvious design rationale | "Shortest paths are precomputed with Dijkstra because the graph is static and small" |
| Operational gotchas | "Run ms_local_ctl down when done — Cloud SQL Proxy impersonation accounts are limited" |
| Workflow procedures | Step-by-step for tasks the code can't express (e.g., "how to add a new vendor format") |
| Cross-team constraints | "Service X owns the schema — changes require their review even though we have write access" |
| Non-obvious environment setup | "Must run gcloud auth with impersonation flag before local dev works" |
| Migration context | "Package oldauth is deprecated — new code must use auth/v2. Known users: [list]" |
| PR review wisdom | Recurring reviewer feedback that reveals undocumented rules, boundaries, or gotchas |
| Hard-to-derive tool usage | "Must pass --legacy-peer-deps to npm install — the default resolver fails on our pinned React 17 peer deps" |
| Subtle config interactions | "Setting GOMAXPROCS=1 in CI is intentional — the race detector produces false positives with higher values on this codebase" |
Content to Reject
| Anti-Pattern | Why It Fails | Alternative |
|---|
| Lint rules | Derivable from linter config | Let the linter do its job |
| Directory listings (names only) | Derivable from ls | OK if adding constraints or relationships |
| Code explanations | Derivable from reading code | Document why, not what |
| Language style guides | Derivable from formatter config | Only project-specific deviations |
| Dependency lists | Derivable from go.mod/package.json | Only surprising choices and why |
| API endpoint catalogs | Derivable from specs/routes | Only non-obvious auth, rate limits, ordering |
| Build commands alone | Derivable from Makefile/CI | Only alongside non-obvious flags, env setup, or hard-to-derive interactions |
Step 5 — Structure the File
Use this structure (include only sections with genuine content):
# <Directory or Project Name>
## Build / Test / Run
<!-- Only non-obvious commands, flags, or environment requirements -->
<!-- Skip if Makefile/CI config is self-explanatory -->
## Architecture
<!-- Boundaries, invariants, import rules not enforced by tooling -->
<!-- Include known violations and migration status -->
## Conventions
<!-- Project-specific rules that deviate from community norms -->
<!-- Only rules NOT enforced by linters/formatters -->
## Gotchas
<!-- Things that will bite you if nobody tells you -->
<!-- Operational, environmental, or cross-team surprises -->
Formatting rules:
- Use tables for structured comparisons.
- Use short bullet points, not paragraphs.
- Prefer imperative mood ("Run X", "Do not import Y").
- Keep total length under 200 lines — if longer, split into subdirectory CLAUDE.md files.
Step 6 — Review Mode
When reviewing an existing CLAUDE.md, evaluate each section:
- For each item, ask: "Can an agent derive this from the codebase?"
- If derivable, apply the hard-to-derive exception: "Would an agent reliably get this right on the first try?" If not, the item may still belong.
- Flag items that are derivable and easy to get right, with a brief explanation of how.
- Flag items that are vague or non-actionable.
- Suggest tacit knowledge that is missing based on your codebase exploration.
- Output a verdict: items to keep, items to remove, items to add.
Format the review as:
## CLAUDE.md Review: <path>
### Keep (tacit knowledge)
- <item> — <why it belongs>
### Remove (derivable)
- <item> — derivable via <tool/file>
### Add (missing tacit knowledge)
- <suggested item> — <why an agent would miss this>
Step 7 — AGENTS.md Alias (Optional)
Some tools and platforms look for AGENTS.md instead of CLAUDE.md. If the
user requests AGENTS.md compatibility, or if the CLAUDE.md being authored
contains the <!-- agents-md-compat --> marker:
- Check whether
AGENTS.md already exists in the same directory as the target
CLAUDE.md.
- If it does not exist, create it as a symbolic link:
ln -s CLAUDE.md AGENTS.md
- If it exists but is a regular file (not a symlink), warn the user and ask
whether to replace it with a symlink.
- If it exists as a symlink pointing elsewhere, warn the user and ask whether
to update it.
This step is limited to creating or verifying the sibling alias. Do not
duplicate content into AGENTS.md — it must always be a symlink to CLAUDE.md.
