Skip to content

alirezarezvani/claude-code-skill-factory / generated-skills/claude-md-enhancer

claude-md-enhancer

Verified

Analyzes, generates, and enhances CLAUDE.md files for any project type using best practices, modular architecture support, and tech stack customization. Use when setting up new projects, improving existing CLAUDE.md files, or establishing AI-assisted development standards.

FileKindSize
HOW_TO_USE.mdmarkdown12.2 KB
README.mdmarkdown15.8 KB
SKILL.mdskill md16.1 KB
analyzer.pyscript12.9 KB
examples/README.mdmarkdown5.3 KB
examples/core-small-team-CLAUDE.mdmarkdown5.5 KB
examples/minimal-solo-CLAUDE.mdmarkdown1.8 KB
examples/modular-backend-CLAUDE.mdmarkdown9.1 KB
examples/modular-frontend-CLAUDE.mdmarkdown10.5 KB
examples/modular-root-CLAUDE.mdmarkdown6.4 KB
examples/python-api-CLAUDE.mdmarkdown13.0 KB
expected_output.jsonconfig9.8 KB
generator.pyscript19.1 KB
sample_input.jsonconfig4.4 KB
template_selector.pyscript16.7 KB
validator.pyscript14.9 KB
workflow.pyscript15.5 KB
# claude-md-enhancer

> **Analyze, generate, and enhance CLAUDE.md files for any project type with intelligent templates and best practices.**

A comprehensive Claude Code skill that helps teams create and maintain high-quality CLAUDE.md files. Supports analysis, validation, generation, and enhancement with tech stack customization, team size adaptation, and modular architecture.

## Features

πŸ†• **Interactive Initialization** - Explore repository, detect project context, and create CLAUDE.md through conversational workflow
✨ **100% Native Format Compliance** - All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations
βœ… **Intelligent Analysis** - Scan and evaluate existing CLAUDE.md files for quality and completeness
🎯 **Best Practice Validation** - Check against Anthropic guidelines and community standards
πŸš€ **Smart Generation** - Create customized CLAUDE.md files from scratch
πŸ”§ **Enhancement** - Add missing sections and improve existing files
πŸ“¦ **Modular Architecture** - Support context-specific files (backend/, frontend/, database/)
πŸ› οΈ **Tech Stack Customization** - Tailor guidelines to your technologies
πŸ‘₯ **Team Size Adaptation** - Adjust complexity for solo, small, medium, or large teams
πŸ“Š **Quality Scoring** - Get 0-100 quality scores with actionable recommendations

---

## Quick Start

### Installation

#### Option 1: Claude Code (Project-Level)

```bash
# Copy skill folder to your project
cp -r claude-md-enhancer /path/to/your/project/.claude/skills/

# Restart Claude Code or reload skills
```

#### Option 2: Claude Code (User-Level)

```bash
# Copy skill folder to user skills directory
cp -r claude-md-enhancer ~/.claude/skills/

# Available across all your projects
```

#### Option 3: Claude Apps

```
1. Open Claude in browser
2. Go to Skills settings
3. Upload claude-md-enhancer.zip
4. Enable the skill
```

### Basic Usage

#### New Project (Interactive Initialization)

```
Hey Claudeβ€”I just added the "claude-md-enhancer" skill. I don't have a CLAUDE.md file yet. Can you help me create one for this project?
```

Claude will:
1. Explore your repository
2. Detect project type, tech stack, team size
3. Show discoveries and ask for confirmation
4. Create customized CLAUDE.md file(s)

#### Existing Project

```
Hey Claudeβ€”I just added the "claude-md-enhancer" skill. Can you analyze my CLAUDE.md and suggest improvements?
```

See [HOW_TO_USE.md](HOW_TO_USE.md) for comprehensive examples.

---

## Architecture

### Module Overview

```
claude-md-enhancer/
β”œβ”€β”€ SKILL.md                    # Skill definition with YAML frontmatter
β”œβ”€β”€ analyzer.py                 # Analyzes existing CLAUDE.md files
β”œβ”€β”€ validator.py                # Validates against best practices
β”œβ”€β”€ generator.py                # Generates new content
β”œβ”€β”€ template_selector.py        # Selects appropriate templates
β”œβ”€β”€ sample_input.json           # Example inputs
β”œβ”€β”€ expected_output.json        # Expected outputs
β”œβ”€β”€ HOW_TO_USE.md               # Usage examples
└── README.md                   # This file
```

### Python Modules

#### `workflow.py` - Initialization Workflow (New!)

**Class**: `InitializationWorkflow`

**Key Methods**:
- `check_claude_md_exists()` - Detect if CLAUDE.md exists
- `generate_exploration_prompt()` - Guide Claude to explore repository
- `analyze_discoveries(results)` - Analyze exploration results to detect project context
- `generate_confirmation_prompt(context)` - Create user confirmation prompt
- `get_workflow_steps()` - Get complete 7-step workflow

**Workflow Steps**:
1. Check for existing CLAUDE.md
2. Explore repository (built-in Claude Code command)
3. Analyze discoveries (project type, tech stack, team size)
4. Request user confirmation
5. Create CLAUDE.md file(s)
6. Enhance with best practices
7. Provide summary

**Detection Capabilities**:
- **Project Types**: web_app, api, fullstack, cli, library, mobile, desktop
- **Tech Stacks**: TypeScript, Python, Go, React, Vue, FastAPI, Django, PostgreSQL, Docker, Kubernetes, etc.
- **Team Sizes**: solo, small (<10), medium (10-50), large (50+)
- **Development Phases**: prototype, mvp, production, enterprise
- **Workflows**: TDD, CI/CD, documentation-first, agile

#### `analyzer.py` - File Analysis

**Class**: `CLAUDEMDAnalyzer`

**Key Methods**:
- `analyze_file()` - Comprehensive file analysis
- `detect_sections()` - Identify all sections and subsections
- `calculate_quality_score()` - Score 0-100 based on multiple factors
- `generate_recommendations()` - Actionable improvement suggestions

**Quality Score Breakdown** (0-100):
- Length appropriateness: 25 points
- Section completeness: 25 points
- Formatting quality: 20 points
- Content specificity: 15 points
- Modular organization: 15 points

#### `validator.py` - Best Practices Validation

**Class**: `BestPracticesValidator`

**Key Methods**:
- `validate_length()` - Check file length (20-300 lines recommended)
- `validate_structure()` - Verify required sections and hierarchy
- `validate_formatting()` - Check markdown formatting quality
- `validate_completeness()` - Ensure critical content included
- `validate_all()` - Run all validation checks

**Validation Categories**:
- File length (MUST be 20-300 lines)
- Structure (required sections: Core Principles, Workflow)
- Formatting (balanced code blocks, heading hierarchy)
- Completeness (code examples, links, lists)
- Anti-patterns (hardcoded secrets, placeholders, broken links)

#### `generator.py` - Content Generation

**Class**: `ContentGenerator`

**Key Methods**:
- `generate_root_file()` - Create main CLAUDE.md (navigation hub)
- `generate_context_file(context)` - Create context-specific files
- `generate_section(name)` - Generate individual sections
- `merge_with_existing(content, sections)` - Enhance existing files

**Supported Contexts**:
- `backend` - API design, database, error handling
- `frontend` - Components, state, styling, performance
- `database` - Schema, migrations, query optimization
- `docs` - Documentation standards
- `.github` - CI/CD workflows

#### `template_selector.py` - Template Selection

**Class**: `TemplateSelector`

**Key Methods**:
- `select_template()` - Choose template based on project context
- `customize_template(template)` - Generate customized content
- `recommend_modular_structure()` - Determine if modular architecture needed

**Template Matrix**:

| Project Type | Team Size | Target Lines | Complexity |
|--------------|-----------|--------------|------------|
| Web App | Solo | 75 | Minimal |
| API | Small (<10) | 125 | Core |
| Full-Stack | Medium (10-50) | 200 | Detailed |
| Library | Large (50+) | 275 | Comprehensive |

**Supported Project Types**:
- `web_app` - Frontend-focused (React, Vue, Angular)
- `api` - Backend services (REST, GraphQL)
- `fullstack` - Integrated frontend + backend
- `cli` - Command-line tools
- `library` - Reusable packages
- `mobile` - React Native, Flutter
- `desktop` - Electron, Tauri

**Supported Tech Stacks**:
- TypeScript/JavaScript (React, Vue, Angular, Node)
- Python (Django, FastAPI, Flask)
- Go (Gin, Echo)
- Java/Kotlin (Spring Boot)
- Ruby (Rails)
- And more...

---

## Use Cases

### 1. Analyze Existing CLAUDE.md

**Scenario**: You have a CLAUDE.md file and want quality feedback.

**Input**: Existing file content + project context

**Output**:
- Quality score (0-100)
- Missing sections identified
- Issues and warnings
- Prioritized recommendations

**Example**:
```
Quality Score: 75/100

Missing Sections:
- Testing Requirements
- Error Handling Patterns

Recommendations:
1. Add testing requirements section
2. Reduce file length from 320 to <300 lines
3. Consider modular architecture
```

---

### 2. Generate New CLAUDE.md from Scratch

**Scenario**: Starting new project, need CLAUDE.md file.

**Input**: Project context (type, tech stack, team size, phase)

**Output**: Complete CLAUDE.md tailored to your specifications

**Generated Sections**:
- Quick Navigation (if modular)
- Core Principles
- Tech Stack
- Workflow Instructions
- Testing Requirements
- Error Handling
- Documentation Standards
- Performance Guidelines

---

### 3. Enhance Existing File

**Scenario**: Your CLAUDE.md is missing important sections.

**Input**: Current content + sections to add

**Output**: Enhanced file with new sections, preserving existing content

**Preservation**:
- Keeps all existing content intact
- Adds new sections seamlessly
- Maintains consistent formatting
- Respects your style choices

---

### 4. Generate Modular Architecture

**Scenario**: Large project needs separate CLAUDE.md files.

**Input**: Project context + modular flag + subdirectories

**Output**:
- Root CLAUDE.md (navigation hub, <150 lines)
- backend/CLAUDE.md (API, database, testing)
- frontend/CLAUDE.md (components, state, styling)
- database/CLAUDE.md (schema, migrations, queries)
- .github/CLAUDE.md (CI/CD workflows)

**When Recommended**:
- Full-stack projects
- Large teams (10+ developers)
- Production/enterprise phase
- 3+ major tech components

---

### 5. Validate Before Commit

**Scenario**: Quick quality check before committing.

**Input**: Current CLAUDE.md content

**Output**:
- Pass/fail status
- Validation results (5 checks)
- Errors and warnings
- Pass/fail counts

**Validation Checks**:
1. File length (20-300 lines)
2. Structure (required sections present)
3. Formatting (markdown quality)
4. Completeness (essential content)
5. Anti-patterns (security, placeholders)

---

## Sample Data

### Sample Input

See [sample_input.json](sample_input.json) for 6 realistic scenarios:

1. **analyze_existing** - Analyze basic CLAUDE.md file
2. **create_new_fullstack** - Generate modular full-stack setup
3. **enhance_with_missing_sections** - Add specific sections
4. **create_modular_architecture** - Large team, enterprise setup
5. **validate_existing** - Validate production-ready file
6. **generate_context_specific** - Backend-only file

### Expected Output

See [expected_output.json](expected_output.json) for:

- Analysis reports with quality scores
- Generated CLAUDE.md content
- Validation results
- Enhanced file examples

---

## Best Practices

### Critical Validation Rule ⚠️

**"Always validate your output against official native examples before declaring complete."**

Before finalizing any CLAUDE.md generation:
1. Compare output against `/update-claude-md` slash command format
2. Check official Claude Code documentation for required sections
3. Verify all native format sections are present (Overview, Project Structure, File Structure, Setup & Installation, Architecture, etc.)
4. Cross-check against reference examples in `examples/` folder

### For New Projects

1. **Start Minimal** - Generate 50-100 line file, expand as needed
2. **Add Tech Stack Early** - Include technologies immediately
3. **Update with Team Growth** - Regenerate when team size changes
4. **Consider Modular** - Use separate files if >3 major components

### For Existing Projects

1. **Analyze First** - Understand current state before changes
2. **Preserve Custom Content** - Don't overwrite your specific guidelines
3. **Validate Regularly** - Check quality when stack or team changes
4. **Iterate** - Start with enhancements, full regeneration if needed

### General Guidelines

1. **Keep Root Concise** - Max 150 lines, use as navigation hub
2. **Use Context Files** - backend/, frontend/, etc. for details
3. **Avoid Duplication** - Each guideline appears once
4. **Link External Docs** - Don't copy official documentation
5. **Update Quarterly** - Review and refresh every 3 months

---

## Configuration

### Project Context Parameters

```json
{
  "type": "fullstack",                              // Project type
  "tech_stack": ["typescript", "react", "node"],    // Technologies
  "team_size": "small",                             // Team size
  "phase": "mvp",                                   // Development phase
  "workflows": ["tdd", "cicd"],                     // Key workflows
  "modular": true,                                  // Modular architecture
  "subdirectories": ["backend", "frontend"]         // Subdirs for context files
}
```

#### Type Options
- `web_app` - Frontend-focused
- `api` - Backend services
- `fullstack` - Full-stack application
- `cli` - Command-line tool
- `library` - Reusable package
- `mobile` - Mobile application
- `desktop` - Desktop application

#### Team Size Options
- `solo` - 1 developer
- `small` - 2-9 developers
- `medium` - 10-49 developers
- `large` - 50+ developers

#### Phase Options
- `prototype` - Early exploration
- `mvp` - Minimum viable product
- `production` - Production system
- `enterprise` - Enterprise-grade

---

## Troubleshooting

### Quality Score Lower Than Expected

**Issue**: Quality score is 35/100

**Solutions**:
1. Check file length (should be 20-300 lines)
2. Add missing required sections (Core Principles, Workflow)
3. Include code examples
4. Add tech stack references
5. Consider modular architecture if >300 lines

---

### Generated Content Too Generic

**Issue**: CLAUDE.md lacks specific guidance

**Solutions**:
1. Provide detailed tech stack (specific frameworks/versions)
2. Specify workflows (TDD, CI/CD, documentation-first)
3. Include team size for appropriate complexity
4. Add development phase for priority focus
5. Customize generated content for your needs

---

### Modular Architecture Not Recommended

**Issue**: Single file generated, wanted modular

**Solutions**:
1. Set `"modular": true` explicitly
2. Ensure project type is `fullstack`
3. Use team size `medium` or `large`
4. Specify phase as `production` or `enterprise`
5. Provide 3+ tech stack components

---

## Version

**Version**: 1.0.0
**Last Updated**: November 2025
**Compatible**: Claude Code 2.0+, Claude Apps, Claude API

---

## Contributing

Found a bug or have a suggestion? This skill is part of the [claude-code-skills-factory](https://github.com/anthropics/claude-code-skills-factory) repository.

---

## License

MIT License - See LICENSE file for details

---

## Companion Agent: claude-md-guardian πŸ›‘οΈ

For automatic CLAUDE.md maintenance throughout your project lifecycle, use the **claude-md-guardian** agent:

### What It Does

- **Auto-Sync**: Updates CLAUDE.md based on project changes
- **Background Operation**: Works independently after milestones
- **Smart Detection**: Only updates when significant changes occur
- **Token-Efficient**: Uses haiku model for routine updates

### When It Triggers

**Automatically**:
- SessionStart (checks git changes)
- After feature completion
- After major refactoring
- After new dependencies added
- After architecture changes

**Manually**:
- Via `/enhance-claude-md` slash command
- Direct invocation

### Installation

```bash
# User-level (all projects)
cp generated-agents/claude-md-guardian/claude-md-guardian.md ~/.claude/agents/

# Project-level (current project)
cp generated-agents/claude-md-guardian/claude-md-guardian.md .claude/agents/
```

### How They Work Together

```
claude-md-guardian (agent) β†’ Uses β†’ claude-md-enhancer (skill)
                      ↓
         Detects changes β†’ Invokes skill β†’ Updates CLAUDE.md
```

**Result**: Your CLAUDE.md stays synchronized with your codebase automatically!

See `generated-agents/claude-md-guardian/README.md` for complete agent documentation.

---

## Support

- **Documentation**: See [SKILL.md](SKILL.md) for complete documentation
- **Examples**: See [HOW_TO_USE.md](HOW_TO_USE.md) for usage examples
- **Companion Agent**: See `../../generated-agents/claude-md-guardian/README.md`
- **Slash Command**: See `../../generated-commands/enhance-claude-md/README.md`
- **Issues**: Report bugs in the main repository
- **Community**: Share your CLAUDE.md setups and best practices

---

**Happy coding with Claude! πŸš€**

Make your AI-assisted development more efficient with well-structured CLAUDE.md files and automatic maintenance via claude-md-guardian!

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall