1
---
2
name: claude-md-master
3
description: Master skill for CLAUDE.md lifecycle - create, update, improve with repo-verified content and multi-module support. Use when creating or updating CLAUDE.md files.
4
---
5
6
# CLAUDE.md Master (Create/Update/Improver)
7
8
## When to use
9
- User asks to create, improve, update, or standardize CLAUDE.md files.
10
11
## Core rules
12
- Only include info verified in repo or config.
13
- Never include secrets, tokens, credentials, or user data.
14
- Never include task-specific or temporary instructions.
15
- Keep concise: root <= 200 lines, module <= 120 lines.
16
- Use bullets; avoid long prose.
17
- Commands must be copy-pasteable and sourced from repo docs/scripts/CI.
18
- Skip empty sections; avoid filler.
19
20
## Mandatory inputs (analyze before generating)
21
- Build/package config relevant to detected stack (root + modules).
22
- Static analysis config used in repo (if present).
23
- Actual module structure and source patterns (scan real dirs/files).
24
- Representative source roots per module to extract:
25
package/feature structure, key types, and annotations in use.
26
27
## Discovery (fast + targeted)
28
1. Locate existing CLAUDE.md variants: `CLAUDE.md`, `.claude.md`, `.claude.local.md`.
29
2. Identify stack and entry points via minimal reads:
30
- `README.md`, relevant `docs/*`
31
- Build/package files (see stack references)
32
- Runtime/config: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*`
33
- CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*`
34
3. Extract commands only if they exist in repo scripts/config/docs.
35
4. Detect multi-module structure:
36
- Android/Gradle: read `settings.gradle` or `settings.gradle.kts` includes.
37
- iOS: detect multiple targets/workspaces in `*.xcodeproj`/`*.xcworkspace`.
38
- If more than one module/target has `src/` or build config, plan module CLAUDE.md files.
39
5. For each module candidate, read its build file + minimal docs to capture
40
module-specific purpose, entry points, and commands.
41
6. Scan source roots for:
42
- Top-level package/feature folders and layer conventions.
43
- Key annotations/types in use (per stack reference).
44
- Naming conventions used in the codebase.
45
7. Capture non-obvious workflows/gotchas from docs or code patterns.
46
47
Performance:
48
- Prefer file listing + targeted reads.
49
- Avoid full-file reads when a section or symbol is enough.
50
- Skip large dirs: `node_modules`, `vendor`, `build`, `dist`.
51
52
## Stack-specific references (Pattern 2)
53
Read the relevant reference only when detection signals appear:
54
- Android/Gradle → `references/android.md`
55
- iOS/Xcode/Swift → `references/ios.md`
56
- PHP → `references/php.md`
57
- Go → `references/go.md`
58
- React (web) → `references/react-web.md`
59
- React Native → `references/react-native.md`
60
- Rust → `references/rust.md`
61
- Python → `references/python.md`
62
- Java/JVM → `references/java.md`
63
- Node tooling → `references/node.md`
64
- .NET/C# → `references/dotnet.md`
65
- Dart/Flutter → `references/flutter.md`
66
- Ruby/Rails → `references/ruby.md`
67
- Elixir/Erlang → `references/elixir.md`
68
- C/C++/CMake → `references/cpp.md`
69
- Other/Unknown → `references/generic.md` (fallback when no specific reference matches)
70
71
If multiple stacks are detected, read multiple references.
72
If no stack is recognized, use the generic reference.
73
74
## Multi-module output policy (mandatory when detected)
75
- Always create a root `CLAUDE.md`.
76
- Also create `CLAUDE.md` inside each meaningful module/target root.
77
- "Meaningful" = has its own build config and `src/` (or equivalent).
78
- Skip tooling-only dirs like `buildSrc`, `gradle`, `scripts`, `tools`.
79
- Module file must be module-specific and avoid duplication:
80
- Include purpose, key paths, entry points, module tests, and module
81
commands (if any).
82
- Reference shared info via `@/CLAUDE.md`.
83
84
## Business module CLAUDE.md policy (all stacks)
85
For monorepo business logic directories (`src/`, `lib/`, `packages/`, `internal/`):
86
- Create `CLAUDE.md` for modules with >5 files OR own README
87
- Skip utility-only dirs: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants`
88
- Layered structure not required; provide module info regardless of architecture
89
- Max 120 lines per module CLAUDE.md
90
- Reference root via `@/CLAUDE.md` for shared architecture/patterns
91
- Include: purpose, structure, key classes, dependencies, entry points
92
93
## Mandatory output sections (per module CLAUDE.md)
94
Include these sections if detected in codebase (skip only if not present):
95
- **Feature/component inventory**: list top-level dirs under source root
96
- **Core/shared modules**: utility, common, or shared code directories
97
- **Navigation/routing structure**: navigation graphs, routes, or routers
98
- **Network/API layer pattern**: API clients, endpoints, response wrappers
99
- **DI/injection pattern**: modules, containers, or injection setup
100
- **Build/config files**: module-specific configs (proguard, manifests, etc.)
101
102
See stack-specific references for exact patterns to detect and report.
103
104
## Update workflow (must follow)
105
1. Propose targeted additions only; show diffs per file.
106
107
2. Ask for approval before applying updates:
108
109
**Cursor IDE:**
110
Use the AskQuestion tool with these options:
111
- id: "approval"
112
- prompt: "Apply these CLAUDE.md updates?"
113
- options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]
114
115
**Claude Code (Terminal):**
116
Output the proposed changes and ask:
117
"Do you approve these updates? (yes/no)"
118
Stop and wait for user response before proceeding.
119
120
**Other Environments (Fallback):**
121
If no structured question tool is available:
122
1. Display proposed changes clearly
123
2. Ask: "Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."
124
3. Wait for explicit user confirmation before proceeding
125
126
3. Apply updates, preserving custom content.
127
128
If no CLAUDE.md exists, propose a new file for approval.
129
130
## Content extraction rules (mandatory)
131
- From codebase only:
132
- Extract: type/class/annotation names used, real path patterns,
133
naming conventions.
134
- Never: hardcoded values, secrets, API keys, business-specific logic.
135
- Never: code snippets in Do/Do Not rules.
136
137
## Verification before writing
138
- [ ] Every rule references actual types/paths from codebase
139
- [ ] No code examples in Do/Do Not sections
140
- [ ] Patterns match what's actually in the codebase (not outdated)
141
142
## Content rules
143
- Include: commands, architecture summary, key paths, testing, gotchas, workflow quirks.
144
- Exclude: generic best practices, obvious info, unverified statements.
145
- Use `@path/to/file` imports to avoid duplication.
146
- Do/Do Not format is optional; keep only if already used in the file.
147
- Avoid code examples except short copy-paste commands.
148
149
## Existing file strategy
150
Detection:
151
- If `<!-- Generated by claude-md-editor skill -->` exists → subsequent run
152
- Else → first run
153
154
First run + existing file:
155
- Backup `CLAUDE.md` → `CLAUDE.md.bak`
156
- Use `.bak` as a source and extract only reusable, project-specific info
157
- Generate a new concise file and add the marker
158
159
Subsequent run:
160
- Preserve custom sections and wording unless outdated or incorrect
161
- Update only what conflicts with current repo state
162
- Add missing sections only if they add real value
163
164
Never modify `.claude.local.md`.
165
166
## Output
167
After updates, print a concise report:
168
```
169
## CLAUDE.md Update Report
170
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
171
- /<module>/CLAUDE.md [CREATED | UPDATED]
172
- Backups: list any `.bak` files
173
```
174
175
## Validation checklist
176
- Description is specific and includes trigger terms
177
- No placeholders remain
178
- No secrets included
179
- Commands are real and copy-pasteable
180
- Report-first rule respected
181
- References are one level deep
182