Content
75%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 and clear validation-gated merge practices, and is well-structured for navigation. Its main weaknesses are duplicated merge-conflict guidance across sections and a long single-file form where troubleshooting/manual-ops content could be offloaded to reference files.
Suggestions
Consolidate the three repeated merge-conflict passages (Conflict Resolution, Troubleshooting, Best Practices) into one canonical section and cross-reference it, cutting roughly 30-40 lines.
Move Troubleshooting and Manual Worktree Operations into a separate reference file (e.g. references/troubleshooting.md) and link from SKILL.md to reduce inline token load.
Turn the Discard Build flow into an explicit validate->confirm->discard loop (list what will be deleted, confirm, then remove) so the destructive path matches the validation rigor of the merge flow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient and assumes Claude's intelligence (no over-explanation of what a worktree is), but merge-conflict guidance is repeated across 'Conflict Resolution', 'Troubleshooting > Merge Conflicts', and 'Best Practices > Before Merging', and the 'cd ../../apps/backend' return pattern is restated several times, so it could be tightened; not a 4 because the duplication is noticeable rather than minor. | 3 / 5 |
Actionability | Dense with copy-paste-ready, executable commands (e.g. 'python run.py --spec 001 --merge', 'git worktree add .worktrees/experiment -b experiment-branch') and concrete JSON metadata examples covering the common review/test/merge/discard/troubleshoot cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | Merge and discard workflows are numbered and the 'Before Merging' checklist provides explicit validation checkpoints (review, test, diff for conflicts) plus post-merge verification; not a 5 because the destructive 'Discard Build' relies on a confirmation prompt rather than a verify-then-confirm loop, and conflict-resolution feedback loops are described rather than structured as validate->fix->retry. | 4 / 5 |
Progressive Disclosure | No bundle files exist, so all content is inline, but it is well-organized with clear hierarchical section headers and a 'Related Skills' pointer to companion skills, making navigation easy; not a 5 because sizable sections (Troubleshooting, Manual Worktree Operations) are natural candidates for separate reference files and would benefit the context budget if split out. | 4 / 5 |
Total | 16 / 20 Passed |