Content
52%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's process is well-sequenced and mostly actionable, with concrete commands, expected output formats, and clear status-routing tables. It is let down by heavy redundancy (roughly a third of the file restates earlier content) and by a progressive-disclosure failure: the workflow's key step invokes ./scripts/octo-state.sh, which is not present in the bundle, and no detail content is split into reference files.
Suggestions
Ship scripts/octo-state.sh in the bundle (or replace the reference with the actual state-reading commands) so the central Phase 2 step is executable as delivered.
Cut the duplication: delete Example 1 (verbatim repeat of Phase 1's output), fold the Best Practices/Red Flags/Bottom Line sections into the phases they restate, and drop the Quick Reference table that repeats When to Use.
Move the three Example Outputs and the phase-specific routing tables into a references/ file (e.g., references/examples.md), keeping SKILL.md as a concise overview with one-level-deep, clearly signaled references.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~500-line body has substantial duplication: 'Example 1: Project Not Initialized' repeats Phase 1's not-initialized output verbatim; the Best Practices 'Good/Poor' code pairs re-show commands already given in Phases 1-2; the Red Flags table, Quick Reference table, and 'The Bottom Line' all restate the When to Use and routing content a third and fourth time. This fits 'Noticeably verbose; several unnecessary explanations or padded sections'; not score 3 because the duplication is pervasive rather than incidental, and not score 1 because there is no educational padding explaining concepts Claude already knows. | 2 / 5 |
Actionability | The body gives concrete, executable commands (`if [[ ! -d ".octo" ]]`, `./scripts/octo-state.sh read_state`, `git log --oneline --since="7 days ago"`), an expected state-output format, and complete routing tables. This matches 'Mostly executable guidance; concrete code or commands with minor gaps'; the gaps are that blocker extraction is never operationalized (the read_state output format shown has no blockers field, yet the dashboard template expects `{blockers or "None"}`) and `.octo/ISSUES.md`, `phase{N}/` directories are referenced without read steps. | 4 / 5 |
Workflow Clarity | The phases are clearly sequenced (check initialization → read state → read roadmap → display dashboard → route → optional activity summary) with an explicit 'Stop here - do not proceed to Phase 2' checkpoint and exit-1 handling for missing .octo/. This matches 'Clear sequence with most checkpoints present; minor validation gaps'; not score 5 because there is no instruction for handling malformed or unexpected read_state output, and the blockers that drive the 'blocked' routing are never given a source. The read-only nature of the skill means the destructive/batch validation cap does not apply. | 4 / 5 |
Progressive Disclosure | The bundle contains no references/, scripts/, or assets/ directories, yet the body's central step depends on `./scripts/octo-state.sh read_state` — a referenced path that does not exist in the skill bundle, so the instruction is unrunnable as shipped. The remaining ~500 lines are entirely inline monolith (examples, routing tables, and the activity-summary section all in SKILL.md), matching 'Minimal structure; content that clearly belongs in separate files is inlined; or references are buried'. Not score 1 because the file itself is well sectioned with headers and tables; not score 3 because the broken script reference plus the monolithic inlining are structural problems, not just organization gaps. | 2 / 5 |
Total | 12 / 20 Passed |