CLAUDE.md Creator Skill

CLAUDE.md Creator

Create, validate, and maintain CLAUDE.md files with intelligent project detection.

Workflow Decision Tree

                    User Request
                        │
            ┌───────────┴───────────┐
            │   What's needed?      │
            └───────────┬───────────┘
         ┌──────────────┼──────────────┐
         │              │              │
    Create new    Update existing   Validate/Fix
         │              │              │
    ┌────┴────┐    ┌────┴────┐    ┌───┴────┐
    │         │    │         │    │        │
  Which      Detect   Merge    Auto-fix   Auto-fix
  type?      context  changes  issues    issues
    │         │        │        │         │
  Detect    Project   Ask      Run       Run
  context    type     user     fix       fix
    │         │      changes   script    script
    └────┬────┘       │        │         │
         │           │        │         │
    Generate    Generate     Validate   Validate
    content     content      output     output
         │           │        │         │
         └───────────┴────────┴─────────┘
                       │
                  Write to
                  file

Quick Start

| Task | Command | |------|---------| | Create project CLAUDE.md | scripts/generate-claude-md.py --type project | | Update existing file | scripts/update-claude-md.py <path> | | Validate file | scripts/validate-claude-md.py <path> | | Auto-fix issues | scripts/auto-fix-claude-md.py <path> | | Detect context | scripts/detect-claude-type.py |

Step 1: Determine CLAUDE.md Type

Script: scripts/detect-claude-type.py

Detection Logic:

| Context | Path | Size Target | When to Use | |---------|------|-------------|-------------| | Global | ~/.claude/CLAUDE.md | 50-150 lines | Personal preferences across all projects | | Project | .claude/CLAUDE.md | 100-300 lines | Team instructions for this project | | Local | CLAUDE.local.md | <50 lines | Personal overrides for this project | | Rules | .claude/rules/*.md | 20-100 each | Modular topics by subject |

Step 2: Detect Project Type

Script: scripts/detect-project.py

Scans for project markers to generate smart defaults:

| Marker | Language | Framework | Template Used | |--------|----------|-----------|---------------| | package.json + "next" | TypeScript | Next.js | nodejs.md | | package.json + "react" + "vite" | TypeScript | Vite React | nodejs.md | | requirements.txt + "fastapi" | Python | FastAPI | python.md | | requirements.txt + "django" | Python | Django | python.md | | Cargo.toml | Rust | - | rust.md | | go.mod | Go | - | go.md | | None detected | - | - | general.md |

Step 3: Generate CLAUDE.md

Script: scripts/generate-claude-md.py

Template Selection:

Base template (assets/*.template.md)
    +
Language template (assets/framework-templates/*.md)
    +
Project-specific data (detected)
    =
Final CLAUDE.md

Step 4: Validate Structure

Script: scripts/validate-claude-md.py

Checks Performed:

| Category | Check | Error Level | |----------|-------|-------------| | Frontmatter | Valid YAML fence | ❌ Error | | Frontmatter | Required fields | ❌ Error | | Structure | Section headers | ⚠️ Warning | | Best practices | Line count | ⚠️ Warning | | Best practices | Table format | ⚠️ Warning | | Content | Command validity | ⚠️ Warning | | Content | Path references | ⚠️ Warning |

Step 5: Auto-Fix Issues

Script: scripts/auto-fix-claude-md.py

Auto-Fixes:

| Issue | Fix | Backup | |-------|-----|--------| | Missing frontmatter | Add YAML fence | ✅ Yes | | Empty sections | Remove or placeholder | ✅ Yes | | Malformed tables | Convert to proper Markdown | ✅ Yes | | Extra blank lines | Collapse to 1 line | No | | Inconsistent headings | Normalize to H2/H3 | ✅ Yes | | Missing commands | Add from project detection | ✅ Yes |

Run modes:

# Dry run
./auto-fix-claude-md.py --dry-run <path>

# Auto-fix all
./auto-fix-claude-md.py <path>

# Fix specific category
./auto-fix-claude-md.py --category structure <path>

Step 6: Update Existing

Script: scripts/update-claude-md.py

Merge Strategy:

Read existing CLAUDE.md
Detect project changes
Ask user what to update
Preserve custom sections
Write updated file

Best Practices

| Principle | Target | |-----------|--------| | Tables > Prose | Use tables for commands, configs | | Specific commands | Extract real commands from package.json | | Line targets | Global: 50-150, Project: 100-300, Local: <50, Rules: 20-100 | | Progressive disclosure | Quick start → detailed → references |

Resources

scripts/

| Script | Purpose | When to Use | |--------|---------|-------------| | detect-claude-type.py | Determine CLAUDE.md type | Auto-detection | | detect-project.py | Scan project markers | Before generation | | generate-claude-md.py | Create from templates | New file creation | | validate-claude-md.py | Check structure | After edits | | auto-fix-claude-md.py | Fix issues | Validation fails | | update-claude-md.py | Update existing | Project changes |

references/

| File | Load When | |------|-----------| | best-practices.md | Writing content | | validation-rules.md | Understanding errors | | project-detection.md | Extending detection | | examples/ | Real-world patterns |

assets/

| File | Purpose | |------|---------| | global.template.md | Personal preferences | | project.template.md | Team instructions | | local.template.md | Personal overrides | | rule.template.md | Modular topics | | framework-templates/*.md | Language/framework additions |

Agent Skills: CLAUDE.md Creator

Skill Files