1. CLAUDE.md is for main agent behaviour
CLAUDE.md defines the main agent's role: conversing with users, delegating to sub-agents, and following the promode methodology. It does NOT contain project-specific technical details — those belong in README.md files.
2. Sub-agents use the promode-subagent
Claude Code sub-agents don't inherit CLAUDE.md. The promode-subagent mirrors the same methodology so sub-agents apply the same principles. Main agents delegate to promode-subagent rather than instructing sub-agents to read CLAUDE.md.
3. README.md files are the knowledge graph
Each package/directory can have a README.md with domain-specific context. Agents read these just-in-time when working in that area. This keeps initial context lean while making deep knowledge available.
4. Tests are the documentation
Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.
5. CLAUDE.md is standardised
The standard CLAUDE.md (standard/MAIN_AGENT_CLAUDE.md) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in README.md files.
- Install — Set up the standard CLAUDE.md in a new project
- Migrate — Refactor an existing CLAUDE.md, moving content to READMEs
- Audit — Check if a project follows progressive disclosure principles
Wait for response before proceeding.
Intent-based routing:
- "set up CLAUDE.md", "add agent config" → workflows/install.md
- "CLAUDE.md is too big", "slim down", "refactor" → workflows/migrate.md
- "is this right?", "check conformance" → workflows/audit.md
After reading the workflow, follow it exactly.
Sub-agents: Main agents delegate to promode-subagent, which already knows the methodology.
README.md distribution:
project/
├── CLAUDE.md # Main agent behaviour (promode methodology)
├── README.md # Project overview, links to main components of system, etc
└── docs/
└── {feature}/ # Ephemeral planning docs, and task specs
| Workflow |
Purpose |
| install.md |
Install standard CLAUDE.md into new project |
| migrate.md |
Migrate existing CLAUDE.md content to READMEs |
| audit.md |
Audit project for progressive disclosure conformance |
|
|
- CLAUDE.md is an exact copy of
standard/MAIN_AGENT_CLAUDE.md
- README.md at project root with overview and navigation
- Component README.md files throughout for domain-specific context
- Tests document system behaviour, not markdown files
1---2name: managing-claude-code-meta-23description: MUST be loaded when setting up, installing, migrating, reviewing, auditing, or checking CLAUDE.md files in projects. Covers installing the promode CLAUDE.md into new projects, migrating existing CLAUDE.md content to READMEs (progressive disclosure), and auditing projects for conformance. Invoke PROACTIVELY when user mentions CLAUDE.md, project setup, agent configuration, or code meta files.4---5
6<essential_principles>
7This skill manages projects that adopt the **promode methodology** — a set of principles and workflows for AI agents to develop software. The methodology emphasises TDD, context conservation, progressive disclosure, and clear delegation patterns.
8
9**1. CLAUDE.md is for main agent behaviour**
10CLAUDE.md defines the main agent's role: conversing with users, delegating to sub-agents, and following the promode methodology. It does NOT contain project-specific technical details — those belong in README.md files.
11
12**2. Sub-agents use the promode-subagent**
13Claude Code sub-agents don't inherit CLAUDE.md. The `promode-subagent` mirrors the same methodology so sub-agents apply the same principles. Main agents delegate to promode-subagent rather than instructing sub-agents to read CLAUDE.md.
14
15**3. README.md files are the knowledge graph**
16Each package/directory can have a README.md with domain-specific context. Agents read these just-in-time when working in that area. This keeps initial context lean while making deep knowledge available.
17
18**4. Tests are the documentation**
19Long-lived markdown should cover architecture and principles only. Detailed behaviour documentation belongs in executable tests. If behaviour isn't tested, it's not guaranteed.
20
21**5. CLAUDE.md is standardised**
22The standard CLAUDE.md (`standard/MAIN_AGENT_CLAUDE.md`) should be copied exactly into projects. It is designed to work universally. All project-specific content belongs in README.md files.
23</essential_principles>
24
25<never_do>
26- NEVER modify `standard/MAIN_AGENT_CLAUDE.md` content — it must be copied exactly into projects
27- NEVER add project-specific content to CLAUDE.md (use README.md files instead)
28- NEVER duplicate content between CLAUDE.md and README.md — single source of truth
29- NEVER skip verifying CLAUDE.md matches the standard after installation or migration
30</never_do>
31
32<escalation>
33Stop and ask the user when:
34- Project is not under git version control or has uncommited changes
35- Content doesn't fit KEEP/MOVE/DELETE categories during migration
36- Existing README.md files conflict with the suggested structure
37- You've attempted the same step 3+ times without success
38- Changes would affect more than 10 files
39</escalation>
40
41<intake>
42What would you like to do?
43
441. **Install** — Set up the standard CLAUDE.md in a new project
452. **Migrate** — Refactor an existing CLAUDE.md, moving content to READMEs
463. **Audit** — Check if a project follows progressive disclosure principles
47
48**Wait for response before proceeding.**
49</intake>
50
51<routing>
52| Response | Next Action | Workflow |
53|----------|-------------|----------|
54| 1, "install", "setup", "new", "create" | Confirm project path | workflows/install.md |
55| 2, "migrate", "refactor", "move", "convert" | Analyze existing CLAUDE.md | workflows/migrate.md |
56| 3, "audit", "check", "review", "assess" | Scan project structure | workflows/audit.md |
57
58**Intent-based routing:**
59- "set up CLAUDE.md", "add agent config" → workflows/install.md
60- "CLAUDE.md is too big", "slim down", "refactor" → workflows/migrate.md
61- "is this right?", "check conformance" → workflows/audit.md
62
63**After reading the workflow, follow it exactly.**
64</routing>
65
66<quick_reference>
67**CLAUDE.md**: Copy `standard/MAIN_AGENT_CLAUDE.md` exactly. Do not modify. This configures the main agent with promode methodology.
68
69**Sub-agents**: Main agents delegate to `promode-subagent`, which already knows the methodology.
70
71**README.md distribution:**
72```
73project/
74├── CLAUDE.md # Main agent behaviour (promode methodology)
75├── README.md # Project overview, links to main components of system, etc
76└── docs/
77 └── {feature}/ # Ephemeral planning docs, and task specs
78```
79</quick_reference>
80
81<reference_index>
82- `standard/MAIN_AGENT_CLAUDE.md` — The canonical CLAUDE.md (copy exactly into projects)
83- `references/progressive-disclosure.md` — Why and how to distribute content to READMEs
84- `references/claude-md-sections.md` — Purpose of each CLAUDE.md section
85</reference_index>
86
87<workflows_index>
88All in `workflows/`:
89
90| Workflow | Purpose |
91|----------|---------|
92| install.md | Install standard CLAUDE.md into new project |
93| migrate.md | Migrate existing CLAUDE.md content to READMEs |
94| audit.md | Audit project for progressive disclosure conformance |
95</workflows_index>
96
97<success_criteria>
98A well-configured project:
99
100- CLAUDE.md is an exact copy of `standard/MAIN_AGENT_CLAUDE.md`
101- README.md at project root with overview and navigation
102- Component README.md files throughout for domain-specific context
103- Tests document system behaviour, not markdown files
104</success_criteria>
majiayu000