{"id":"84c4eac0-642a-4533-ae78-e1d47aeeb3b8","shortId":"9QwVQq","kind":"skill","title":"agent-md-refactor","tagline":"Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.","description":"# Agent MD Refactor\n\nRefactor 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.\n\n---\n\n## Triggers\n\nUse this skill when:\n- \"refactor my AGENTS.md\" / \"refactor my CLAUDE.md\"\n- \"split my agent instructions\"\n- \"organize my CLAUDE.md file\"\n- \"my AGENTS.md is too long\"\n- \"progressive disclosure for my instructions\"\n- \"clean up my agent config\"\n\n---\n\n## Quick Reference\n\n| Phase | Action | Output |\n|-------|--------|--------|\n| 1. Analyze | Find contradictions | List of conflicts to resolve |\n| 2. Extract | Identify essentials | Core instructions for root file |\n| 3. Categorize | Group remaining instructions | Logical categories |\n| 4. Structure | Create file hierarchy | Root + linked files |\n| 5. Prune | Flag for deletion | Redundant/vague instructions |\n\n---\n\n## Process\n\n### Phase 1: Find Contradictions\n\nIdentify any instructions that conflict with each other.\n\n**Look for:**\n- Contradictory style guidelines (e.g., \"use semicolons\" vs \"no semicolons\")\n- Conflicting workflow instructions\n- Incompatible tool preferences\n- Mutually exclusive patterns\n\n**For each contradiction found:**\n```markdown\n## Contradiction Found\n\n**Instruction A:** [quote]\n**Instruction B:** [quote]\n\n**Question:** Which should take precedence, or should both be conditional?\n```\n\nAsk the user to resolve before proceeding.\n\n---\n\n### Phase 2: Identify the Essentials\n\nExtract ONLY what belongs in the root agent file. The root should be minimal - information that applies to **every single task**.\n\n**Essential content (keep in root):**\n| Category | Example |\n|----------|---------|\n| Project description | One sentence: \"A React dashboard for analytics\" |\n| Package manager | Only if not npm (e.g., \"Uses pnpm\") |\n| Non-standard commands | Custom build/test/typecheck commands |\n| Critical overrides | Things that MUST override defaults |\n| Universal rules | Applies to 100% of tasks |\n\n**NOT essential (move to linked files):**\n- Language-specific conventions\n- Testing guidelines\n- Code style details\n- Framework patterns\n- Documentation standards\n- Git workflow details\n\n---\n\n### Phase 3: Group the Rest\n\nOrganize remaining instructions into logical categories.\n\n**Common categories:**\n| Category | Contents |\n|----------|----------|\n| `typescript.md` | TS conventions, type patterns, strict mode rules |\n| `testing.md` | Test frameworks, coverage, mocking patterns |\n| `code-style.md` | Formatting, naming, comments, structure |\n| `git-workflow.md` | Commits, branches, PRs, reviews |\n| `architecture.md` | Patterns, folder structure, dependencies |\n| `api-design.md` | REST/GraphQL conventions, error handling |\n| `security.md` | Auth patterns, input validation, secrets |\n| `performance.md` | Optimization rules, caching, lazy loading |\n\n**Grouping rules:**\n1. Each file should be self-contained for its topic\n2. Aim for 3-8 files (not too granular, not too broad)\n3. Name files clearly: `{topic}.md`\n4. Include only actionable instructions\n\n---\n\n### Phase 4: Create the File Structure\n\n**Output structure:**\n```\nproject-root/\n├── CLAUDE.md (or AGENTS.md)     # Minimal root with links\n└── .claude/                      # Or docs/agent-instructions/\n    ├── typescript.md\n    ├── testing.md\n    ├── code-style.md\n    ├── git-workflow.md\n    └── architecture.md\n```\n\n**Root file template:**\n```markdown\n# Project Name\n\nOne-sentence description of the project.\n\n## Quick Reference\n\n- **Package Manager:** pnpm\n- **Build:** `pnpm build`\n- **Test:** `pnpm test`\n- **Typecheck:** `pnpm typecheck`\n\n## Detailed Instructions\n\nFor specific guidelines, see:\n- [TypeScript Conventions](.claude/typescript.md)\n- [Testing Guidelines](.claude/testing.md)\n- [Code Style](.claude/code-style.md)\n- [Git Workflow](.claude/git-workflow.md)\n- [Architecture Patterns](.claude/architecture.md)\n```\n\n**Each linked file template:**\n```markdown\n# {Topic} Guidelines\n\n## Overview\nBrief context for when these guidelines apply.\n\n## Rules\n\n### Rule Category 1\n- Specific, actionable instruction\n- Another specific instruction\n\n### Rule Category 2\n- Specific, actionable instruction\n\n## Examples\n\n### Good\n\\`\\`\\`typescript\n// Example of correct pattern\n\\`\\`\\`\n\n### Avoid\n\\`\\`\\`typescript\n// Example of what not to do\n\\`\\`\\`\n```\n\n---\n\n### Phase 5: Flag for Deletion\n\nIdentify instructions that should be removed entirely.\n\n**Delete if:**\n| Criterion | Example | Why Delete |\n|-----------|---------|------------|\n| Redundant | \"Use TypeScript\" (in a .ts project) | Agent already knows |\n| Too vague | \"Write clean code\" | Not actionable |\n| Overly obvious | \"Don't introduce bugs\" | Wastes context |\n| Default behavior | \"Use descriptive variable names\" | Standard practice |\n| Outdated | References deprecated APIs | No longer applies |\n\n**Output format:**\n```markdown\n## Flagged for Deletion\n\n| Instruction | Reason |\n|-------------|--------|\n| \"Write clean, maintainable code\" | Too vague to be actionable |\n| \"Use TypeScript\" | Redundant - project is already TS |\n| \"Don't commit secrets\" | Agent already knows this |\n| \"Follow best practices\" | Meaningless without specifics |\n```\n\n---\n\n## Execution Checklist\n\n```\n[ ] Phase 1: All contradictions identified and resolved\n[ ] Phase 2: Root file contains ONLY essentials\n[ ] Phase 3: All remaining instructions categorized\n[ ] Phase 4: File structure created with proper links\n[ ] Phase 5: Redundant/vague instructions removed\n[ ] Verify: Each linked file is self-contained\n[ ] Verify: Root file is under 50 lines\n[ ] Verify: All links work correctly\n```\n\n---\n\n## Anti-Patterns\n\n| Avoid | Why | Instead |\n|-------|-----|---------|\n| Keeping everything in root | Bloated, hard to maintain | Split into linked files |\n| Too many categories | Fragmentation | Consolidate related topics |\n| Vague instructions | Wastes tokens, no value | Be specific or delete |\n| Duplicating defaults | Agent already knows | Only override when needed |\n| Deep nesting | Hard to navigate | Flat structure with links |\n\n---\n\n## Examples\n\n### Before (Bloated Root)\n```markdown\n# CLAUDE.md\n\nThis is a React project.\n\n## Code Style\n- Use 2 spaces\n- Use semicolons\n- Prefer const over let\n- Use arrow functions\n... (200 more lines)\n\n## Testing\n- Use Jest\n- Coverage > 80%\n... (100 more lines)\n\n## TypeScript\n- Enable strict mode\n... (150 more lines)\n```\n\n### After (Progressive Disclosure)\n```markdown\n# CLAUDE.md\n\nReact dashboard for real-time analytics visualization.\n\n## Commands\n- `pnpm dev` - Start development server\n- `pnpm test` - Run tests with coverage\n- `pnpm build` - Production build\n\n## Guidelines\n- [Code Style](.claude/code-style.md)\n- [Testing](.claude/testing.md)\n- [TypeScript](.claude/typescript.md)\n```\n\n---\n\n## Verification\n\nAfter refactoring, verify:\n\n1. **Root file is minimal** - Under 50 lines, only universal info\n2. **Links work** - All referenced files exist\n3. **No contradictions** - Instructions are consistent\n4. **Actionable content** - Every instruction is specific\n5. **Complete coverage** - No instructions were lost (unless flagged for deletion)\n6. **Self-contained files** - Each linked file stands alone\n\n---","tags":["agent","refactor","toolkit","softaworks","agent-skills","automation","claude","claude-code","coding-agent","development"],"capabilities":["skill","source-softaworks","skill-agent-md-refactor","topic-agent-skills","topic-automation","topic-claude","topic-claude-code","topic-coding-agent","topic-development"],"categories":["agent-toolkit"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/softaworks/agent-toolkit/agent-md-refactor","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add softaworks/agent-toolkit","source_repo":"https://github.com/softaworks/agent-toolkit","install_from":"skills.sh"}},"qualityScore":"0.700","qualityRationale":"deterministic score 0.70 from registry signals: · indexed on github topic:agent-skills · 1847 github stars · SKILL.md body (7,190 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:52:55.929Z","embedding":null,"createdAt":"2026-04-18T20:27:47.670Z","updatedAt":"2026-05-18T18:52:55.929Z","lastSeenAt":"2026-05-18T18:52:55.929Z","tsv":"'-8':369 '1':94,136,354,480,607,796 '100':266,745 '150':752 '2':103,198,365,489,614,726,807 '200':737 '3':112,292,368,377,621,814 '4':119,383,389,627,820 '5':127,509,635,827 '50':652,802 '6':838 '80':744 'action':92,386,482,491,542,582,821 'agent':2,11,26,31,68,87,209,533,594,696 'agent-md-refactor':1 'agents.md':7,34,62,75,401 'aim':366 'alon':847 'alreadi':534,588,595,697 'analyt':238,766 'analyz':95 'anoth':484 'anti':660 'anti-pattern':659 'api':562 'api-design.md':335 'appli':218,264,476,565 'architectur':459 'architecture.md':330,413 'arrow':735 'ask':190 'auth':341 'avoid':500,662 'b':178 'behavior':552 'belong':205 'best':599 'bloat':6,30,669,714 'branch':327 'brief':470 'broad':376 'bug':548 'build':432,434,781,783 'build/test/typecheck':253 'cach':349 'categor':53,113,625 'categori':118,228,301,303,304,479,488,679 'checklist':605 'claud':406 'claude.md':8,35,65,72,399,717,759 'claude/architecture.md':461 'claude/code-style.md':455,787 'claude/git-workflow.md':458 'claude/testing.md':452,789 'claude/typescript.md':449,791 'clean':84,539,575 'clear':380 'code':281,453,540,577,723,785 'code-style.md':320,411 'command':251,254,768 'comment':323 'commit':326,592 'common':302 'complet':828 'condit':189 'config':88 'conflict':100,143,158 'consist':819 'consolid':681 'const':731 'contain':361,617,646,841 'content':224,305,822 'context':471,550 'contradict':97,138,169,172,609,816 'contradictori':149 'convent':278,308,337,448 'copilot.md':36 'core':107 'correct':498,658 'coverag':317,743,779,829 'creat':121,390,630 'criterion':522 'critic':255 'custom':252 'dashboard':236,761 'deep':703 'default':261,551,695 'delet':131,512,520,525,571,693,837 'depend':334 'deprec':561 'descript':231,423,554 'detail':283,290,441 'dev':770 'develop':772 'disclosur':17,41,80,757 'docs/agent-instructions':408 'document':25,286 'duplic':694 'e.g':152,245 'enabl':749 'entir':519 'error':338 'essenti':44,106,201,223,270,619 'etc':37 'everi':220,823 'everyth':666 'exampl':229,493,496,502,523,712 'exclus':165 'execut':604 'exist':813 'extract':104,202 'file':13,21,33,54,73,111,122,126,210,274,356,370,379,392,415,464,616,628,642,649,676,798,812,842,845 'find':96,137 'flag':129,510,569,835 'flat':708 'folder':332 'follow':15,39,598 'format':321,567 'found':170,173 'fragment':680 'framework':284,316 'function':736 'git':288,456 'git-workflow.md':325,412 'good':494 'granular':373 'group':114,293,352 'guidelin':151,280,445,451,468,475,784 'handl':339 'hard':670,705 'hierarchi':123 'identifi':105,139,199,513,610 'includ':384 'incompat':161 'info':806 'inform':216 'input':343 'instead':664 'instruct':12,32,69,83,108,116,133,141,160,174,177,298,387,442,483,486,492,514,572,624,637,685,817,824,831 'introduc':547 'jest':742 'keep':43,225,665 'know':535,596,698 'languag':276 'language-specif':275 'lazi':350 'let':733 'line':653,739,747,754,803 'link':24,52,125,273,405,463,633,641,656,675,711,808,844 'list':98 'load':351 'logic':117,300 'long':78 'longer':564 'look':147 'lost':833 'maintain':576,672 'manag':240,430 'mani':678 'markdown':171,417,466,568,716,758 'md':3,27,382 'meaningless':601 'minim':215,402,800 'mock':318 'mode':312,751 'monolith':20 'move':271 'must':259 'mutual':164 'name':322,378,419,556 'navig':707 'need':702 'nest':704 'non':249 'non-standard':248 'npm':244 'obvious':544 'one':232,421 'one-sent':420 'optim':347 'organ':23,48,70,296 'outdat':559 'output':93,394,566 'over':543 'overrid':256,260,700 'overview':469 'packag':239,429 'pattern':166,285,310,319,331,342,460,499,661 'performance.md':346 'phase':91,135,197,291,388,508,606,613,620,626,634 'pnpm':247,431,433,436,439,769,774,780 'practic':558,600 'preced':184 'prefer':163,730 'principl':18,42 'proceed':196 'process':134 'product':782 'progress':16,40,79,756 'project':230,397,418,426,532,586,722 'project-root':396 'proper':632 'prs':328 'prune':128 'question':180 'quick':89,427 'quot':176,179 'react':235,721,760 'real':764 'real-tim':763 'reason':573 'redund':526,585 'redundant/vague':132,636 'refactor':4,5,28,29,60,63,794 'refer':90,428,560 'referenc':811 'relat':682 'remain':115,297,623 'remov':518,638 'resolv':102,194,612 'rest':50,295 'rest/graphql':336 'review':329 'root':46,110,124,208,212,227,398,403,414,615,648,668,715,797 'rule':263,313,348,353,477,478,487 'run':776 'secret':345,593 'security.md':340 'see':446 'self':360,645,840 'self-contain':359,644,839 'semicolon':154,157,729 'sentenc':233,422 'server':773 'similar':10 'singl':221 'skill':58 'skill-agent-md-refactor' 'source-softaworks' 'space':727 'specif':277,444,481,485,490,603,691,826 'split':19,66,673 'stand':846 'standard':250,287,557 'start':771 'strict':311,750 'structur':120,324,333,393,395,629,709 'style':150,282,454,724,786 'take':183 'task':222,268 'templat':416,465 'test':279,315,435,437,450,740,775,777,788 'testing.md':314,410 'thing':257 'time':765 'token':687 'tool':162 'topic':364,381,467,683 'topic-agent-skills' 'topic-automation' 'topic-claude' 'topic-claude-code' 'topic-coding-agent' 'topic-development' 'trigger':55 'ts':307,531,589 'type':309 'typecheck':438,440 'typescript':447,495,501,528,584,748,790 'typescript.md':306,409 'univers':262,805 'unless':834 'use':56,153,246,527,553,583,725,728,734,741 'user':192 'vagu':537,579,684 'valid':344 'valu':689 'variabl':555 'verif':792 'verifi':639,647,654,795 'visual':767 'vs':155 'wast':549,686 'without':602 'work':657,809 'workflow':159,289,457 'write':538,574","prices":[{"id":"169465ee-8562-4926-b1db-83ab0e5834a5","listingId":"84c4eac0-642a-4533-ae78-e1d47aeeb3b8","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"softaworks","category":"agent-toolkit","install_from":"skills.sh"},"createdAt":"2026-04-18T20:27:47.670Z"}],"sources":[{"listingId":"84c4eac0-642a-4533-ae78-e1d47aeeb3b8","source":"github","sourceId":"softaworks/agent-toolkit/agent-md-refactor","sourceUrl":"https://github.com/softaworks/agent-toolkit/tree/main/skills/agent-md-refactor","isPrimary":false,"firstSeenAt":"2026-04-18T21:54:20.205Z","lastSeenAt":"2026-05-18T18:52:55.929Z"},{"listingId":"84c4eac0-642a-4533-ae78-e1d47aeeb3b8","source":"skills_sh","sourceId":"softaworks/agent-toolkit/agent-md-refactor","sourceUrl":"https://skills.sh/softaworks/agent-toolkit/agent-md-refactor","isPrimary":true,"firstSeenAt":"2026-04-18T20:27:47.670Z","lastSeenAt":"2026-05-07T22:40:50.643Z"}],"details":{"listingId":"84c4eac0-642a-4533-ae78-e1d47aeeb3b8","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"softaworks","slug":"agent-md-refactor","github":{"repo":"softaworks/agent-toolkit","stars":1847,"topics":["agent-skills","ai","automation","claude","claude-code","coding-agent","development"],"license":"mit","html_url":"https://github.com/softaworks/agent-toolkit","pushed_at":"2026-03-05T16:46:24Z","description":"A curated collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities across development, documentation, planning, and professional workflows.","skill_md_sha":"d4ee2b5babb59b328972e2bae3d205d79b602333","skill_md_path":"skills/agent-md-refactor/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/softaworks/agent-toolkit/tree/main/skills/agent-md-refactor"},"layout":"multi","source":"github","category":"agent-toolkit","frontmatter":{"name":"agent-md-refactor","license":"MIT","description":"Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation."},"skills_sh_url":"https://skills.sh/softaworks/agent-toolkit/agent-md-refactor"},"updatedAt":"2026-05-18T18:52:55.929Z"}}