Content
77%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is an exceptionally actionable, well-sequenced instruction set with complete output templates, explicit failure handling, and clear verdict logic — near the top of the actionability and workflow-clarity scales. Its weaknesses are the ~600-line monolithic layout that would benefit from per-mode reference files, and repetitive passages (the NOT ASSESSED ranking rules) that inflate token cost without adding guidance.
Suggestions
Move each mode's full specification (Phase 2A/2B/2C/2D) into references/ files (e.g. references/static-mode.md, references/spec-mode.md) and keep SKILL.md as the argument-parsing hub with one-line pointers, so a single-mode invocation loads only what it needs.
State the NOT ASSESSED ranking (FAIL < PARTIAL < NOT ASSESSED < PASS) once in a shared section and reference it from the three places that currently re-derive it.
Trim the justificatory blockquotes (e.g. the gate-verdict list rationale in Check 3) to a single sentence each — the design reason is useful, the full argument is not needed at run time.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly tight imperative instructions, but the NOT ASSESSED ranking is re-explained in three separate places (static output rules, spec assertion rules, category verdict) and several justificatory asides ("A linter that produces false failures on legitimate patterns stops being trusted") could be trimmed — mostly efficient but could be tightened. | 3 / 5 |
Actionability | Fully executable for an instruction-only skill: exact commands ("bash .claude/scripts/agent-check.sh --skill [name]"), complete copy-paste output templates for every mode, exact error messages to print ("Spec file missing at [path]. Run /skill-test audit..."), and explicit verdict aggregation orderings — specific examples cover the common cases. | 5 / 5 |
Workflow Clarity | Sequencing is explicit (Phase 1 parse arguments → mode-specific phases → Phase 3 handoff) with numbered steps inside each mode, and failure paths are handled everywhere (missing catalog, missing spec, unparsable frontmatter, script cannot run → "not run (<reason>)"), with verdict-to-Recommended-fix feedback loops throughout. | 5 / 5 |
Progressive Disclosure | The single SKILL.md inlines ~600 lines including four substantial per-mode specifications that load into context on every invocation even when only one mode runs; internal structure is well-headed, but this content plainly belongs in one-level-deep references/ files, matching the 'content that should be separate is inline' anchor. | 3 / 5 |
Total | 16 / 20 Passed |