agent-md-refactor

# Agent Context Documentation - Refactor & Template

This skill helps you refactor large, monolithic agent instruction files (AGENTS.md, CLAUDE.md, etc.) into a well-structured, modular documentation system following progressive disclosure principles.

## What This Skill Does

1. **Analyzes** existing agent instruction files to identify areas for improvement
2. **Separates** project context (AGENTS.md) from executable capabilities (SKILLS.md)
3. **Generates** structured templates for both documentation types
4. **Creates** comprehensive documentation for frontend and backend projects
5. **Establishes** clear separation of concerns between "what the project is" and "what the agent can do"

## When to Use This Skill

Use this skill when you encounter:
- Large AGENTS.md or CLAUDE.md files (>1000 lines) that are hard to navigate
- Mixed content (context + procedures) in a single file
- Need to document a new project for AI agents
- Want to create reusable documentation templates
- Setting up agent context for team collaboration
- Converting README-style docs to agent-optimized format

## Documentation Structure

This skill creates a two-file system:

### AGENTS.md (Project Context)
**Purpose**: Defines WHAT the project is and HOW it's structured

**Contains**:
- ✅ Project identification and tech stack
- ✅ Architecture and SOLID principles
- ✅ Layer structure and design patterns
- ✅ Data domain and entities
- ✅ Code conventions and naming
- ✅ Configuration and environment variables
- ✅ Critical rules and constraints
- ✅ Cross-references to SKILLS.md

**Does NOT contain**:
- ❌ Step-by-step procedures
- ❌ Command execution examples
- ❌ Detailed task checklists

### SKILLS.md (Agent Capabilities)
**Purpose**: Defines WHAT the agent CAN DO and HOW to execute tasks

**Contains**:
- ✅ Backend skills (Database, API, Business Logic, Testing, etc.)
- ✅ Frontend skills (Components, State, Routing, Forms, UI/UX, etc.)
- ✅ Transversal skills (Auth, Error Handling, Config, etc.)
- ✅ Step-by-step procedures
- ✅ Command quick reference
- ✅ Code examples and templates
- ✅ Verification checklists
- ✅ Skill matrix for quick lookup

**Does NOT contain**:
- ❌ Project-specific architecture details
- ❌ Entity relationships and schemas
- ❌ Environment configuration

## Templates Provided

This skill includes three template files:

1. **AGENTS_TEMPLATE.md** - Comprehensive template for project context
2. **SKILLS_TEMPLATE.md** - Comprehensive template for agent capabilities  
3. **SKILL.md** (this file) - Skill registration for skills.sh

## Basic Skills Coverage

### Backend Projects
- Database Management (migrations, queries, optimization)
- API Development (REST/GraphQL endpoints)
- Business Logic Implementation
- Integration & External Services
- Testing & Quality Assurance
- Performance Optimization

### Frontend Projects
- Component Development
- State Management
- API Integration & Data Fetching
- Routing & Navigation
- Form Handling & Validation
- UI/UX & Styling
- Performance & Optimization

### Transversal (Both)
- Authentication & Authorization
- Error Handling
- Configuration Management

## Usage Examples

### Example 1: Refactor Existing Documentation
```
User: "My AGENTS.md is 2000 lines and hard to navigate. Can you refactor it?"
Agent: [Uses this skill to split into AGENTS.md + SKILLS.md]
```

### Example 2: Create Documentation for New Project
```
User: "I have a new Next.js + FastAPI project. Create agent documentation."
Agent: [Uses templates to generate both files with appropriate frontend/backend skills]
```

### Example 3: Add Skills to Existing AGENTS.md
```
User: "I have AGENTS.md but need to document procedures. Add a SKILLS.md file."
Agent: [Generates SKILLS.md complementing existing AGENTS.md]
```

## Key Principles

### Progressive Disclosure
- Start with essential information
- Link to detailed procedures when needed
- Avoid overwhelming with all details upfront

### Separation of Concerns
- **Context** (AGENTS.md): Describes the "shape" of the code
- **Capabilities** (SKILLS.md): Describes how to work with the code

### Cross-Referencing
- Both files reference each other
- No information duplication
- Clear navigation between related concepts

### Technology Agnostic
- Templates work for any language/framework
- Sections can be customized or removed
- Extensible for project-specific needs

## Customization

When generating documentation from templates:

1. **Analyze the project** thoroughly (package.json, pom.xml, etc.)
2. **Determine project type** (Backend, Frontend, Fullstack, CLI, Library)
3. **Select relevant sections** - remove what doesn't apply
4. **Add project-specific sections** as needed
5. **Include real code examples** from the actual project
6. **Verify all commands** actually work
7. **Remove template comments** and instructions
8. **Update cross-references** between files

## Best Practices

### For AGENTS.md
- Be specific about versions and tools
- Include real examples from the project
- Document actual conventions observed in code
- List all critical rules that must never be violated
- Reference SKILLS.md for procedural details

### For SKILLS.md
- Focus on actionable procedures
- Include verified commands that work
- Provide code examples that can be copied
- Add verification checklists
- Reference AGENTS.md for context

### Integration
- Ensure consistency between both files
- Use same terminology
- Keep cross-references updated
- Avoid duplication - each piece of info in one place only

## File Structure Output

After using this skill, you'll have:

```
project-root/
├── AGENTS.md           # Project context and structure
├── SKILLS.md           # Agent capabilities and procedures
├── README.md           # (existing) Human-readable documentation
└── [project files...]
```

## Verification Checklist

After generating documentation, verify:

- [ ] AGENTS.md covers project context comprehensively
- [ ] SKILLS.md includes all relevant procedures
- [ ] No information duplication between files
- [ ] Cross-references work correctly
- [ ] All code examples are from the actual project
- [ ] All commands have been tested and work
- [ ] Template comments and instructions removed
- [ ] Sections not applicable to project removed
- [ ] Project-specific sections added where needed
- [ ] Both files use consistent terminology

## Advanced Features

### Skill Matrix
SKILLS.md includes a skill matrix table for quick reference of what skill to use for each task type.

### Quick Reference
Command quick reference sections for common operations without scrolling through procedures.

### Categorized Skills
Skills organized by domain (Database, API, UI, etc.) for easy navigation.

### Standard Procedures
Reusable procedures for common tasks:
- Adding new features
- Debugging problems
- Refactoring code

## Maintenance

Keep documentation updated when:
- Architecture changes
- New technologies are adopted
- Coding conventions evolve
- New common procedures are established
- Critical rules are added or modified

## Resources

This skill provides:
- `AGENTS_TEMPLATE.md` - Template for project context
- `SKILLS_TEMPLATE.md` - Template for agent capabilities
- Comprehensive examples for both frontend and backend
- SOLID principles guidance
- Clean Architecture patterns

## Output Format

Generated files use:
- ✅ Markdown with proper formatting
- ✅ Emojis for section headers (better visual scanning)
- ✅ Code blocks with syntax highlighting
- ✅ Tables for structured data
- ✅ Checklists for verification
- ✅ Cross-references as markdown links

## Tips for AI Agents

When using this skill:

1. **Read templates first** to understand the structure
2. **Analyze the project thoroughly** before filling templates
3. **Be specific**, not generic - use real project information
4. **Remove inapplicable sections** - not everything fits every project
5. **Add project-specific content** beyond the template
6. **Test commands** before documenting them
7. **Create cross-references** between related sections
8. **Use real code examples** from the project
9. **Follow the separation**: Context in AGENTS.md, Actions in SKILLS.md
10. **Update both files** when making changes to maintain consistency