# Claude Md Enhancer

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-alirezarezvani-claude-code-skill-factory-claude-md-enhancer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [alirezarezvani](https://agentstack.voostack.com/s/alirezarezvani)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [alirezarezvani](https://github.com/alirezarezvani)
- **Source:** https://github.com/alirezarezvani/claude-code-skill-factory/tree/dev/generated-skills/claude-md-enhancer
- **Website:** https://medium.com/@alirezarezvani/the-claude-skills-factory-how-you-can-generate-production-ready-ai-tools-in-15-minutes-eb0b86087f31?sk=4c0f7e762b9d7caf49d4234a978f3b0a

## Install

```sh
agentstack add skill-alirezarezvani-claude-code-skill-factory-claude-md-enhancer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 300 lines)
- `validate_structure()` - Verify required sections present
- `validate_formatting()` - Check markdown formatting quality
- `validate_completeness()` - Ensure critical information included

### generator.py
Generates new CLAUDE.md content or missing sections based on templates.

**Key Functions**:
- `generate_root_file()` - Create main CLAUDE.md orchestrator
- `generate_context_file()` - Create context-specific files (backend, frontend, etc.)
- `generate_section()` - Generate individual sections (tech stack, workflows, etc.)
- `merge_with_existing()` - Add new sections to existing files

### template_selector.py
Selects appropriate template based on project context.

**Key Functions**:
- `select_template()` - Choose template based on project type and team size
- `customize_template()` - Adapt template to tech stack
- `determine_complexity()` - Calculate appropriate detail level
- `recommend_modular_structure()` - Suggest subdirectory organization

## 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 with minimal template (50-100 lines) and grow as needed
2. Use modular architecture for projects with >3 major components
3. Include tech stack reference immediately
4. Add workflow instructions before team grows beyond 5 people

### For Enhancement
1. Analyze before modifying - understand current structure first
2. Preserve custom content - only enhance, don't replace
3. Validate after changes - ensure improvements don't break existing patterns
4. Test with Claude Code - verify guidelines work as intended

### General Guidelines
1. **Keep root file concise** - Max 150 lines, use as navigation hub
2. **Use context-specific files** - backend/CLAUDE.md, frontend/CLAUDE.md, etc.
3. **Avoid duplication** - Each guideline should appear once
4. **Link to external docs** - Don't copy official documentation
5. **Update regularly** - Review guidelines quarterly or when stack changes

## Limitations

### Technical Constraints
- Requires valid project context for accurate template selection
- Tech stack detection is based on keywords, may need manual refinement
- Modular file generation assumes standard directory structure

### Scope Boundaries
- Focuses on CLAUDE.md structure, not project-specific business logic
- Best practice recommendations are general, may need industry-specific customization
- Validation is guideline-based, not enforcement (no automated fixes without approval)

### When NOT to Use
- For non-Claude AI tools (this is Claude Code specific)
- For projects that don't use Claude Code or similar AI assistants
- When you need highly specialized domain guidelines (legal, medical compliance)

## Template Categories

### By Size
- **Minimal** (50 lines) - Solo developers, prototypes, hackathons
- **Core** (100-150 lines) - Small teams, MVPs, standard projects
- **Detailed** (200-300 lines) - Large teams, production systems, enterprise

### By Project Type
- **Web App** - Frontend-focused (React, Vue, Angular)
- **API** - Backend services (REST, GraphQL, microservices)
- **Full-Stack** - Integrated frontend + backend
- **CLI** - Command-line tools and utilities
- **Library** - Reusable packages and frameworks
- **Mobile** - React Native, Flutter, native iOS/Android

### By Tech Stack
- **TypeScript/Node** - Modern JavaScript ecosystem
- **Python** - Django, FastAPI, Flask
- **Go** - Gin, Echo, native services
- **Java/Kotlin** - Spring Boot, enterprise Java
- **Ruby** - Rails, Sinatra

## Quality Metrics

### File Quality Score (0-100)

Calculated based on:
- **Length appropriateness** (25 points) - Not too short or long
- **Section completeness** (25 points) - Required sections present
- **Formatting quality** (20 points) - Proper markdown structure
- **Content specificity** (15 points) - Tailored to project, not generic
- **Modular organization** (15 points) - Uses subdirectory files when appropriate

### Recommendations Priority

- **Critical** - Missing required sections, file too long (>400 lines)
- **High** - Missing important sections, formatting issues
- **Medium** - Could add optional sections, minor improvements
- **Low** - Nice-to-have enhancements, stylistic suggestions

## Advanced Features

### Modular Architecture Support

Automatically generates context-specific files:

```
project-root/
├── CLAUDE.md                 # Root orchestrator (100-150 lines)
├── backend/
│   └── CLAUDE.md            # Backend-specific (150-200 lines)
├── frontend/
│   └── CLAUDE.md            # Frontend-specific (150-200 lines)
├── database/
│   └── CLAUDE.md            # Database operations (100-150 lines)
└── .github/
    └── CLAUDE.md            # CI/CD workflows (100-150 lines)
```

### Tech Stack Detection

Automatically detects technologies from:
- `package.json` (Node.js/TypeScript)
- `requirements.txt` or `pyproject.toml` (Python)
- `go.mod` (Go)
- `Cargo.toml` (Rust)
- `pom.xml` or `build.gradle` (Java)

### Team Size Adaptation

Adjusts detail level:
- **Solo**: Minimal guidelines, focus on efficiency
- **Small (<10)**: Core guidelines, workflow basics
- **Medium (10-50)**: Detailed guidelines, team coordination
- **Large (50+)**: Comprehensive guidelines, process enforcement

## References

- **Anthropic Claude Code Docs**: https://docs.claude.com/en/docs/claude-code
- **CLAUDE.md Best Practices**: Based on community patterns and Anthropic guidance
- **Example CLAUDE.md Files**: See `examples/` folder for 6 reference implementations covering different project types and team sizes

## Version

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

Remember: The goal is to make Claude more efficient and context-aware, not to create bureaucracy. Start simple, iterate based on real usage, and automate quality checks where possible.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [alirezarezvani](https://github.com/alirezarezvani)
- **Source:** [alirezarezvani/claude-code-skill-factory](https://github.com/alirezarezvani/claude-code-skill-factory)
- **License:** MIT
- **Homepage:** https://medium.com/@alirezarezvani/the-claude-skills-factory-how-you-can-generate-production-ready-ai-tools-in-15-minutes-eb0b86087f31?sk=4c0f7e762b9d7caf49d4234a978f3b0a

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alirezarezvani-claude-code-skill-factory-claude-md-enhancer
- Seller: https://agentstack.voostack.com/s/alirezarezvani
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.