agent-md-refactor
Refactor bloated AGENTS.md, CLAUDE.md, or similar agent instruction files to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation.
81
72%
Does it follow best practices?
Impact
94%
1.36xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./dist/plugins/agent-md-refactor/skills/agent-md-refactor/SKILL.mdQuality
Discovery
67%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
The description effectively communicates specific capabilities for a well-defined niche (agent instruction file refactoring). Its main weakness is the lack of explicit trigger guidance ('Use when...') which would help Claude know exactly when to select this skill. The trigger terms could also be expanded to include more natural user phrasings.
Suggestions
Add a 'Use when...' clause with explicit triggers like 'Use when the user mentions their AGENTS.md or CLAUDE.md is too long, hard to maintain, or needs reorganization'
Include additional natural trigger terms users might say: 'too long', 'hard to read', 'organize my instructions', 'split documentation', 'simplify agent config'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple concrete actions: 'Refactor bloated AGENTS.md, CLAUDE.md', 'follow progressive disclosure principles', 'Splits monolithic files into organized, linked documentation'. These are specific, actionable capabilities. | 3 / 3 |
Completeness | Clearly answers 'what' (refactor agent instruction files, split into organized documentation), but lacks an explicit 'Use when...' clause. The 'when' is only implied through the word 'bloated'. | 2 / 3 |
Trigger Term Quality | Includes some natural keywords like 'AGENTS.md', 'CLAUDE.md', 'monolithic files', 'refactor', but missing common variations users might say like 'too long', 'organize instructions', 'split up', or 'documentation cleanup'. | 2 / 3 |
Distinctiveness Conflict Risk | Very specific niche targeting agent instruction files (AGENTS.md, CLAUDE.md) with progressive disclosure methodology. Unlikely to conflict with general documentation or refactoring skills due to the specific file types mentioned. | 3 / 3 |
Total | 10 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill provides excellent actionable guidance with clear workflows and concrete examples for refactoring agent instruction files. The 5-phase process is well-structured with validation checkpoints. However, the skill is somewhat verbose and doesn't apply its own progressive disclosure principles—the detailed templates and examples could be moved to linked reference files.
Suggestions
Apply progressive disclosure to this skill itself: move detailed templates (Phase 4 templates, linked file template) to a separate reference file
Remove or condense the 'Triggers' section—Claude can infer when to use this skill from context
Consolidate the Anti-Patterns section with Phase 5 (Flag for Deletion) to reduce redundancy
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary explanation. The triggers section and some table formatting add bulk without proportional value. The anti-patterns section partially duplicates guidance already given in the phases. | 2 / 3 |
Actionability | Provides concrete, executable guidance throughout. Includes specific templates, file structures, markdown examples, and clear criteria tables. The before/after examples are copy-paste ready and demonstrate exactly what to produce. | 3 / 3 |
Workflow Clarity | Clear 5-phase sequence with explicit checkpoints. Phase 1 requires user resolution before proceeding. The execution checklist provides verification steps. Each phase has clear outputs and criteria for completion. | 3 / 3 |
Progressive Disclosure | Ironically, a skill about progressive disclosure is itself a monolithic document. At ~200 lines, the detailed templates and examples could be split into referenced files. The content is well-organized with clear sections, but doesn't practice what it preaches. | 2 / 3 |
Total | 10 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- softaworks/agent-toolkit
- Commit
3027f20
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.