mgajewskik/agent-md-refactor

Agent MD Refactor

Refactor bloated agent instruction files (AGENTS.md, CLAUDE.md, COPILOT.md, etc.) to follow progressive disclosure principles - keeping essentials at root and organizing the rest into linked, categorized files.

---

Triggers

Use this skill when:

• "refactor my AGENTS.md" / "refactor my CLAUDE.md"
• "split my agent instructions"
• "organize my CLAUDE.md file"
• "my AGENTS.md is too long"
• "progressive disclosure for my instructions"
• "clean up my agent config"

---

Quick Reference

| Phase | Action | Output | |-------|--------|--------| | 1. Analyze | Find contradictions | List of conflicts to resolve | | 2. Extract | Identify essentials | Core instructions for root file | | 3. Categorize | Group remaining instructions | Logical categories | | 4. Structure | Create file hierarchy | Root + linked files | | 5. Prune | Flag for deletion | Redundant/vague instructions |

---

Process

Phase 1: Find Contradictions

Identify any instructions that conflict with each other.

Look for:

• Contradictory style guidelines (e.g., "use semicolons" vs "no semicolons")
• Conflicting workflow instructions
• Incompatible tool preferences
• Mutually exclusive patterns

For each contradiction found:

## Contradiction Found

**Instruction A:** [quote]
**Instruction B:** [quote]

**Question:** Which should take precedence, or should both be conditional?

Ask the user to resolve before proceeding.

---

Phase 2: Identify the Essentials

Extract ONLY what belongs in the root agent file. The root should be minimal - information that applies to every single task.

Essential content (keep in root): | Category | Example | |----------|---------| | Project description | One sentence: "A React dashboard for analytics" | | Package manager | Only if not npm (e.g., "Uses pnpm") | | Non-standard commands | Custom build/test/typecheck commands | | Critical overrides | Things that MUST override defaults | | Universal rules | Applies to 100% of tasks |

NOT essential (move to linked files):

• Language-specific conventions
• Testing guidelines
• Code style details
• Framework patterns
• Documentation standards
• Git workflow details

---

Phase 3: Group the Rest

Organize remaining instructions into logical categories.

Common categories: | Category | Contents | |----------|----------| | typescript.md | TS conventions, type patterns, strict mode rules | | testing.md | Test frameworks, coverage, mocking patterns | | code-style.md | Formatting, naming, comments, structure | | git-workflow.md | Commits, branches, PRs, reviews | | architecture.md | Patterns, folder structure, dependencies | | api-design.md | REST/GraphQL conventions, error handling | | security.md | Auth patterns, input validation, secrets | | performance.md | Optimization rules, caching, lazy loading |

Grouping rules:

1. Each file should be self-contained for its topic
2. Aim for 3-8 files (not too granular, not too broad)
3. Name files clearly: {topic}.md
4. Include only actionable instructions

---

Phase 4: Create the File Structure

Output structure:

project-root/
├── CLAUDE.md (or AGENTS.md)     # Minimal root with links
└── .claude/                      # Or docs/agent-instructions/
    ├── typescript.md
    ├── testing.md
    ├── code-style.md
    ├── git-workflow.md
    └── architecture.md

Root file template:

# Project Name

One-sentence description of the project.

## Quick Reference

- **Package Manager:** pnpm
- **Build:** `pnpm build`
- **Test:** `pnpm test`
- **Typecheck:** `pnpm typecheck`

## Detailed Instructions

For specific guidelines, see:
- [TypeScript Conventions](.claude/typescript.md)
- [Testing Guidelines](.claude/testing.md)
- [Code Style](.claude/code-style.md)
- [Git Workflow](.claude/git-workflow.md)
- [Architecture Patterns](.claude/architecture.md)

Each linked file template:

# {Topic} Guidelines

## Overview
Brief context for when these guidelines apply.

## Rules

### Rule Category 1
- Specific, actionable instruction
- Another specific instruction

### Rule Category 2
- Specific, actionable instruction

## Examples

### Good
\`\`\`typescript
// Example of correct pattern
\`\`\`

### Avoid
\`\`\`typescript
// Example of what not to do
\`\`\`

---

Phase 5: Flag for Deletion

Identify instructions that should be removed entirely.

Delete if: | Criterion | Example | Why Delete | |-----------|---------|------------| | Redundant | "Use TypeScript" (in a .ts project) | Agent already knows | | Too vague | "Write clean code" | Not actionable | | Overly obvious | "Don't introduce bugs" | Wastes context | | Default behavior | "Use descriptive variable names" | Standard practice | | Outdated | References deprecated APIs | No longer applies |

Output format:

## Flagged for Deletion

| Instruction | Reason |
|-------------|--------|
| "Write clean, maintainable code" | Too vague to be actionable |
| "Use TypeScript" | Redundant - project is already TS |
| "Don't commit secrets" | Agent already knows this |
| "Follow best practices" | Meaningless without specifics |

---

Execution Checklist

[ ] Phase 1: All contradictions identified and resolved
[ ] Phase 2: Root file contains ONLY essentials
[ ] Phase 3: All remaining instructions categorized
[ ] Phase 4: File structure created with proper links
[ ] Phase 5: Redundant/vague instructions removed
[ ] Verify: Each linked file is self-contained
[ ] Verify: Root file is under 50 lines
[ ] Verify: All links work correctly

---

Anti-Patterns

| Avoid | Why | Instead | |-------|-----|---------| | Keeping everything in root | Bloated, hard to maintain | Split into linked files | | Too many categories | Fragmentation | Consolidate related topics | | Vague instructions | Wastes tokens, no value | Be specific or delete | | Duplicating defaults | Agent already knows | Only override when needed | | Deep nesting | Hard to navigate | Flat structure with links |

---

Examples

Before (Bloated Root)

# CLAUDE.md

This is a React project.

## Code Style
- Use 2 spaces
- Use semicolons
- Prefer const over let
- Use arrow functions
... (200 more lines)

## Testing
- Use Jest
- Coverage > 80%
... (100 more lines)

## TypeScript
- Enable strict mode
... (150 more lines)

After (Progressive Disclosure)

# CLAUDE.md

React dashboard for real-time analytics visualization.

## Commands
- `pnpm dev` - Start development server
- `pnpm test` - Run tests with coverage
- `pnpm build` - Production build

## Guidelines
- [Code Style](.claude/code-style.md)
- [Testing](.claude/testing.md)
- [TypeScript](.claude/typescript.md)

---

Verification

After refactoring, verify:

1. Root file is minimal - Under 50 lines, only universal info
2. Links work - All referenced files exist
3. No contradictions - Instructions are consistent
4. Actionable content - Every instruction is specific
5. Complete coverage - No instructions were lost (unless flagged for deletion)
6. Self-contained files - Each linked file stands alone

---