agents-refactor

Files (2)

• LICENSE
• SKILL.md

SKILL.md (first lines)

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

---

## Provenance

- Origin: <https://github.com/softaworks/agent-toolkit> (`agent-md-refactor`)
- Commit: `3027f20f3181758385a1bb8c022d4041dfb4de84`
- License: MIT

## 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:**

```markdown
## 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

From datacosmos-br/agents, MIT.

More from datacosmos-br/agents