Content
86%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 an exemplar of lean, high-signal instruction writing: terse governance rules, concrete pnpm commands, and clear section structure. The only weaknesses are minor — a placeholder argument, no sample command output, and no guidance on recovering from failed validation.
Suggestions
Give one concrete example invocation of `pnpm change:scope` / `pnpm docs:affected` (e.g., with a real base ref like `origin/main`) and a line of expected output so the impact-inspection step is fully copy-paste ready.
Add a brief feedback loop to the Validation section: what to do when `pnpm docs:check`, `pnpm lint`, or `pnpm test:lint` fails (fix and re-run before proceeding).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~30-line body is dense imperative rules with zero padding ("Keep one home per fact.", "Never hand-edit `docs/dev/README.md` …"), explains nothing Claude already knows, and assumes competence throughout — every token earns its place. It clearly fits the lean/efficient anchor, not the minor-over-explanation anchor below. | 5 / 5 |
Actionability | Concrete, runnable commands and paths are given (`pnpm change:scope --base <verified-ref>`, `pnpm docs:affected --base <verified-ref>`, `pnpm docs:check`, `pnpm lint`, `pnpm test:lint`, `git diff --check`, `translate-docs`), which is mostly executable guidance. It falls short of fully copy-paste ready because commands use a `<verified-ref>` placeholder with no example value and there is no sample output for the impact-inspection commands. | 4 / 5 |
Workflow Clarity | A clear sequence is established ("Require an explicit scope. Read the applicable `AGENTS.md`, then the owning source or module README before judging prose") with checkpoints ("A source-prefix match is a mandatory review prompt, not proof"; a dedicated Validation section with commands). It is not a 5 because there is no feedback loop describing what to do when `pnpm docs:check` or lint fails. | 4 / 5 |
Progressive Disclosure | The skill is under 50 lines with no bundle files and no need for external references; it has well-organized sections (Place the fact / Inspect code impact / Generated and paired docs / Validation) and its few links (pairing contract, translation rules, terminology) are clearly labeled and one level deep — matching the simple-skill exception for a top score. | 5 / 5 |
Total | 18 / 20 Passed |