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.
Install with Tessl CLI
npx tessl i github:softaworks/agent-toolkit --skill agent-md-refactor81
Does it follow best practices?
If you maintain this skill, you can automatically optimize it using the tessl CLI to improve its score:
npx tessl skill review --optimize ./path/to/skillValidation for skill structure
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 language.
Suggestions
Add a 'Use when...' clause with explicit triggers like 'Use when the user mentions their CLAUDE.md or AGENTS.md is too long, wants to reorganize agent instructions, or asks about progressive disclosure for documentation.'
Include additional natural trigger terms users might say: 'too long', 'organize', 'split up instructions', 'documentation structure', 'instruction file cleanup'.
| 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
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-structured, highly actionable skill that provides clear workflows for refactoring agent instruction files. Its main weakness is moderate verbosity - the triggers section is unnecessary, and some tables could be consolidated. The concrete templates, clear phase structure, and validation checkpoints make this immediately usable.
Suggestions
Remove the 'Triggers' section entirely - Claude doesn't need explicit trigger phrases to understand when to apply a skill
Consolidate the 'Essential content' and 'NOT essential' tables in Phase 2 into a single table with a 'Keep/Move' column to reduce redundancy
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably efficient but includes some unnecessary content like the 'Triggers' section (Claude doesn't need trigger phrases) and some tables that could be more compact. The anti-patterns and examples sections add value but could be tighter. | 2 / 3 |
Actionability | Provides concrete, copy-paste ready templates for both root files and linked files, specific file structures, clear criteria tables for what to keep/delete, and executable checklists. The examples show exact before/after transformations. | 3 / 3 |
Workflow Clarity | Excellent 5-phase workflow with clear sequencing, explicit validation checkpoints (Phase 1 requires user resolution before proceeding), and a comprehensive execution checklist. The feedback loop for contradictions is well-designed. | 3 / 3 |
Progressive Disclosure | Ironic given the skill's purpose, but it practices what it preaches - clear quick reference table at top, detailed phases below, and well-organized sections. Content is appropriately structured for a single-file skill of this complexity. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
87%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 14 / 16 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
description_trigger_hint | Description may be missing an explicit 'when to use' trigger hint (e.g., 'Use when...') | Warning |
metadata_version | 'metadata' field is not a dictionary | Warning |
Total | 14 / 16 Passed | |
- 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.