Content
67%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, mostly executable skill body with a clear scene-based workflow, good error-recovery routing, and sensible guardrails. Its two real weaknesses are meta-descriptive padding (SSL-primitive and resource-scope tables) that inflates token cost without aiding execution, and references to bundle files that are not present in the skill's directory, which undermines the progressive-disclosure design.
Suggestions
Delete the meta-descriptive sections that don't aid execution — the 'Actions | SSL primitive' table, 'Resource scope' table, and 'Control-flow features' — and merge 'Intent signature' into 'When to use' to remove duplication and cut token cost.
Ship the referenced bundle files (resources/execution-protocol.md, resources/troubleshooting.md, resources/flatten-tables.ts, config/hwp-config.yaml) or inline the essential details; as written, the skill defers CLI specifics to files that don't exist in the bundle.
Make the VERIFY step concrete: specify an actual check (e.g., grep for heading markers, confirm non-empty output, count extracted tables) instead of 'inspect structure', and show the kordoc flags for page_range and JSON output inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The actionable parts (Entry, Scenes, Transitions, Failure and recovery, Guardrails, Canonical command path) are efficient, but several sections are meta-padding Claude does not need: the "Actions | SSL primitive" table, the "Resource scope" table (LOCAL_FS/PROCESS/MEMORY), "Control-flow features", and "Intent signature" largely duplicate "When to use"/"Preconditions". This fits "mostly efficient but includes some unnecessary explanation or could be tightened" rather than 2, since no space is spent explaining known concepts (e.g., what HWP is). | 3 / 5 |
Actionability | The canonical command path gives copy-adaptable commands ("bunx kordoc@latest \"{input_path}\" -o \"{output_path}\"", "bun run .../flatten-tables.ts \"{output_path}\"", plus a batch variant), and runtime checks are concrete ("bun --version"). Minor gaps keep it below 5: the kordoc CLI options for page_range/format/JSON output are never shown (deferred to an external protocol file), so the common cases are not fully covered inline. | 4 / 5 |
Workflow Clarity | The PREPARE→ACQUIRE→ACT→VERIFY→FINALIZE scene sequence, explicit Transitions, and a failure/recovery table with feedback loops ("Empty Markdown output → consult resources/troubleshooting.md", "Stale kordoc cache → use bunx kordoc@latest") form a clear sequence with most checkpoints present. Not 5 because VERIFY is underspecified — "inspect structure for headings, tables..." gives no concrete verification command or acceptance check. | 4 / 5 |
Progressive Disclosure | The body is well-sectioned with clearly signaled one-level-deep references ("Execution protocol: resources/execution-protocol.md", "Troubleshooting: resources/troubleshooting.md", "Keep full CLI details in resources/execution-protocol.md"). However, none of the referenced bundle files (resources/execution-protocol.md, resources/troubleshooting.md, resources/flatten-tables.ts, config/hwp-config.yaml) exist in the skill's bundle — the references/ and resources/ directories are absent — so the deferred detail is unreachable and navigation cannot fully deliver, keeping this below 5. | 4 / 5 |
Total | 15 / 20 Passed |