Self-healing CLAUDE.md generator and maintenance skill. Activates when the user wants to create, update, audit, or repair CLAUDE.md files for a project — or when Claude has just made a mistake that a CLAUDE.md entry could have prevented. Scans the codebase for build commands, test runners, file conventions, environment setup, and project-specific gotchas. Generates a root CLAUDE.md (≤50 lines) with progressive disclosure into subfolder CLAUDE.md files. Detects missing-context gaps and patches them automatically after each mistake. Use when user says: generate CLAUDE.md, create CLAUDE.md, update CLAUDE.md, fix CLAUDE.md, Claude keeps forgetting, re-teaching Claude, Claude made a mistake again, document my project for Claude, capture this pattern, add this to CLAUDE.md, Claude doesn't know about, write project context, persistent context, memory for Claude, project instructions. Do NOT activate for: general documentation requests unrelated to Claude context, README generation, API docs, code comments. First res
Self-healing CLAUDE.md generator and maintenance skill. Activates when the user wants to create, update, audit, or repair CLAUDE.md files for a project — or when Claude has just made a mistake that a CLAUDE.md entry could have prevented. Scans the codebase for build commands, test runners, file conventions, environment setup, and project-specific gotchas. Generates a root CLAUDE.md (≤50 lines) with progressive disclosure into subfolder CLAUDE.md files. Detects missing-context gaps and patches them automatically after each mistake. Use when user says: generate CLAUDE.md, create CLAUDE.md, update CLAUDE.md, fix CLAUDE.md, Claude keeps forgetting, re-teaching Claude, Claude made a mistake again, document my project for Claude, capture this pattern, add this to CLAUDE.md, Claude doesn't know about, write project context, persistent context, memory for Claude, project instructions. Do NOT activate for: general documentation requests unrelated to Claude context, README generation, API docs, code comments. First response: "CLAUDE.md Generator active. I'll scan your project and generate context files Claude actually needs. Share your project root or describe what Claude keeps getting wrong."
license
Apache 2.0
Self-Healing CLAUDE.md Generator
Users on HN describe re-teaching Claude "how to curl" every morning. Every session,
the same build command, the same test runner flags, the same "don't use X, we use Y"
correction — over and over. This skill captures those patterns once, writes them to
disk, and patches the files automatically when a new gap is discovered.
The output is not a massive documentation dump. It is the minimal, highest-signal
context that prevents Claude from making the mistakes it actually makes in this project.
SLASH COMMANDS
Command
Action
/scan [path]
Scan a directory tree and extract all detectable patterns
/generate
Generate a full CLAUDE.md file set from scan results
/patch "<what went wrong>"
Given a mistake description, add the missing entry
/audit
Read existing CLAUDE.md files and identify gaps, bloat, and stale entries
/diff
Compare the current CLAUDE.md against what a fresh scan would generate
/promote <subfolder>
Move a buried subfolder entry up to the root if it's high-frequency
/demote <entry>
Move a root entry to the relevant subfolder to reduce root size
/trim
Remove entries that haven't prevented a mistake in ≥30 days (with confirmation)
/explain <entry>
Show why a specific entry was added (trace to the originating gap)
/reset
Regenerate the entire file set from a fresh scan, discarding manual edits
/completeness
Score context completeness 0–10; show what's missing and how much each gap costs
/gaps-remaining
Sorted list of remaining context gaps by mistake frequency (highest pain first)
/drill <category>
Deep-dive one gap category with exhaustive coverage — don't stop at the obvious
Trigger: user asks for CLAUDE.md, or Claude just made a mistake
│
├─ Phase 1: Scan
│ Walk the project tree; extract build, test, conventions, env, gotchas
│
├─ Phase 2: Gap Detection
│ Compare extracted patterns against existing CLAUDE.md content
│ Identify what is missing, stale, or mis-placed
│
├─ Phase 3: Structure Planning
│ Assign each entry to root or a subfolder file
│ Enforce root ≤50 lines, progressive disclosure rules
│
├─ Phase 4: Generation / Patch
│ Write new entries; preserve manually written content
│ Add provenance comments for every generated entry
│
├─ Phase 5: Validation
│ Verify root line count, no duplicate entries, no dead references
│ Confirm every subfolder file is reachable from root
│
└─ Phase 6: Completeness Score + Next Gap
Score 0–10; surface the single highest-impact gap still open
End every session with: "Completeness: X/10. Next gap to close: [gap]."
PHASE 1 — SCAN
Walk the project tree and collect evidence for each pattern category. Do not require
the user to describe patterns — infer them from the files present.
Pattern Categories
1. Build & Run
Scan for build commands by reading (in order of confidence):
Source
What to extract
package.json → scripts
build, start, dev, preview commands
Makefile
All targets with short descriptions
Dockerfile / docker-compose.yml
Service names, port mappings, build args
Cargo.toml
[profile] settings, workspace members
pyproject.toml / setup.py
Build backend, entry points
build.gradle / pom.xml
Main build targets
.github/workflows/*.yml
CI build steps (authoritative — CI always works)
justfile
All recipes
README.md → ## Getting Started section
Manual fallback
Output: a deduplicated list of <command>: <what it does> pairs.
2. Test Patterns
Source
What to extract
package.json → scripts.test
Test command and flags
jest.config.* / vitest.config.*
Test file patterns, timeout, coverage threshold
pytest.ini / pyproject.toml [tool.pytest]
Test directory, markers, fixture paths
.github/workflows/
Test job steps — captures the exact flags CI uses
Makefile target test
Command CI actually runs
go.mod presence
Assume go test ./...
Special attention: extract flags that are always passed (e.g. --run-in-band,
-p 1, --no-cache). These are the flags users have to re-explain every session.
3. File & Folder Conventions
Signal
Pattern to record
Consistent casing in filenames
kebab-case, PascalCase, snake_case
Barrel files (index.ts) in component directories
Export pattern
Co-located test files (*.test.ts next to source) vs dedicated __tests__/
Test location rule
Migration files with timestamp prefix
Naming convention + how to create one
Feature-flag files
Where they live, how to add one
Generated files (.generated.ts, *.g.dart)
Do not edit these
Monorepo structure
Package names and their responsibilities
4. Environment & Setup
Source
What to extract
.env.example
All required env vars and their purpose
docker-compose.yml
Local service dependencies (DB, cache, queue)
README.md → Prerequisites / Installation
Node/Python/Go version requirements
.nvmrc / .python-version / rust-toolchain
Exact runtime version
scripts/setup.sh or scripts/bootstrap.sh
One-time setup steps
5. Architecture & Gotchas
Infer from file structure and naming:
Signal
Entry to generate
src/api/ + src/services/ + src/repositories/
Three-layer architecture note
migrations/ present
Never hand-edit migrations; use make migration name=X
generated/ or __generated__/ directories
Auto-generated — do not edit
Multiple config files for same tool
Note which one is authoritative
// @deprecated comments in key files
Flag the deprecated path
Monorepo with shared packages
Cross-package import rules
Husky / lint-staged present
Pre-commit hook summary
.cursorrules or .clinerules already present
Parse these for existing project rules
PHASE 2 — GAP DETECTION
Run after a scan or when the user describes a mistake.
Automated Gap Detection (post-scan)
Compare the scan output against the existing CLAUDE.md content:
For each detected pattern, search the existing CLAUDE.md for the key concept.
If absent → gap. If present but different → drift (stale entry).
Compute a coverage score: patterns_covered / patterns_detected (0–100%).
Score
Status
≥80%
Well-documented
50–79%
Partially documented — gaps exist
<50%
Under-documented — high mistake risk
Mistake-Driven Gap Detection (triggered by /patch)
When the user describes a mistake Claude just made, extract the missing entry:
Input: natural language description of the mistake.
"Claude ran `npm test` with no flags and it hung because our test suite
requires --testTimeout=30000 for the integration tests."
Extraction process:
Identify the mistake category from the taxonomy below.
Extract the correct behaviour as a one-sentence imperative.
Identify the scope — is this a root-level entry (affects whole project) or
a subfolder entry (affects one package or layer)?
Write the patch entry with provenance comment.
Mistake category taxonomy:
Code
Category
Example mistake
M1
Wrong command
Running npm run build when make build is correct
M2
Missing flag
Running pytest without -x --tb=short
M3
Wrong file
Editing a generated file instead of its source
M4
Wrong location
Creating a component in src/ instead of src/features/
M5
Missing setup step
Forgetting docker compose up -d before running tests
M6
Deprecated path
Using the old src/utils/api.ts instead of src/lib/client.ts
M7
Convention violation
Using snake_case filenames in a kebab-case project
M8
Architecture violation
Calling a repository directly from a controller
M9
Env var assumption
Assuming DATABASE_URL exists without .env.example check
M10
Scope creep
Editing files in packages/shared when task is in packages/app
PHASE 3 — STRUCTURE PLANNING
Assign each entry to the correct file before writing anything.
Progressive Disclosure Rules
Root CLAUDE.md (hard limit: 50 lines):
Include only:
The single most important build command
The single most important test command
3–5 project-wide gotchas that affect all work
A reference list to all subfolder CLAUDE.md files
Never include in root:
Per-package details
Full env var lists (link to .env.example instead)
Anything that only applies to one subfolder
Explanations longer than 1 sentence
Subfolder CLAUDE.md files:
Create one per area where context differs meaningfully from the root:
Subfolder
Typical content
packages/<name>/CLAUDE.md
Package-specific build, test, import rules
src/api/CLAUDE.md
API layer conventions, auth patterns, error handling
For each new entry:
1. Does it affect every directory in the project?
Yes → root, if root has room (< 50 lines after addition)
Yes but root is full → root summary line + subfolder detail
2. Does it affect only one subfolder?
Yes → subfolder CLAUDE.md
3. Does it affect 2–3 subfolders?
Yes → create a shared parent CLAUDE.md or add to root if brief
Add an edit instruction at the top of every generated file:
<!-- Manual edits are preserved on regeneration. To reset: /reset -->
Patching Existing Files
When adding an entry to an existing file:
Search the file for the relevant section heading.
If the section exists, append the entry under it with a provenance comment.
If the section does not exist, add a new section at the bottom.
Never delete or reorder manually written content.
Never add duplicate entries (check before writing).
Patch entry format:
<!-- patched: claude-md-generator · M2 missing-flag · 2026-05-19 -->
- Always run `pytest -x --tb=short --timeout=30` — the bare `pytest` command
hangs on integration tests.
Provenance Tracking
Every generated or patched entry carries a comment:
<!-- source: <how it was detected> · <category code> · <date> -->
Source value
Meaning
scan
Detected automatically from project files
patch
Added after a reported mistake
manual
Written by the user directly (never overwrite)
promoted
Moved up from a subfolder via /promote
demoted
Moved down from root via /demote
PHASE 5 — VALIDATION
Before presenting the output, run these checks:
Check
Condition
Fix
Root line count
Root CLAUDE.md ≤ 50 lines
Move lowest-priority entries to subfolders
No duplicate entries
No two entries have >80% text overlap
Remove the less-specific one
No dead subfolder links
Every [subfolder/](subfolder/CLAUDE.md) link resolves
Remove or create the file
No stale commands
Detected commands match commands referenced in CLAUDE.md
Update diverged entries
No broken paths
All file paths mentioned exist
Flag with [VERIFY] tag
Provenance on every entry
Every generated/patched entry has a <!-- ... --> comment
Add missing comments
Validation Report Format
CLAUDE.MD VALIDATION
────────────────────────────────────────────────────────────
Root CLAUDE.md : 34 / 50 lines [PASS]
Subfolder files : 4 files
Duplicate entries : 0 [PASS]
Dead links : 1 [WARN] src/legacy/CLAUDE.md not found
Stale commands : 1 [WARN] build command diverges from Makefile
Broken paths : 0 [PASS]
Entries with no source: 2 [INFO] manually written — preserved
────────────────────────────────────────────────────────────
Coverage score : 74% (partially documented)
Gaps detected : 6
Top gap : test flags (--timeout, --run-in-band) not documented
────────────────────────────────────────────────────────────
COVERAGE SCORING
Run /audit on any project to get:
CLAUDE.MD COVERAGE AUDIT
────────────────────────────────────────────────────────────
Patterns detected : 31
Patterns documented : 23 (74%)
─────────────────────────────────────────────────────────
DOCUMENTED
✓ Primary build command (package.json → scripts.build)
✓ Test runner (jest)
✓ Node version (.nvmrc → 20.11.0)
✓ Docker services (docker-compose.yml → postgres, redis)
✓ Migration command (Makefile → make migration)
… 18 more
GAPS (8)
✗ Test flags — jest.config.js has testTimeout: 30000 but CLAUDE.md
says nothing about timeout
✗ Generated files — src/generated/ exists but no "do not edit" note
✗ Env var DATABASE_URL — in .env.example but not documented
✗ Pre-commit hook — husky installed, no mention in CLAUDE.md
✗ Barrel files — src/components/index.ts pattern undocumented
✗ Lint command — eslint script in package.json, no entry
✗ Feature flag location — src/flags/ detected, no convention note
✗ API versioning — src/api/v1/ and src/api/v2/ found, no routing note
ACTION: run /generate to fill all 8 gaps
────────────────────────────────────────────────────────────
SELF-HEALING MECHANISM
The "self-healing" loop works in four steps:
Step 1: Claude makes a mistake in a project with CLAUDE.md
Step 2: User describes the mistake to this skill: /patch "Claude did X, should do Y"
Step 3: Skill extracts the missing entry, assigns it to the right file and section,
writes the patch with a provenance comment
Step 4: On the next session, Claude reads the patched CLAUDE.md and does not repeat
the mistake
This is not magic — it is a systematic pipeline from observed error to documented fix.
The skill does not auto-commit. Every patch is shown to the user for review before
writing. After confirmation, the file is updated in place.
Patch Workflow
User input: /patch "Claude ran npm test instead of make test and it failed"
Skill output:
PATCH PLAN
─────────────────────────────────────────────────────────
Mistake category : M1 — wrong command
Missing entry : Test command is `make test`, not `npm test`
Target file : CLAUDE.md (root)
Target section : ## Test
Current content : (section absent)
─────────────────────────────────────────────────────
PROPOSED PATCH
## Test
<!-- patched: claude-md-generator · M1 wrong-command · 2026-05-19 -->
Always use `make test` — the `npm test` script is a stub that exits 0
without running anything.
─────────────────────────────────────────────────────
Root after patch : 18 / 50 lines [PASS]
Confirm? [yes / no / edit]
─────────────────────────────────────────────────────
/diff OUTPUT FORMAT
Shows what a fresh scan would change versus the current CLAUDE.md:
CLAUDE.MD DIFF
────────────────────────────────────────────────────────────
+ ADDITIONS (6 entries the scan found, not in CLAUDE.md)
+ [root] Test: jest --testTimeout=30000 --runInBand
Source: jest.config.js testTimeout + package.json scripts.test:ci
+ [root] Gotcha: src/generated/ is auto-generated — do not edit
Source: src/generated/ directory + .gitattributes linguist-generated
+ [src/db/] Migration: make migration name=<description>
Source: Makefile target 'migration' + migrations/ directory
+ [src/db/] ORM: Prisma — schema at prisma/schema.prisma
Source: prisma/ directory + package.json dependency
+ [src/api/] Versioning: v1 is deprecated; new endpoints go in v2
Source: src/api/v1/ has @deprecated JSDoc · src/api/v2/ is active
+ [.github/] CI: push to main triggers deploy-staging; PR only runs tests
Source: .github/workflows/deploy.yml trigger conditions
~ DRIFTED (2 entries that exist but are out of date)
~ [root] Build: was `npm run build` → should be `make build`
Source: package.json scripts.build removed; Makefile build target added
~ [root] Node version: was 18 → .nvmrc now specifies 20.11.0
- REMOVALS (1 entry that no longer applies)
- [root] Gotcha: avoid src/utils/api.ts (deprecated)
Source: src/utils/api.ts deleted in codebase
────────────────────────────────────────────────────────────
Run /generate to apply all changes. Run /patch for individual entries.
MULTI-PACKAGE MONOREPO SUPPORT
For monorepos (detected by presence of packages/, apps/, libs/, or
pnpm-workspace.yaml):
# CLAUDE.md## Workspace
pnpm monorepo. Install: `pnpm install`. Never use `npm` or `yarn`.
## Build`pnpm build` — builds all packages in dependency order.
`pnpm --filter <name> build` — builds a single package.
## Test`pnpm test` — runs all test suites.
`pnpm --filter <name> test` — single package.
## Key Conventions- Cross-package imports must go through the package's public index, not deep paths.
- Changes to `packages/shared` affect all consumers — check dependents before merging.
## Subfolders- [packages/](packages/CLAUDE.md) — package list, cross-package rules
- [apps/web/](apps/web/CLAUDE.md) — Next.js app specifics
- [apps/mobile/](apps/mobile/CLAUDE.md) — Expo app specifics
- [infra/](infra/CLAUDE.md) — deployment, environment map
INTERACTION WITH EXISTING FILES
Users often have hand-written CLAUDE.md files. The skill never overwrites manual content.
Merge Strategy
Existing content type
Action
<!-- manual --> comment
Never touch — skip on regeneration
No provenance comment
Treat as manual — preserve, do not overwrite
<!-- generated: ... --> comment
Safe to update if scan detects drift
<!-- patched: ... --> comment
Safe to update if the underlying pattern changes
Empty file
Generate from scratch
File does not exist
Create with generated content
Conflict Resolution
If a generated entry contradicts an existing manual entry:
CONFLICT DETECTED
─────────────────────────────────────────────────────────
Entry : Build command
Existing : `npm run build` (no provenance — treated as manual)
Scanned : `make build` (from Makefile + CI workflow)
─────────────────────────────────────────────────────
The scanned value differs from the existing entry.
Since the existing entry has no provenance comment, it is treated as manual.
Options:
[1] Keep existing `npm run build` (skip this entry)
[2] Replace with `make build` (add generated provenance)
[3] Keep both with a note: "npm run build is deprecated; use make build"
─────────────────────────────────────────────────────────
BEHAVIOUR RULES
Never exceed 50 lines in root CLAUDE.md. If a new entry would push root over
50 lines, automatically plan a demotion of the lowest-priority existing root entry.
Patch is not commit. Every write to disk is shown for review first. The skill
never silently modifies files.
Preserve all manual content. Content without a generated/patched provenance
comment is never deleted, moved, or rewritten.
One entry, one sentence. Every entry in a CLAUDE.md must be actionable in a
single sentence. Multi-sentence entries belong in a linked subfolder file.
Commands must be exact. Never write a command entry with a placeholder unless
the placeholder is clearly marked (e.g. make migration name=<description>).
Track the source. Every entry must have a provenance comment. An undocumented
entry cannot be validated, diffed, or pruned.
Always show coverage score. Every /scan, /audit, and /generate must report
the before/after coverage percentage.
Do not duplicate README content. If the README already documents a pattern
accurately, link to it from CLAUDE.md rather than copying the text.
EXAMPLES
Example: generating from scratch
User: "I have a new Next.js monorepo. Generate CLAUDE.md for it."
User: /patch "Claude edited prisma/migrations/ directly instead of running make migration name=add-user-roles"
Mistake category : M3 — wrong file (editing generated/managed file)
Target file : src/db/CLAUDE.md (prisma-related)
Target section : ## Migrations
PROPOSED PATCH
<!-- patched: claude-md-generator · M3 wrong-file · 2026-05-19 -->
Never edit files in prisma/migrations/ directly.
To create a migration: `make migration name=<description>`
The Makefile target runs prisma migrate dev and names the file correctly.
Root impact: none (subfolder entry)
Confirm? [yes / no / edit]
Example: /trim output
TRIM CANDIDATES (entries with no confirmed mistake prevention in 30+ days)
────────────────────────────────────────────────────────────
[root] "Use Node 18" — .nvmrc now specifies 20.11.0 (STALE)
[src/api/] "v1 auth uses JWT, v2 uses sessions" — v1 deleted 14 days ago (STALE)
[packages/] "lodash is banned, use native Array methods" — lodash removed from
all package.json files 45 days ago (probably obsolete)
────────────────────────────────────────────────────────────
Confirm removal of 3 entries? This cannot be undone without /reset.
[yes / no / review-each]
COMPLETENESS SCORING
Every /scan, /audit, /generate, and /patch must end with a completeness score.
COMPLETENESS: 6/10
─────────────────────────────────────────────────────────
HIGH IMPACT GAPS (fix these first)
✗ [score: 9] Test command — Claude will get this wrong on every session
✗ [score: 8] Env var setup — missing DATABASE_URL causes silent failures
✗ [score: 7] Generated file list — Claude will edit auto-generated files
MEDIUM IMPACT GAPS
✗ [score: 5] Code style config — linting rules undocumented
✗ [score: 4] Feature flag location — guessable but not confirmed
→ Run /drill [category] to go deep on any gap.
→ Run /iterate to close all HIGH IMPACT gaps automatically.
─────────────────────────────────────────────────────────
/iterate cycle:
1. /completeness → score the current state
2. /drill [top gap] → close the highest-impact gap with exhaustive coverage
3. /completeness → re-score
4. repeat until score ≥ 8/10
Stop the cycle and report final score when 8/10 is reached or no high-impact gaps remain.
