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 a dense, well-structured overview that assumes Claude's intelligence, points to real reference files one level deep, and puts explicit validation gates on its destructive operations. Its main weaknesses are the absence of worked command examples for common flows and a dead reference to a missing workflows/repair-agent-links.md file.
Suggestions
Fix the broken reference: either restore workflows/repair-agent-links.md to the bundle or inline/remove the pointer in the "Recovering a broken `.agents` entry" section.
Add one copy-paste-ready example invocation for the dominant flow, e.g., `.agents/skills/worktree/scripts/worktree create ISSUE-123 --base main`, so the common case does not require a help lookup first.
Break up the longest multi-clause sentences (session-guard and merged/rebase paragraphs) into shorter statements to reduce re-reading cost.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence throughout ("Every command's contract is its `--help`", exit codes 75/76 cited without explanation) and contains no padding of known concepts. It is not a 5 because several long multi-clause sentences (e.g., the session-guard paragraph and the merged/rebase policy restatements) could be tightened without losing content. | 4 / 5 |
Actionability | Concrete guidance dominates: the exact script invocation path, a fully executable cat command for resolving the main checkout, specific flag names, and precise exit codes. It is not a 5 because no worked example invocation (e.g., `worktree create <ISSUE-ID>`) appears in the body for the most common flows; details are delegated to `--help`. | 4 / 5 |
Workflow Clarity | The destructive workflows carry explicit validation gates: removal recovery requires proving identity, path containment, and ancestry with "Failed or unread proof stops recovery", and build-output pruning previews by default and deletes only under `--apply`. It is not a 5 because the everyday create/push sequence is deferred to `--help` and the recovery steps are prose-embedded rather than listed. | 4 / 5 |
Progressive Disclosure | The body is a genuine overview with clearly signaled, one-level-deep references to real bundle files ([references/hooks.md](references/hooks.md) and [references/session-guard.md](references/session-guard.md) both exist, and both reference only back to SKILL.md or `--help`). It is not a 5 because [workflows/repair-agent-links.md](workflows/repair-agent-links.md) is referenced but absent from the bundle, and most command detail lives in runtime `--help` output rather than navigable files. | 4 / 5 |
Total | 16 / 20 Passed |