Content
71%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 highly actionable with executable commands, checklists, and concrete examples, and its workflows are well-sequenced with self-check validation. Its weaknesses are redundant coverage of the bd-vs-TodoWrite decision, a body length that retains detail belonging in reference files, and a progressive-disclosure architecture whose six referenced files are missing from the bundle.
Suggestions
Consolidate the three overlapping bd-vs-TodoWrite decision sections ("When to Use", "Test Yourself", and "Integration with TodoWrite") into one section and defer detail to references/BOUNDARIES.md to cut significant tokens.
Ship the six referenced references/*.md files in the skill bundle (BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md, DEPENDENCIES.md, ISSUE_CREATION.md, STATIC_DATA.md) or remove the links, since every reference currently points to a non-existent file.
De-duplicate the database auto-discovery rules stated in both "Session Start Protocol" and "Database Selection", and re-order the Issue Lifecycle so Planning precedes Execution.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The bd-vs-TodoWrite decision is covered three separate times ("When to Use bd vs TodoWrite", "Test Yourself: bd or TodoWrite?", and "Integration with TodoWrite"), and the database auto-discovery rules ("Uses .beads/*.db in current project if exists / Falls back to ~/.beads/default.db") are stated twice in nearly identical wording. Mostly efficient and free of explanations of concepts Claude already knows, but clearly could be tightened, matching anchor 3 rather than 2 since the padding is redundancy rather than patronizing explanation. | 3 / 5 |
Actionability | Commands are copy-paste ready and cover the common cases: `bd create "Add OAuth" -p 0 -t feature`, `bd update issue-123 --status in_progress`, `bd dep add auth-epic auth-setup --type parent-child`, `bd close issue-1 issue-2 issue-3 --reason "..."`. Concrete good/bad note examples, copy-able checklists, report formats, and troubleshooting workarounds (e.g., `bd list | grep -i "search term"`) match anchor 5's fully executable, common-case-covering guidance. | 5 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced with checklists (Session Start Checklist, Progress Checkpoint, Issue Creation Checklist) and self-check validation ("Test yourself: If compaction happened right now, could future-me resume from these notes?"), plus conditional recovery paths ("If bd ready returns empty but issues exist: bd blocked --json" and a Troubleshooting section). Minor gaps keep it at anchor 4 rather than 5: the Issue Lifecycle numbers Planning (3) after Execution (2), and bulk operations like `bd close issue-1 issue-2 issue-3` have no verification step before closing. | 4 / 5 |
Progressive Disclosure | References are clearly signaled and one level deep with a useful "Read When" table, but the six referenced files (references/BOUNDARIES.md, CLI_REFERENCE.md, WORKFLOWS.md, DEPENDENCIES.md, ISSUE_CREATION.md, STATIC_DATA.md) do not exist in the skill's bundle, so the disclosure structure does not actually resolve and navigation breaks. Additionally, the ~640-line body retains substantial material (TodoWrite integration patterns, full pattern walkthroughs, decision criteria repeated three times) that the reference files are meant to hold, fitting anchor 3 ("content that should be separate is inline") despite the good signaling. | 3 / 5 |
Total | 15 / 20 Passed |