Content
70%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 skill body is a strong executable workflow: every step has concrete commands, validation checkpoints, and STOP gates, and the error-handling and rollback coverage is exemplary. Its weaknesses are repetition — four separate summary sections restate the same phase list — and complete absence of progressive disclosure, with 470 lines of monolithic content where secondary tables and integration details belong in reference files.
Suggestions
Split secondary material into one-level-deep reference files (e.g., references/error-handling.md, references/integration.md) and keep SKILL.md to the phase workflow with well-signaled links, reducing the main file to roughly 200-250 lines.
Collapse "Red Flags", "Safety Measures", "Quick Reference", and "The Bottom Line" into a single compact checklist — they restate the phase steps nearly verbatim and cost tokens without adding guidance.
Fix the pseudo-executable fragments: wire the ${USER_*} placeholders in the LESSONS.md heredoc to captured variables, note that ${codex_status} must be substituted into the displayed markdown, and replace the sed -i '' portability fallback with a single portable invocation.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly concrete instruction with no explanations of concepts Claude already knows, but it carries several padded, redundant sections — "Red Flags", "Safety Measures", "Quick Reference", and "The Bottom Line" largely restate the phase steps, and the shouty "MANDATORY COMPLIANCE" block adds emphasis rather than information. This fits anchor 3 (could be tightened) better than anchor 4 given the volume of repetition. | 3 / 5 |
Actionability | Every phase ships concrete, mostly copy-paste-ready bash with real error handling (grep with || echo fallbacks, sed -i variant fallback, find -mmin validation check). Minor gaps keep it at anchor 4 rather than 5: ${codex_status} appears unexpanded inside a markdown block, the ${USER_*} placeholders in the heredoc are never wired to actual variables, and the sed -i '' portability dance is under-explained. | 4 / 5 |
Workflow Clarity | Six explicitly numbered phases with STOP checkpoints, a ready-state gate before any destructive action, audit-completion verification (find for the validation file), and feedback loops on failure ("Resolve issues and run /octo:ship again"), plus an error-handling matrix. This matches anchor 5 (clear sequence, explicit validation, feedback loops) — destructive/batch operations are fully gated with validation. | 5 / 5 |
Progressive Disclosure | The file is well-sectioned with clear headers, but it is a fully monolithic 470-line SKILL.md with no references/, scripts/, or assets/ bundle; everything including the error-handling, safety, and integration tables is inlined. That fits anchor 3 (structure present, content that should be separate is inline) rather than anchor 4, since secondary material clearly belongs in one-level-deep reference files. | 3 / 5 |
Total | 15 / 20 Passed |