CLAUDE.md Generator

Purpose: Teach an AI agent how to analyze a codebase and produce a high-quality CLAUDE.md file with progressive disclosure.

Overview

A great CLAUDE.md is the single most impactful file in a repository for AI-assisted development. It tells the agent what it needs to know — and nothing more. This skill teaches you how to create one.

Principles

Concise over comprehensive — 200 lines max for CLAUDE.md. Details go in agent_docs/.
Universal, not personal — Write for any agent, not a specific model.
No linting rules — Agents get these from config files. Don't duplicate.
Progressive disclosure — Top-level has critical info. agent_docs/ has deep dives.
Imperative rules — "Never do X" and "Always do Y" are clearer than explanations.

Process

Step 1: Analyze the Codebase

Scan these files first:

package.json / Cargo.toml / pyproject.toml — stack and dependencies
Existing config files (.eslintrc, tsconfig.json, etc.) — already-encoded rules
README.md — project purpose (but don't copy it)
Recent git history — active patterns and conventions

Step 2: Identify Critical Rules

Look for:

Data access patterns — ORMs, query builders, column selection rules
Numeric conventions — score ranges (0-1 vs 0-100), currency units
Auth patterns — how auth is handled, typed clients, middleware
Architecture constraints — "never import X from Y", module boundaries
Testing patterns — test file locations, mocking conventions, assertion styles
Common gotchas — things that break builds or cause subtle bugs

Step 3: Structure the CLAUDE.md

markdown

# {Project Name}

{One paragraph: what the project is and does}

## Stack

- {Framework} + {Language} + {Styling}
- {Database/backend}
- {Testing framework}

## Quick Reference

```bash
{dev command}      # {what it does}
{test command}     # {what it does}
{build command}    # {what it does}

Workflow

{Branch strategy}
{Deploy process}

Critical Rules

{Rule name} — {concise explanation}
{Rule name} — {concise explanation}

Agent Docs (read when relevant)

File	When to read
`agent_docs/{file}.md`	{trigger condition}

code


### Step 4: Create agent_docs/ Files

For each deep topic, create a focused file:

- `agent_docs/project_structure.md` — file layout, key directories, naming conventions
- `agent_docs/development_workflow.md` — git workflow, environments, migrations, deployment
- `agent_docs/common_gotchas.md` — debugging issues, form validation, auth quirks
- `agent_docs/testing.md` — writing and running tests, mocking patterns

Each agent_docs file should be **self-contained** — an agent reads it independently.

---

## Anti-Patterns

- Copying the entire README into CLAUDE.md
- Listing every file in the project
- Including linting rules the agent gets from config
- Writing paragraphs when bullet points suffice
- Including setup instructions (agents don't run npm install)
- Documenting obvious conventions (standard Next.js patterns, etc.)

---

## Quality Checklist

- [ ] CLAUDE.md is under 200 lines
- [ ] Every rule is actionable ("Never X", "Always Y")
- [ ] No duplicate info from config files
- [ ] agent_docs/ table has clear "when to read" triggers
- [ ] A new developer (or agent) could be productive after reading just CLAUDE.md
- [ ] No personal preferences disguised as project rules

## Playground

<!DOCTYPE html><html><head><meta charset='utf-8'><style>*{box-sizing:border-box;margin:0;padding:0}body{background:#0d1117;color:#e6edf3;font-family:monospace;font-size:12px;height:100vh;display:flex;flex-direction:column;overflow:hidden}.header{background:#161b22;border-bottom:1px solid #30363d;padding:8px 14px;font-size:11px;color:#8b949e;display:flex;justify-content:space-between;align-items:center;flex-shrink:0}.title{color:#58a6ff;font-weight:bold;font-size:13px}.panels{display:flex;flex:1;overflow:hidden}.panel{flex:1;overflow:auto;padding:12px;border-right:1px solid #30363d}.panel:last-child{border-right:none}.label{font-size:10px;color:#8b949e;text-transform:uppercase;letter-spacing:.08em;margin-bottom:6px}pre{white-space:pre-wrap;word-break:break-word;line-height:1.5}</style></head><body><div class='header'><span class='title'>CLAUDE.md Generator</span><span>Example · SkillSlap</span></div><div class='panels'><div class='panel'><div class='label'>Input: Project description</div><pre><span style='color:#8b949e'>Project: Next.js 16 + Supabase SaaS</span>
<span style='color:#8b949e'>Stack: TypeScript, Tailwind, Vitest</span>
<span style='color:#8b949e'>Special rules:</span>
<span style='color:#8b949e'>- Never SELECT * on users table</span>
<span style='color:#8b949e'>- Always run tests before commit</span>
<span style='color:#8b949e'>- Stripe is test-mode only in dev</span></pre></div><div class='panel'><div class='label'>Output: CLAUDE.md</div><pre><span style='color:#58a6ff'># ProjectName</span>

<span style='color:#8b949e'>Next.js 16 SaaS with Supabase auth</span>
<span style='color:#8b949e'>and Stripe billing.</span>

<span style='color:#58a6ff'>## Stack</span>
<span style='color:#8b949e'>Next.js 16 · Supabase · TypeScript</span>
<span style='color:#8b949e'>Tailwind · Vitest · Stripe</span>

<span style='color:#58a6ff'>## Non-Negotiable Rules</span>
<span style='color:#8b949e'>1. Never `SELECT *` on users table</span>
<span style='color:#8b949e'>   — use USER_COLUMNS from lib/</span>
<span style='color:#8b949e'>2. Run `npx vitest run` before</span>
<span style='color:#8b949e'>   every commit</span>
<span style='color:#8b949e'>3. Stripe is ALWAYS test-mode in</span>
<span style='color:#8b949e'>   dev (sk_test_ keys only)</span>

<span style='color:#58a6ff'>## Quick Commands</span>
<span style='color:#8b949e'>npm run dev   # localhost:3000</span>
<span style='color:#8b949e'>npm test      # full unit suite</span></pre></div></div></body></html>

CLAUDE.md Generator

CLAUDE.md Generator

Overview

Principles

Process

Step 1: Analyze the Codebase

Step 2: Identify Critical Rules

Step 3: Structure the CLAUDE.md

Workflow

Critical Rules

Agent Docs (read when relevant)

Created by

Info

Embed

Export