Content
62%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body has excellent workflow sequencing with explicit validation and feedback loops, and its commands are concrete. Its main weaknesses are verbosity from repeating the same rules across sections and limited use of progressive disclosure, with much detail kept inline rather than split into reference files.
Suggestions
Consolidate the PR-scoped-vs-sweep and no-guessing rules into single authoritative sections and reference them instead of restating them in Modes, Phase 0.5, Phase 2, and Phase 3.
Move the detailed Conventions (aliases, links, shortcodes, fragments, external URLs, special cases) into a separate reference.md linked from the body, leaving SKILL.md as a lean overview of the required procedure and phases.
Add concrete, copy-paste-ready examples of the actual List 1 and List 2 link edits (before/after diff snippets) so the core editing actions are executable rather than described in prose.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is thorough and mostly domain-specific policy Claude would not know, but key rules are restated multiple times (the PR-scoped-vs-sweep distinction recurs in the procedure, Modes, Phase 0.5, Phase 2 and Phase 3; "no guessing" repeats in four places), so it could be tightened. It is not level 1 because the content is genuine project policy rather than generic concepts Claude already knows. | 2 / 3 |
Actionability | It provides concrete executable commands (git diff --name-only main...HEAD, merge-base then diff, docker buildx bake validate) and a real scope-pr-files.sh helper, but the core link-edit steps are described as prose ("Replace old source paths... preserve each file's link pattern") rather than given as copy-paste-ready commands. It is not level 3 because the central editing actions are not fully executable code. | 2 / 3 |
Workflow Clarity | The multi-step process is explicitly sequenced (Phases 0→0.5→1→2→3 plus a mandatory "Run in order" list) with a validation checkpoint (docker buildx bake validate), a re-sweep feedback loop ("re-print or re-scan for List 2 until empty or deferred"), and a Definition-of-done checklist, matching the anchor for clear sequence with explicit validation and feedback loops. | 3 / 3 |
Progressive Disclosure | There is one real bundle file (scripts/scope-pr-files.sh) referenced correctly and a convention for an optional reference.md, with no deeply nested references; however the detailed Conventions and Phase sections remain inline in a ~370-line SKILL.md rather than being split into well-signaled one-level-deep reference files. It is not level 1 because sections are headed and organized, and not level 3 because content that could be separate is left inline. | 2 / 3 |
Total | 9 / 12 Passed |