Content
82%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-built skill body: highly actionable with concrete commands and a complete output contract, and a clearly sequenced workflow with sensible guardrails via anti-patterns. The main improvements are trimming the duplicated example between Steps 2 and 4 and adding a lightweight self-validation step before emitting the brief.
Suggestions
De-duplicate the Step 2 YAML example against the Step 4 JSON schema — show the per-entry shape once (in the final JSON) and reference it from Step 2, saving ~15 lines.
Add a brief validation checkpoint before emitting the brief, e.g. "confirm each section heading exists verbatim in the page and line ranges fall inside the section" — cheap to run and prevents hallucinated sections.
State what to do when scope_pages[] is empty or a listed page is missing (skip vs. report via localizer_concern) so the batch loop has an explicit failure path.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence (no concept explanations, useful budget notes like "Pages are typically 3-10 KB"), but the Step 2 YAML example and the Step 4 JSON example duplicate the same section-edit fields (page, section, line_range, diff_symbol, edit_kind, rationale), and the Output contract section restates Step 4's schema. This is the anchor-4 case: efficient with minor instances that could be trimmed, not the every-token-earns-its-place level of a 5. | 4 / 5 |
Actionability | Fully concrete guidance: exact inputs (`gh pr diff $PR`, `.apm/docs-index.yml`), a precise line-range convention ("lines 120-145 not the whole page"), a complete copy-paste-ready JSON output schema, and concrete verify commands ("apm install --help", "grep -n no-cache src/apm_cli/commands/install.py"). Nothing remains abstract. | 5 / 5 |
Workflow Clarity | Steps 1-4 are clearly sequenced with well-defined outputs at each stage, and validation is addressed via the verify_claims[] handoff and the Anti-patterns checklist. It falls short of a 5 because there is no self-validation checkpoint (e.g., confirm each section_to_edit exists in the page or that line ranges match the read content) before emitting the final brief — verification is delegated downstream rather than performed. | 4 / 5 |
Progressive Disclosure | No bundle files exist and the body is self-contained at ~113 lines with clean sections (When to invoke, Inputs, Steps 1-4, Output contract, Anti-patterns) that are easy to navigate. The inline output schema is core contract content and appropriately placed; the gap toward a 5 is that the JSON schema and cross-page example together could live in a small reference file if the skill grows, and there is no reference layer at all to signal. | 4 / 5 |
Total | 17 / 20 Passed |