claude-md-enhancer

What this skill does

# CLAUDE.md File Enhancer

This skill provides comprehensive CLAUDE.md file generation and enhancement for Claude Code projects. It analyzes existing files, validates against best practices, and generates customized guidelines tailored to your project type, tech stack, and team size.

## Capabilities

- **🆕 Interactive Initialization**: Intelligent workflow that explores your repository, detects project type and tech stack, asks for confirmation, then creates customized CLAUDE.md files
- **✨ 100% Native Format Compliance**: All generated files follow official Claude Code format with project structure diagrams, setup instructions, architecture sections, and file structure explanations (matching `/update-claude-md` slash command)
- **Analyze Existing Files**: Scan and evaluate current CLAUDE.md files for structure, completeness, and quality
- **Validate Best Practices**: Check against Anthropic guidelines (file length, required sections, formatting standards)
- **Generate New Files**: Create complete CLAUDE.md files from scratch for new projects
- **Enhance Existing Files**: Add missing sections, improve structure, and update to latest best practices
- **Modular Architecture**: Support context-specific CLAUDE.md files in subdirectories (backend/, frontend/, docs/)
- **Tech Stack Customization**: Tailor guidelines to specific technologies (TypeScript, Python, Go, React, Vue, etc.)
- **Team Size Adaptation**: Adjust complexity based on team size (solo, small <10, large 10+)
- **Template Selection**: Choose appropriate template based on project complexity and development phase

## Input Requirements

### For Analysis and Enhancement

Provide existing CLAUDE.md file content or file path:

```json
{
  "mode": "enhance",
  "file_path": "CLAUDE.md",
  "content": "[existing CLAUDE.md content]",
  "project_context": {
    "type": "web_app",
    "tech_stack": ["typescript", "react", "node", "postgresql"],
    "team_size": "small",
    "phase": "mvp"
  }
}
```

### For New File Generation

Provide project context:

```json
{
  "mode": "create",
  "project_context": {
    "type": "api",
    "tech_stack": ["python", "fastapi", "postgresql", "docker"],
    "team_size": "medium",
    "phase": "production",
    "workflows": ["tdd", "cicd", "documentation_first"]
  },
  "modular": true,
  "subdirectories": ["backend", "database", "docs"]
}
```

### Context Parameters

- **type**: Project type (`web_app`, `api`, `fullstack`, `cli`, `library`, `mobile`, `desktop`)
- **tech_stack**: Array of technologies (e.g., `["typescript", "react", "node"]`)
- **team_size**: `solo`, `small` (<10), `medium` (10-50), `large` (50+)
- **phase**: Development phase (`prototype`, `mvp`, `production`, `enterprise`)
- **workflows**: Key workflows (`tdd`, `cicd`, `documentation_first`, `agile`, etc.)

## Output Formats

### Analysis Report

```json
{
  "analysis": {
    "file_size": 450,
    "line_count": 320,
    "sections_found": [
      "Quick Navigation",
      "Core Principles",
      "Tech Stack",
      "Workflow Instructions"
    ],
    "missing_sections": [
      "Testing Requirements",
      "Error Handling Patterns"
    ],
    "issues": [
      {
        "type": "length_warning",
        "severity": "medium",
        "message": "File exceeds recommended 300 lines (320 lines)"
      },
      {
        "type": "missing_section",
        "severity": "low",
        "message": "Consider adding 'Testing Requirements' section"
      }
    ],
    "quality_score": 75,
    "recommendations": [
      "Split into modular files (backend/CLAUDE.md, frontend/CLAUDE.md)",
      "Add testing requirements section",
      "Reduce root file to <150 lines"
    ]
  }
}
```

### Generated Content

Complete CLAUDE.md file content or specific sections to add:

```markdown
# CLAUDE.md

This file provides guidance for Claude Code when working with this project.

## Quick Navigation

- [Backend Guidelines](backend/CLAUDE.md)
- [Frontend Guidelines](frontend/CLAUDE.md)
- [Database Operations](database/CLAUDE.md)
- [CI/CD Workflows](.github/CLAUDE.md)

## Core Principles

1. **Test-Driven Development**: Write tests before implementation
2. **Type Safety First**: Use TypeScript strict mode throughout
3. **Component Composition**: Favor small, reusable components
4. **Error Handling**: Always handle errors with proper logging
5. **Documentation Updates**: Keep docs in sync with code changes

[... additional sections based on template ...]
```

## How to Use

### Example 1: Initialize CLAUDE.md for New Project (Interactive)

```
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?
```

**What Happens**:
1. Claude checks if CLAUDE.md exists (it doesn't)
2. Claude explores your repository using built-in commands
3. Claude analyzes: project type, tech stack, team size, workflows
4. Claude shows discoveries and asks for confirmation
5. You confirm the settings
6. Claude creates customized CLAUDE.md file(s)
7. Claude enhances with best practices

**Interactive Flow**:
- ✋ User must confirm before creation
- 🔍 Full visibility into what was discovered
- ⚙️ Option to adjust settings before proceeding

### Example 2: Analyze Existing CLAUDE.md

```
Hey Claude—I just added the "claude-md-enhancer" skill. Can you analyze my current CLAUDE.md file and tell me what's missing or could be improved?
```

### Example 2: Generate New CLAUDE.md for TypeScript Project

```
Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a CLAUDE.md file for my TypeScript React project with a team of 5 developers? We use PostgreSQL, Docker, and follow TDD practices.
```

### Example 3: Enhance Existing File

```
Hey Claude—I just added the "claude-md-enhancer" skill. Can you enhance my existing CLAUDE.md by adding missing sections and improving the structure? Here's my current file: [paste content]
```

### Example 4: Generate Modular Architecture

```
Hey Claude—I just added the "claude-md-enhancer" skill. Can you create a modular CLAUDE.md setup for my full-stack project? I need separate files for backend (Python/FastAPI), frontend (React), and database (PostgreSQL).
```

## Initialization Workflow (New Projects)

When CLAUDE.md doesn't exist in your project, this skill provides an intelligent initialization workflow:

### Workflow Steps

**Step 1: Detection**
- Skill checks if CLAUDE.md exists in project root
- If not found, initialization workflow begins

**Step 2: Repository Exploration**
- Uses Claude Code's built-in `explore` command
- Analyzes project structure, files, and directories
- Examines configuration files (package.json, requirements.txt, go.mod, etc.)
- Reviews existing documentation

**Step 3: Intelligent Analysis**
- **Project Type Detection**: web_app, api, fullstack, cli, library, mobile, desktop
- **Tech Stack Detection**: TypeScript, Python, React, FastAPI, PostgreSQL, Docker, etc.
- **Team Size Estimation**: Based on project complexity (solo, small, medium, large)
- **Development Phase**: prototype, mvp, production, enterprise
- **Workflow Detection**: TDD, CI/CD, documentation-first, agile
- **Structure Recommendation**: Single file vs. modular architecture

**Step 4: User Confirmation** ✋
- Displays all discoveries in clear format
- Shows recommended CLAUDE.md structure
- Asks user to confirm or adjust settings
- **User must explicitly approve** before proceeding

**Step 5: File Creation**
- Generates customized CLAUDE.md based on confirmed settings
- Creates modular files if recommended (backend/, frontend/, etc.)
- Applies tech-specific best practices

**Step 6: Enhancement**
- Validates generated content
- Adds quality improvements
- Ensures completeness

**Step 7: Summary**
- Shows what files were created
- Provides next steps
- Ready for immediate use

### Interactive Example

```
User: "I need a CLAUDE.md for this project"

Claude: "I'll explore your repository first to understand the project.
        [Explores u