claude-md-creator

name

claude-md-creator

description

Creates a production-quality CLAUDE.md file for any project by exploring the codebase, inferring the stack, and applying proven best practices. Use this skill whenever the user wants to create, generate, initialize, write, or set up a CLAUDE.md (or "Claude config", "Claude instructions", "Claude rules") for their project — even if they just say "help Claude understand my codebase", "set up Claude for this repo", or "onboard Claude to this project". This skill produces a behavioral contract, not a README — it shapes Claude Code's safety posture, verification discipline, and task execution protocol for the specific project.

CLAUDE.md Creator

A great CLAUDE.md is a behavioral contract — it shapes Claude Code's default behavior, safety posture, verification discipline, and context economy. This skill creates one by exploring the codebase first, asking only what can't be inferred, and following proven best practices throughout.

Step 1: Explore the Project

Before asking the user anything, read the project to gather what can be inferred automatically. Use Glob and Read — don't ask for things the code already answers.

Look for:

Package manager

• pnpm-lock.yaml → pnpm
• yarn.lock → yarn
• package-lock.json → npm
• bun.lockb → bun
• pyproject.toml, Pipfile → Python (check for uv, poetry, pip)
• Cargo.toml → cargo
• go.mod → go

Stack and frameworks — read package.json dependencies, pyproject.toml, requirements.txt, go.mod, Cargo.toml

Test runner — look for jest.config.*, vitest.config.*, pytest.ini, *.test.*, *.spec.*, __tests__/

Linter/formatter — .eslintrc*, .prettierrc*, biome.json, ruff.toml, .flake8, pyproject.toml [tool.ruff]

Project structure — Glob for apps/, packages/, src/, lib/, api/, web/, services/

Monorepo signals — turbo.json, nx.json, pnpm-workspace.yaml, multiple package.json files in subdirectories

Existing CLAUDE.md — if one exists, read it before doing anything else. Ask whether to update it or replace it.

Key entry points — look for main.*, index.*, app.*, server.*, Makefile, justfile

Step 2: Ask Targeted Questions

Ask only for what can't be inferred — maximum 5 questions, fewer if the codebase is clear. Examples of good questions:

• "What does this project do in one sentence?" (always ask this unless there's a clear README)
• "I found these dev/test commands — are they right? [list inferred commands]"
• "Any key external services or deployment targets Claude should know about?"
• "Are there parts of the codebase that are sensitive or should never be modified without extra care?"
• "Anything specific Claude tends to get wrong in this kind of project?"

Skip questions whose answers are obvious from the code.

Step 3: Generate CLAUDE.md

Follow the structure and rules from references/best-practices.md. Key principles to apply:

Structure — always in this order:

1. Project Context
2. Non-Negotiable Rules
3. Task Execution Protocol
4. Coding Standards
5. Verification Protocol
6. Tools and Commands
7. Scoped Rules (if applicable)
8. Git Safety
9. Completion Report Format

Quality rules:

• Project description first — context before rules, always
• Local truth only — don't write things Claude already knows (use git status, TypeScript uses types)
• Commands block — tailor to the detected package manager; only include commands Claude actually needs
• Concise imperatives — prefer "Use pnpm, not npm" over "When working in this project you should try to use pnpm instead of npm"
• Length — keep root CLAUDE.md under 200 lines; move domain detail into scoped files
• Priority ordering — non-negotiable rules go at the top, low-priority references at the bottom

Sections to always include verbatim (tailor where noted):

Non-Negotiable Rules:

- Think before coding. State assumptions and clarify ambiguous requirements before implementation.
- Prefer the simplest solution that satisfies the requirement.
- Make surgical changes. Only touch files required for the requested task.
- Do not add features, abstractions, dependencies, or refactors unless explicitly requested.
- Never run destructive or irreversible commands without explicit user confirmation.
- If unsure whether a command is destructive, ask first.
- Verify behavior before reporting completion.

Task Execution Protocol:

For each task:
1. Restate the goal.
2. Identify assumptions and ambiguity.
3. Define verifiable success criteria.
4. Implement the smallest correct change.
5. Verify with tests, typecheck, lint, build, or runtime checks.
6. Report what changed and what was verified.

Git Safety (adjust command list to project):

Require confirmation before:
- git push --force
- git reset --hard
- git clean -fd
- rm -rf
- branch deletion
- rebasing shared branches
- merging branches
- production migrations

Completion Report:

At the end of each task, report:
- Summary of changes
- Files modified
- Verification performed
- Remaining risks or limitations
- Unrelated issues observed but not changed

Verification Protocol — tailor based on what was detected:

Before completion:
- Run [detected test command] when available.
- Run [detected typecheck command] for typed code.
- Run [detected lint/build command] when relevant.
- For UI changes, verify visually when browser tooling is available.
- If verification cannot be run, explain why.

Unrelated findings rule — always include this:

If you discover unrelated bugs, dead code, security issues, or refactor opportunities during a task, report them under "Observed but not changed." Do not fix them unless asked.

Ambiguity rule — always include this:

When requirements are ambiguous, ask before implementing — but only when the ambiguity affects architecture, data model, user-visible behavior, security, or irreversible changes.

Step 4: Handle Monorepos

If monorepo signals were detected:

• Root CLAUDE.md contains only global invariants (non-negotiable rules, git safety, completion format)
• Propose per-app/package CLAUDE.md files with local specifics
• Ask before creating them — show what you'd put in each

Step 5: Offer Scoped Rule Files

For projects with multiple clear domains (API, frontend, database, testing), offer to create:

rules/api.md       # Scope: apps/api/**
rules/frontend.md  # Scope: apps/web/**
rules/database.md  # Scope: **/migrations/**, **/schema/**
rules/testing.md   # Scope: **/*.test.*, **/*.spec.*

Each file starts with # Scope: <glob> and contains domain-specific rules. Reference them from root CLAUDE.md under a "Scoped Rules" section.

Step 6: Write the File

If no CLAUDE.md exists: write it directly.

If one already exists: show the diff and ask before overwriting.

After writing, briefly summarize what went into each section and why, so the user can iterate. Point out any assumptions you made.

Reference

See references/best-practices.md for the full best-practices reference including the recommended skeleton and the compressed rule set. Read it if you need to double-check specific rules or want to include additional optional sections.