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 content is highly actionable and workflow-sequenced, with strong validation checkpoints and feedback loops around risky operations. Its weaknesses are rhetorical padding in the prose and the absence of any progressive disclosure: three full mode workflows plus a language reference table all live inline in one long file.
Suggestions
Split each mode's detailed procedure into one-level-deep reference files (e.g., references/audit.md, references/upgrade.md, references/cleanup.md, references/languages.md) and keep SKILL.md as a mode-selection overview with brief summaries, cutting the inline body to a fraction of its current length.
Trim the justification asides (e.g., "Skipping this step is the single biggest time-sink in practice", "failure beats a 20-minute hang", "these create fragile dependencies") down to the operative rule — the instruction itself already carries the decision.
Move the release-notes URL table and the formatting/dependency-check command tables into a single reference file, keeping only the most-used rows (the current language's row) inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with genuinely repo-specific operational content (grep patterns, per-language commands, CONNECTION_STRING ping one-liners), but recurring rationale asides pad it out ("Skipping this step is the single biggest time-sink in practice", "failure beats a 20-minute hang", "these create fragile dependencies"). It fits anchor 3 — mostly efficient but includes unnecessary explanation and could be tightened — rather than anchor 4 given how often the justification prose recurs. | 3 / 5 |
Actionability | Guidance is fully executable throughout: per-language command tables (npm outdated, mvn versions:display-dependency-updates, gofmt -l, dotnet list package --outdated), concrete grep and anti-pattern patterns (outputFromExampleFiles\(\[, catch.*\{\s*\}), runnable driver-ping one-liners, and copy-paste report templates. This matches anchor 5. | 5 / 5 |
Workflow Clarity | Each mode is a numbered, clearly sequenced procedure with explicit validation checkpoints and feedback loops: preflight DB ping ("If unreachable, stop"), pre-upgrade baseline smoke test, the >5×-baseline regression heuristic, failure-count branching (1–3 vs 4+ tests), and user-approval gates before any destructive cleanup action. This matches anchor 5. | 5 / 5 |
Progressive Disclosure | Section structure is clear (per-mode headers, steps, edge cases), but the entire three-mode skill (~430 lines) is inlined in a single SKILL.md with no bundle files — the per-mode workflows and the language reference table are natural candidates for one-level-deep reference files. This fits anchor 3 (content that should be separate is inline) rather than 4, where the split would be mostly done. | 3 / 5 |
Total | 16 / 20 Passed |