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 instruction skill: a mode router up front, four sequenced workflows with explicit validation and approval gates, concrete bundled-script commands, and a clean overview-to-reference split where every referenced bundle file exists. The residual cost is density of abstract principle prose that could be slightly tightened, and repair steps that are (justifiably) left repo-dependent.
Suggestions
Trim the philosophical framing sentences in Operating principles (e.g. "A hook is not a more professional version of a sentence") to their operational rule, cutting repetition with the Git safety section.
In A3, add one concrete worked example of tracing a failed requirement to its declaring source (manifest → lockfile → command) so the repair loop has a copy-paste-ready illustration alongside the script commands.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, prescriptive rule-content with essentially no explanation of concepts Claude already knows, and commands appear without preamble. Minor instances of abstract philosophical prose could be trimmed ("A hook is not a more professional version of a sentence", "not as a special interface for people with a particular job title"), and Operating principle 4 overlaps the Git safety section. Fits the 4 anchor (efficient, minor trimmable over-explanation); not 3 because there is no genuinely padded explanation, not 5 because the value-statement prose is not maximally lean. | 4 / 5 |
Actionability | Concrete, copy-paste-ready commands are given where possible ("uv run python scripts/check_env.py --repo <repo-root> --json" with exit-code semantics, the init hook command with --dry-run/--remove, "git pull --ff-only"), plus a specific file read-order, expected results, and a report format. Mostly executable guidance with minor gaps: A3 repair and A4 smoke-test derivation are necessarily repo-dependent and left to the agent, which is justified flexibility but keeps it below the fully-executable 5 anchor; clearly above 3 since real commands and specifics dominate over pseudocode or hints. | 4 / 5 |
Workflow Clarity | Workflows A-D are clearly sequenced with explicit validation checkpoints and feedback loops: "Re-run the failed check before moving on", "Verify the observable result, not merely a zero exit code", "Before reporting synchronized, independently verify the target branch, clean status, and local/remote commit equality", the hook gate with --dry-run preview before install, and exit-code-driven handling for the env check and network failures. Destructive Git operations are gated by explicit approval steps, matching the 5 anchor; not 4 because checkpoints are explicit and repeated rather than having minor gaps. | 5 / 5 |
Progressive Disclosure | The body is an overview/router with well-signaled, one-level-deep references that all exist in the bundle (git_safety.md, startup_automation.md, onboarding_template.md, pii_guard.md, codex-hook-trust.md, plus three scripts), each linked inline with a purpose signal and summarized in a Resources section with one-line descriptions. Content is appropriately split — the git-safety rules are distilled in the body with detail pushed to the reference — and the only cross-link between references (startup_automation → git_safety anchor) stays shallow. Matches the 5 anchor; not 4 because navigation and placement have no meaningful gaps. | 5 / 5 |
Total | 18 / 20 Passed |