Content
48%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 domain-specific core (extraction rules, CSV schemas, table-first detection order, dedup/spot-check quality checks) is solid and specific, but it is wrapped in ~60 lines of generic filler, a broken primary script reference, and contradictory duplicate validation instructions. The skill reads as a good extraction spec diluted by template boilerplate.
Suggestions
Delete the generic boilerplate sections ('Required Inputs', 'Recommended Workflow', 'Output Contract', 'Validation and Safety Rules', 'Failure Handling', 'Deterministic Output Rules', 'Completion Checklist', 'When Not to Use') — they restate what Claude already knows and consume roughly a third of the body.
Fix the primary execution path: 'd:\SKILL\project\pdf-extract\scripts\extract_pdf.py' is not in the bundle; either ship the script under scripts/ with a relative path or replace the command with a concrete pdfplumber/OCR snippet, since pdfplumber is already a declared dependency with no example code.
Reconcile the contradictory validation guidance — 'Validation Shortcut' says to run scripts/validate_skill.py while 'Quick Validation' states 'No local script validation step is required for this skill'. Keep one validation step and turn the item spot check into a fix-and-retry loop (re-extract mismatched rows, then re-verify).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Roughly a third of the body is generic boilerplate Claude already knows — 'Required Inputs', 'Recommended Workflow', 'Output Contract', 'Validation and Safety Rules', 'Failure Handling', 'Deterministic Output Rules', 'Completion Checklist' (e.g., 'Validate required inputs before execution and stop early when mandatory fields or files are missing', 'Return a structured deliverable that is directly usable without reformatting'). Several padded, skill-agnostic sections make this noticeably verbose rather than 'mostly efficient', so it sits at anchor 2 rather than 3. | 2 / 5 |
Actionability | Genuinely concrete parts exist (exact CSV schemas, field mapping rules like 'catalog_number = version/release (if explicitly stated)', dedup and spot-check rules), but the primary execution step is broken: 'python d:\SKILL\project\pdf-extract\scripts\extract_pdf.py -i input.pdf -o out.md' references a script absent from the bundle via a hardcoded absolute Windows path, and no executable pdfplumber/OCR code is provided despite listing them as dependencies. This is concrete-but-incomplete guidance with missing key details, matching anchor 3 rather than 4's 'minor gaps'. | 3 / 5 |
Workflow Clarity | The operational sequence is clear: convert PDF to Markdown → table-first region detection → field extraction per rules → write three exact-schema CSVs → deduplicate → 'Perform a spot check of at least three items against the PDF source'. An explicit validation checkpoint exists, so the batch-operation cap at 3 does not apply. It falls short of 5 because there is no fix-and-retry loop after the spot check, and the two validation sections contradict each other ('Run this minimal command first... python scripts/validate_skill.py --help' vs 'No local script validation step is required for this skill'). | 4 / 5 |
Progressive Disclosure | Section headers are present and the one real bundle file (scripts/validate_skill.py) is clearly signaled and exists, but the other referenced script (extract_pdf.py) does not exist in the bundle and is reached via a buried absolute path, failing navigation. The trivial stub script plus the contradictory duplicate validation guidance ('Validation Shortcut' vs 'Quick Validation') leaves the structure redundant and harder to navigate than the 'references mostly clear' bar of anchor 4. | 3 / 5 |
Total | 12 / 20 Passed |