claude-md-creator
Use when creating CLAUDE.md files, updating existing CLAUDE.md, validating CLAUDE.md structure, or auto-fixing CLAUDE.md issues. Load for setting up project instructions, global guidelines, local overrides, or modular rules. Handles global (~/.claude/CLAUDE.md), project (.claude/CLAUDE.md), local (CLAUDE.local.md), and rules (.claude/rules/*.md) with smart project detection and template generation.
When & Why to Use This Skill
The CLAUDE.md Creator is a specialized utility designed to automate the generation, validation, and maintenance of CLAUDE.md files, which serve as the primary instruction set for AI agents. By leveraging intelligent project detection for frameworks like Next.js, FastAPI, and Rust, it ensures that AI assistants have precise, structured, and context-aware guidelines. This tool streamlines the setup of global, project-specific, and local rules, significantly improving the efficiency and accuracy of AI-human pair programming.
Use Cases
- New Project Initialization: Automatically detect the tech stack (e.g., TypeScript, Python, Go) and generate a tailored CLAUDE.md file with relevant build and test commands.
- Instruction Standardization: Enforce consistent coding standards and project guidelines across a team by validating and auto-fixing the structure of existing instruction files.
- Hierarchical Context Management: Organize AI instructions into global preferences, project-wide rules, and local overrides to provide the most relevant context for different development environments.
- Documentation Maintenance: Use the auto-fix feature to repair malformed tables, normalize headings, and update outdated command references in project documentation to keep AI agents aligned with the current codebase.
| name | claude-md-creator |
|---|---|
| description | "Use when creating CLAUDE.md files, updating existing CLAUDE.md, validating CLAUDE.md structure, or auto-fixing CLAUDE.md issues. Load for setting up project instructions, global guidelines, local overrides, or modular rules. Handles global (~/.claude/CLAUDE.md), project (.claude/CLAUDE.md), local (CLAUDE.local.md), and rules (.claude/rules/*.md) with smart project detection and template generation." |
| keywords | claude-md, instructions, setup, configuration, guidelines, project-setup |
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 |