claude-md-starter

Scans the repo, infers the tech stack and conventions, asks at most 3 targeted questions, and writes a populated CLAUDE.md that gives Claude full project context from session one.

Invocation Triggers

Explicit:

• "create a CLAUDE.md"
• "my CLAUDE.md is blank"
• "generate project context"
• "initialize CLAUDE.md"
• "set up Claude context for this repo"
• "fill in my CLAUDE.md"
• "run the claude-md-starter skill"

Implicit:

• User pastes a near-empty CLAUDE.md and asks Claude to populate it
• User keeps re-explaining the same project context at the start of sessions

Run immediately when triggered — no upfront questions before scanning.

Workflow (6 Nodes)

Node	Role
1 — Detect	Check if CLAUDE.md exists and measure content length
2 — Scan	Read signal files from the project root (see references/scan-signals.md)
3 — Infer	Draft all sections that can be derived from scanned signals
4 — Grill-me	Ask at most 3 questions for what cannot be inferred
5 — Generate	Write the full CLAUDE.md using the template in references/claude-md-template.md
6 — Validate	Confirm required sections are present and non-placeholder

Node 1 — Detect

Check for CLAUDE.md at the project root.

If not found: Proceed directly to Node 2.

If found and has ≤ 200 characters: Treat as blank — proceed to Node 2.

If found and has > 200 characters: Run the diff-and-merge flow before writing:

1. Read the existing file

2. Complete Nodes 2–4 to produce the generated version

3. Compare section by section — for each of the 8 required sections, classify as:

   • NEW — exists in generated, absent or empty in existing
   • ENHANCED — both versions have content; generated version adds more
   • SAME — both versions have equivalent content
   • CONFLICT — both versions have different non-empty content

4. Present a diff summary table:

Section              | Existing | Generated | Action
---------------------|----------|-----------|-------
Project Overview     | present  | enhanced  | +additions available
Tech Stack           | absent   | new       | will add
Commands             | present  | enhanced  | +2 commands found
Architecture         | absent   | new       | will add
Code Conventions     | present  | same      | no change
Testing              | absent   | new       | will add
What NOT To Do       | absent   | new       | will add
Environment Setup    | absent   | new       | will add

5. Offer three options:

   • A (Recommended) — Keep existing content + add new and enhanced sections only (safe, additive)
   • B — Full replace with generated version
   • C — Review each conflicting section individually before writing

6. Write the chosen merge result.

Node 2 — Scan

Read signal files using the catalog in references/scan-signals.md. For each file found, extract the fields it reveals. Missing files are skipped silently.

Run all reads in parallel where possible:

1. package.json — framework, scripts, package manager, dependencies
2. pyproject.toml / requirements.txt / setup.py — Python stack
3. Cargo.toml / go.mod / pom.xml / build.gradle — language
4. Makefile / justfile — named commands
5. .github/workflows/*.yml — CI/CD steps, deploy targets
6. Dockerfile / docker-compose.yml — runtime environment, services
7. .eslintrc.* / .prettierrc.* / eslint.config.* — JS/TS code style
8. ruff.toml / .flake8 / mypy.ini — Python lint/type config
9. jest.config.* / vitest.config.* / pytest.ini / conftest.py — test framework
10. tsconfig.json — TypeScript settings
11. .env.example / .env.sample — required environment variables
12. README.md (first 40 lines only) — project description
13. Top-level directory listing — architecture pattern
14. .gitignore — build artifacts and generated files

Node 3 — Infer

Using scanned data, populate as many sections as possible before asking questions:

• Project Overview → from README.md first paragraph; fall back to package.json description field
• Tech Stack → from language files + framework dependencies
• Commands → from package.json scripts, Makefile targets, workflow run steps
• Architecture → from top-level directory structure
• Code Conventions → from eslint/prettier/ruff config values
• Testing → from test config files and test directory location
• What NOT To Do → from .gitignore build outputs, workflow branch protection, lock files
• Environment Setup → from .env.example variable names and docker-compose services

Node 4 — Grill-Me Intake

Ask only for what cannot be inferred. Maximum 3 questions. Skip any question whose answer is already clear from scanned files.

Present all applicable questions together in one message — never ask them across multiple turns:

Quick questions to finish your CLAUDE.md (answer whichever apply):

1. What does this project do in one sentence? (skip if README was found)
2. Are there any files, directories, or systems that should never be touched or auto-modified by Claude?
3. Any team conventions not captured in your lint config? (naming patterns, PR size, commit format, review process)

Node 5 — Generate

Produce the CLAUDE.md using the exact section structure from references/claude-md-template.md.

Critical rules:

• Every populated section must have real content — no [TODO: add your X here] placeholders
• If a section cannot be filled at all, omit it entirely rather than writing a placeholder
• Commands must be exact and runnable (npm run dev, not "run the dev server")
• What NOT To Do must have at least 2 entries
• Write in imperative, direct style ("Run tests with...", "Never edit files in...")
• No heading levels deeper than H2 within sections

Node 6 — Validate

Before writing, verify against references/validation-checklist.md:

• All populated sections have real content (no placeholders)
• Commands section has ≥ 2 runnable commands
• What NOT To Do has ≥ 2 entries
• No unreplaced placeholder text remains
• If existing CLAUDE.md had > 200 characters, diff-and-merge flow was completed

If Commands or What NOT To Do would fail: ask one final targeted question before writing.

Output

Write the file to CLAUDE.md at the project root. After writing, print a one-line confirmation:

✓ CLAUDE.md written — X sections populated from repo scan, Y from your answers.

If in diff-and-merge mode, also print which sections were added vs. left unchanged.

Anti-Patterns To Reject

• Generating CLAUDE.md without running the scan first
• Asking more than 3 intake questions
• Writing placeholder sections ("add your commands here")
• Overwriting an existing populated CLAUDE.md without running the diff-and-merge flow
• Writing generic boilerplate not specific to the scanned project
• Including commands that weren't found in signal files and weren't confirmed by the user

References

• references/scan-signals.md — full catalog of signal files and what each reveals
• references/claude-md-template.md — canonical CLAUDE.md section structure and style rules
• references/validation-checklist.md — required fields and quality gates before writing

---

Version: 1.0.0