Content
73%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 strong, project-specific operational guide: concrete commands, a clearly sequenced workflow with real validation checkpoints and user-confirmation gates around the destructive apply step, and proper deferral of branch-model detail to a real reference file. Its weaknesses are density-driven: the Best Practices section and the add-on flag paragraphs repeat caveats and could be tightened or split into reference files, and the PR-creation step could be spelled out as concretely as the others.
Suggestions
Tighten the --with-aspens and --with-gitnexus paragraphs: they both end with the same best-effort/'only reliable success signal' caveat and could share one sentence covering both flags, cutting ~10 lines from the propose step.
Move the .worktrail/policy.yaml and gitleaks bullets (and the add-on flag rationale) from Best Practices into a references/ file (e.g. references/scaffold-details.md) so SKILL.md stays a lean overview, matching how branch-model-decision.md is already handled.
Make Step 3 as concrete as Steps 2 and 4: give the actual git add/commit/gh pr create command sequence (with a suggested commit message and PR-body skeleton) instead of describing the standard workflow, and show a minimal required_status_checks hand-edit example for the ci_jobs_discovered case in Step 2.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Almost all content is project-specific knowledge Claude cannot be assumed to have (doctrine file paths, CLI flag semantics, GitHub App credentials), so it avoids explaining known concepts — but the body is noticeably long and could be tightened: 'the only reliable success signal available' appears nearly verbatim in both the --with-aspens and --with-gitnexus bullets, 'don't default it on' is repeated in the same paragraph pair, and several multi-line parentheticals restate their justification twice. This fits anchor 3 ('mostly efficient but includes some unnecessary explanation or could be tightened') better than anchor 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | Two copy-paste-ready bash blocks ('git worktree add ../<repo>-worktrees/repo-standards -b repo-standards <current-default-branch>' / 'worktrail-repo-init propose --repo . --branch-model 2 --json'; 'git checkout <old-default-branch> && git pull' / 'worktrail-repo-init apply --repo . --json') plus concrete JSON fields to review ('written/skipped/warnings', 'ci_jobs_discovered', 'branches/default_branch/.../rulesets'). Minor gaps keep it at 4 rather than 5: Step 3's 'git add, commit, push, gh pr create' is gestured rather than given as a command, and the hand-edit of required_status_checks in Step 2 is described but never shown with an example diff. | 4 / 5 |
Workflow Clarity | A clear four-step sequence (decide branch model → worktree + propose → commit/push/PR → apply) with explicit validation checkpoints: review the propose JSON's written/skipped/warnings and ci_jobs_discovered before committing, explicit user confirmation before the destructive apply, 'Any FAILED entry means apply exited non-zero — investigate and re-run', and a manual-follow-up checklist. This matches anchor 5 (validation steps, feedback loops, checklist) despite the destructive operations — the guideline capping destructive skills at 3 applies only when validation is missing, and it is not. | 5 / 5 |
Progressive Disclosure | Good structure: Overview → When to Use → Instructions (4 steps) → Examples → Best Practices, with a well-signaled one-level-deep reference ('Read references/branch-model-decision.md before choosing --branch-model') that exists in the bundle and contains exactly the deferred detail, with the body keeping only 'the short version'. Not a 5 because the body still inlines ~240 lines of detail — the long --with-aspens/--with-gitnexus paragraphs and the .worktrail/policy.yaml and gitleaks bullets in Best Practices are candidates for a second reference file — which fits anchor 4's 'most content is appropriately placed; minor organization gaps'. | 4 / 5 |
Total | 16 / 20 Passed |