Content
81%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 high-quality, highly actionable body: executable checks for every PDF/UA requirement, real-world gotchas documented inline, and a fail-closed CI gate. Weaker spots are the undefined reading-order helper and placeholder install paths, plus a slightly padded intro paragraph.
Suggestions
Ship the pytest functions as a scripts/pdf_ua_checks.py bundle file (or provide the missing extract_text_with_structure_order implementation) so all code is copy-paste executable.
Provide a concrete auto-install.xml example or exact installer invocation in Step 2 to remove the '<install-dir>' guesswork.
Trim the opening WCAG-principles paragraph to one line pointing at the [WCAG 2.1 spec] reference, since Claude already knows the principles.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and expert-level: non-obvious gotchas (pikepdf 'bool(), not is True' wrapper semantics, jq -e exit-status behavior, nested /K tree walking) earn their tokens, and tables carry information efficiently. It is not score 5 because the opening paragraph reciting WCAG principles and some Step 8 template prose restate knowledge Claude already has and could be trimmed. | 4 / 5 |
Actionability | Mostly executable: verapdf install commands, the '--flavour ua1 --format json' CLI invocation, complete pytest functions, and a CI YAML gate with working jq logic. It is not score 5 because Step 8 calls an undefined 'extract_text_with_structure_order()' helper and Step 2 leaves '<install-dir>' and an unshown 'auto-install.xml' as placeholders — flagged as templates, but not copy-paste ready. | 4 / 5 |
Workflow Clarity | Ten clearly sequenced steps (pick checker → install → run → parse → tagged → title/lang → alt → reading order → map techniques → CI gate) where each verification step is itself an assertion with a descriptive failure message, exit codes are documented, failures cite WCAG techniques, and the Anti-patterns table supplies fixes — explicit validation checkpoints plus error-recovery guidance. It is not score 4 because there are no validation gaps: the CI gate demonstrably fails on violations via jq -e. | 5 / 5 |
Progressive Disclosure | Well-organized single-file skill with clear step sections, comparison tables, and well-signaled one-level-deep external references (markdown link definitions for WCAG, pikepdf, jq). It is not score 5 because no bundle structure exists: the reusable pytest functions (~90 lines of code) could plausibly live in a scripts/ file, keeping SKILL.md a leaner overview. | 4 / 5 |
Total | 17 / 20 Passed |