Content
71%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, operational body with a genuinely useful decision table, fallback matrix, and token preflight, held back by bundle-level defects: the two files it defers detail to (`reference.md`, `setup.sh`) are absent, and the path-independent invocation snippets are subtly broken as written. Batch workflows also lack a post-run verification checkpoint.
Suggestions
Ship the missing `reference.md` (e.g. under `references/`) with the deferred content — backends, REST endpoints, disk/uninstall info — since line 20's pointer currently dead-ends, or inline the essential parts and drop the reference.
Add or fix `setup.sh`: the Setup section's core command (`bash setup.sh`) has no corresponding file in the bundle, so the fresh-device bootstrap flow cannot run as written.
Add an explicit post-parse verification step for batch runs (e.g., check each output .md exists and is non-empty, retry failures on the other parser path, then report counts) — batch workflows currently end without a validation checkpoint.
Replace the broken path-independent snippets (`$(dirname "$0")`, `cd "$(dirname SKILL.md)"`) with a single correct form, e.g. `bash "$(dirname <path-to>/SKILL.md)/scripts/check.sh"` or a plain 'cd into this skill's directory, then run bash scripts/check.sh'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense and operational almost everywhere — decision table, fallback matrix, preflight, and copy-paste commands with no padding and no explanation of concepts Claude already knows. Falls short of the 5 anchor due to minor trims available: repeated path-independence caveats ("don't hardcode a home path — the skill may live under ~/.claude/skills/..." plus the parenthetical "or: cd into this skill dir"), and the tail block on setup.sh's whitespace re-serialization of ~/.claude.json spends tokens on an ancillary edge case. Well above 3's 'some unnecessary explanation'. | 4 / 5 |
Actionability | Mostly copy-paste ready: `pdf2md paper.pdf out/ -m ocr`, `bash scripts/batch-local.sh ~/papers ~/papers_md`, exact token names, URLs, and concrete limits (≤20p/10MB) plus natural-language MCP prompts. Not the 5 anchor because the two path-independent invocation snippets are broken as written — `bash "$(dirname "$0")/scripts/check.sh"` resolves to the caller's cwd, not the skill dir, and `cd "$(dirname SKILL.md)"` is a no-op (dirname of a bare filename is '.') — so the working alternative has to be inferred from the comment, and the Setup section's `bash setup.sh` has no corresponding file in the bundle. | 4 / 5 |
Workflow Clarity | Clear sequencing (decision table → fallback → preflight → usage → setup) with a real validation checkpoint (run check.sh before token-gated tools, "do not silently fail") and an error-recovery loop ("A parse fails or returns garbage on one path → retry the same file on the other path before giving up; report which path"). Falls short of 5 because batch workflows (batch-local.sh, cloud batch prompts) end with no post-run verification step — nothing says to check outputs exist/are non-empty before reporting success — a minor validation gap rather than the 3-cap, since preflight validation and failure-recovery loops are present. | 4 / 5 |
Progressive Disclosure | The in-body structure is good and the reference is clearly signaled ("Deep detail lives in `reference.md`; read it when you need backends, REST endpoints, or disk/uninstall info"), but scoring against the actual bundle: `reference.md` does not exist anywhere in the skill, and `setup.sh` — the core command of the Setup section — is also missing, while only `scripts/batch-local.sh` and `scripts/check.sh` resolve. The one-level-deep reference design that justifies keeping SKILL.md lean dead-ends, so the split is half-implemented — more than the 4 anchor's 'minor organization gaps' and worse navigation than the 5 anchor requires. | 3 / 5 |
Total | 15 / 20 Passed |