State-machine driven iterative planning and execution for complex coding tasks. Cycle: Explore → Plan → Execute → Reflect → Pivot. Filesystem as persistent memory. Use for multi-file tasks, migrations, refactoring, failed tasks, or anything non-trivial.
57
64%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./src/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 a structured methodology for complex coding tasks and includes an explicit 'Use for...' clause, which is a strength. However, the specificity of actions is at the process/methodology level rather than concrete coding actions, and the catch-all phrase 'anything non-trivial' weakens distinctiveness. Trigger terms cover some common scenarios but miss natural user language variations.
Suggestions
Replace 'anything non-trivial' with more specific trigger scenarios (e.g., 'large-scale changes spanning multiple modules', 'tasks requiring investigation before implementation') to reduce conflict risk with other skills.
Add more natural user-facing trigger terms such as 'break down', 'step by step', 'complex project', 'large codebase change', 'systematic approach' to improve keyword coverage.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (complex coding tasks) and describes the methodology (state-machine driven iterative planning with Explore → Plan → Execute → Reflect → Pivot cycle), but the actual concrete actions are abstract process steps rather than specific coding actions like 'refactor modules' or 'migrate database schemas'. | 2 / 3 |
Completeness | Clearly answers both 'what' (state-machine driven iterative planning and execution with a defined cycle and filesystem as persistent memory) and 'when' (explicitly states 'Use for multi-file tasks, migrations, refactoring, failed tasks, or anything non-trivial'). | 3 / 3 |
Trigger Term Quality | Includes some useful trigger terms like 'multi-file tasks', 'migrations', 'refactoring', and 'failed tasks', but misses many natural variations users might say such as 'large refactor', 'complex project', 'step by step', 'break down this task', or 'code migration'. The term 'non-trivial' is vague and not something users typically say. | 2 / 3 |
Distinctiveness Conflict Risk | The methodology-focused description (state machine, iterative planning) is somewhat distinctive, but terms like 'refactoring', 'migrations', and 'complex coding tasks' could easily overlap with other coding-related skills. The catch-all 'anything non-trivial' significantly increases conflict risk. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a highly sophisticated and deeply actionable planning protocol with excellent workflow clarity and validation checkpoints. Its primary weakness is extreme verbosity — the skill is far too long for a SKILL.md file, with significant redundancy and inline detail that belongs in the referenced files. The progressive disclosure architecture exists (many references/) but isn't leveraged enough, resulting in a document that competes heavily with context window space.
Suggestions
Move the detailed Consolidated File Management section (compression protocol, format, rules, failsafe) to references/file-formats.md and keep only a 3-line summary with a reference link in SKILL.md.
Move the Sub-Agent Architecture section (agent definitions table, file ownership model, dispatch rules, conflict prevention) to agents/orchestrator.md and keep only a 5-line summary in SKILL.md.
Eliminate redundant restatements of rules — e.g., Revert-First appears in Complexity Control, Autonomy Leash, EXECUTE, and PIVOT sections. Define once, reference by name elsewhere.
Compress the REFLECT section by moving the 20-step numbered procedure to a reference file, keeping only the 3-phase structure and key gates in SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | This skill is extremely verbose at ~500+ lines. While the domain is complex, there is massive redundancy: the same rules (Mandatory Re-reads, Revert-First, 3-Strike, etc.) are restated multiple times across sections. Many sections explain concepts Claude already understands (what a state machine is, what git checkout does). The file lifecycle matrix, sub-agent architecture, and consolidated file management sections could be dramatically compressed. | 1 / 3 |
Actionability | The skill provides highly concrete, executable guidance: specific bash commands for bootstrapping, exact file paths and naming conventions, precise state transition triggers, detailed checklists with checkboxes, specific line count thresholds (>300 lines, >200 lines), and exact commit message formats. Every rule has a concrete action attached. | 3 / 3 |
Workflow Clarity | The state machine is exceptionally well-defined with explicit transitions, triggers, and validation checkpoints at every stage. The Post-Step Gate, Phase 1/2/3 REFLECT structure, Autonomy Leash with 2-attempt cap, and Gate-In mandatory reads provide thorough feedback loops. Destructive operations have explicit revert-first protocols and checkpoint requirements. | 3 / 3 |
Progressive Disclosure | The skill references many external files (references/file-formats.md, references/complexity-control.md, agents/orchestrator.md, etc.) which is good progressive disclosure architecture. However, the SKILL.md itself is a monolithic wall of text that inlines enormous amounts of detail that could live in those reference files. The sub-agent architecture section, consolidated file management, and detailed REFLECT phases could be split out, keeping only summaries in the main file. | 2 / 3 |
Total | 9 / 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.
39a478e
Table of Contents
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.