Content
81%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.
A well-crafted skill body: highly actionable commands with sample outputs, an explicitly validated workflow with dependency checking and completion discipline, and a sound file structure with real, well-signaled references. The main gains are literal copy-paste readiness (actual script paths), trimming duplicated notes, and offloading one or two long sections to reference files.
Suggestions
Write the actual script invocation paths (e.g., scripts/jj-todo-create ...) in the Quick Start and workflow examples so commands are copy-paste executable, instead of the 'full paths not written' placeholder.
Remove duplicated provenance notes (the jj-show-desc 'BEWARE'/'REMINDER' pair) and the 'standby was previously called broken' version-history aside to save tokens.
Move the full 'Writing Good TODO Descriptions' example and/or the 'AI-Assisted TODO Workflow' section into a references/ file, keeping SKILL.md as a leaner overview with pointers.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean and command/table-driven, teaching only JJ-workflow-specific knowledge Claude would not already have. Minor trimmable instances keep it below the 5 anchor: the jj-show-desc provenance is flagged twice ('BEWARE: Script from the working-with-jj skill' and 'REMINDER: jj-show-desc is from the working-with-jj skill'), the 'NOTE: In previous versions of this Skill, standby was called broken' version-history aside, and some introductory prose about the core idea. Well above the 3 anchor — no padding or explanation of concepts Claude already knows. | 4 / 5 |
Actionability | Concrete, executable guidance throughout: specific script invocations with expected output, jj commands, a fully worked example TODO description, and a script table. Falls short of the 5 anchor ('copy-paste ready') because the Quick Start itself notes 'full paths to helper scripts not written' and examples use placeholders like <T1-id>, so commands are not literally copy-paste runnable as-is. | 4 / 5 |
Workflow Clarity | The Quick Start lays out a numbered plan→work→verify→transition cycle, and validation is explicit and layered: 'Verify ALL acceptance criteria met' (make test), 'ONLY if all checks pass' before --mark-as done, jj-todo-next's automatic dependency checking, the ✅/❌ completion-discipline checklist, dependency inspection commands, and a dedicated 'When to Stop and Report' error-recovery section. This matches the 5 anchor's explicit validation steps, feedback loops, and checklists. | 5 / 5 |
Progressive Disclosure | Good structure with clearly signaled, verified one-level-deep references: 'references/parallel-agents.md' is referenced in context, listed in a References section, and exists as a real file; the script table matches the actual contents of scripts/. Not a 5 because the ~420-line body inlines some material that could live in references (the full example TODO description, the AI-Assisted TODO Workflow section), making the overview slightly heavier than the exemplary quick-start-plus-pointers shape. | 4 / 5 |
Total | 17 / 20 Passed |