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-structured, highly actionable skill body: complete executable code for every step, an explicit workflow with validation and a demonstrated error-recovery feedback loop, and clean progressive disclosure into two real, well-signaled reference files. The two minor weaknesses are the duplicated overview/steps framing (and repeated dpi guidance) and the undefined `pixel_diff_img` helper in Step 6 that keeps that code block from being copy-paste ready.
Suggestions
Resolve the pixel_diff / pixel_diff_img mismatch: define the image-object variant (or make the Step 3 pixel_diff accept either paths or PIL images) so the Step 6 update-baseline block is copy-paste ready.
De-duplicate guidance to save tokens: the 7-step 'How to use' list restates Steps 1–6, and the dpi=150 vs 300 advice appears three times — condense the overview to a short index or state the dpi rule once.
Trim or merge the trailing References list, which repeats the two inline reference links and could fold the Poppler/pdf2image/pixelmatch pointers into the relevant steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is code-first and assumes competence (no explanation of what PDFs are or how the libraries work), but the 7-item 'How to use' list substantially restates the Step 1–6 sections that follow, and the dpi=150-vs-300 guidance appears three times (How to use, Step 2, and the anti-patterns table). These are minor instances of over-explanation and duplication that could be trimmed, matching the efficient-with-minor-trimmings anchor rather than the every-token-earns-its-place anchor at 5. | 4 / 5 |
Actionability | Nearly everything is executable: OS-specific install commands, a complete pdf2image convert snippet, pdftocairo CLI lines, a full pixel_diff implementation, a runnable pytest example, page-range code, and the UPDATE_PDF_BASELINES flow. The gap: Step 6 calls `pixel_diff_img(page_img, Image.open(baseline))`, a helper never defined anywhere (Step 3's pixel_diff takes file paths), so that block is not copy-paste ready — 'mostly executable with minor gaps' rather than fully executable. | 4 / 5 |
Workflow Clarity | The sequence is explicit (numbered overview plus detailed Steps 1–6), validation is built in (assert diff_ratio < 0.005 with an informative per-page failure message), the semi-destructive baseline overwrite is gated behind an opt-in env var, and the worked example demonstrates a full feedback loop: fail → run `pdfinfo -list-embedded-fonts` to distinguish a real layout change from a font-substitution artifact → fix → re-run until under threshold → refresh baseline. This matches the explicit-validation-with-feedback-loops anchor; the destructive/batch cap does not apply because validation is present. | 5 / 5 |
Progressive Disclosure | Scored against the actual bundle: both referenced files (references/cross-engine-regression.md, references/deterministic-rendering.md) exist and hold exactly the content promised. Cross-engine engine setup, metadata stripping, and font-substitution detection are correctly kept out of SKILL.md in one-level-deep references, each clearly signaled at point of use ("the per-engine generation setup, agreement tests, and version pinning live in [references/cross-engine-regression.md]") and again in a References section, with no inline content that belongs in a separate file. Matches the clear-overview, well-signaled, one-level-deep anchor. | 5 / 5 |
Total | 18 / 20 Passed |