Content
85%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-engineered skill body: a decision router up front, guarded workflows with explicit validation checkpoints and dry-run gates, and a verified, one-level-deep reference structure. The main improvement opportunities are token-level: deduplicating the repeated git_safety.md pointers and showing the sanitize_history.sh invocation.
Suggestions
Show the scripts/sanitize_history.sh invocation (flags and expected output) the way check_env.py and init_session_start_hook.py are shown, so all three bundled scripts have copy-paste-ready usage.
Consolidate the four separate pointers to references/git_safety.md (entry router, principle 4, Workflow B step 2, Git safety section) into one authoritative pointer to save tokens.
Trim the rhetorical prose in Operating Principles (e.g., 'A hook is not a more professional version of a sentence') to pure directives.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, prescriptive, and assumes Claude's competence — no basic Git or package-manager explanations — with each section earning most of its tokens. Not 5 because of repetition (references/git_safety.md is pointed to from the entry router, principle 4, Workflow B, and the Git safety section) and some abstract principle prose ('A hook is not a more professional version of a sentence') that could be trimmed. | 4 / 5 |
Actionability | Concrete, verified commands are given for the bundled scripts (`uv run python scripts/check_env.py --repo <repo-root>` with documented exit-code semantics, and the init hook with --dry-run), and specific git commands appear where needed. Not 5 because sanitize_history.sh is described but never invoked with flags, and Workflow C stays at checklist altitude without examples — minor gaps against 'specific examples cover the common cases'. | 4 / 5 |
Workflow Clarity | Workflows A–D are clearly sequenced with explicit validation: A3 mandates capturing evidence, tracing to source, smallest repair, and re-running the failed check (a feedback loop); A4 requires verifying the observable result; the hook gate requires a --dry-run preview and user confirmation before install; destructive Git operations are gated by approval requirements. Matches the anchor 'Clear sequence with explicit validation steps; feedback loops for error recovery'. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview with an entry router, and all detail lives in one-level-deep, clearly signaled references: the four referenced files and three scripts all exist, the git_safety.md anchor links resolve to real headings, cross-links between reference files are sparse and signaled, and a Resources section indexes everything. Matches the score 5 anchor. | 5 / 5 |
Total | 18 / 20 Passed |