| name | agent-md-refactor |
| description | Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation. Use when (1) agent context files are too large or unwieldy, (2) need to separate project context from executable skills, (3) want to create modular documentation structure, (4) refactoring existing documentation for better organization, or (5) creating new agent context documentation from scratch. |
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
- Analyzes existing agent instruction files to identify areas for improvement
- Separates project context (AGENTS.md) from executable capabilities (SKILLS.md)
- Generates structured templates for both documentation types
- Creates comprehensive documentation for frontend and backend projects
- 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:
- AGENTS_TEMPLATE.md - Comprehensive template for project context
- SKILLS_TEMPLATE.md - Comprehensive template for agent capabilities
- 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:
- Analyze the project thoroughly (package.json, pom.xml, etc.)
- Determine project type (Backend, Frontend, Fullstack, CLI, Library)
- Select relevant sections - remove what doesn't apply
- Add project-specific sections as needed
- Include real code examples from the actual project
- Verify all commands actually work
- Remove template comments and instructions
- 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:
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 contextSKILLS_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:
- Read templates first to understand the structure
- Analyze the project thoroughly before filling templates
- Be specific, not generic - use real project information
- Remove inapplicable sections - not everything fits every project
- Add project-specific content beyond the template
- Test commands before documenting them
- Create cross-references between related sections
- Use real code examples from the project
- Follow the separation: Context in AGENTS.md, Actions in SKILLS.md
- Update both files when making changes to maintain consistency
