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