Content
75%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, lean instruction-only skill with a clear sequenced workflow, strong validation guidance, and appropriate deference to official host docs. The main gaps are the absent fix-and-retry feedback loop and a small amount of duplicated emphasis.
Suggestions
Add an explicit validation feedback loop, e.g. 'If a hook test fails or the block is not honored: re-check the host's current payload/matcher shape, fix the adapter (not the shared policy), and re-run the validation command.'
Deduplicate the Codex caveat — state the interactive-vs-non-interactive warning once (Pitfalls or step 6) and reference it from the Output Shape checklist.
Include one short worked example of a normalized decision (e.g., a tool_input pattern -> 'block with reason' JSON snippet) to make the shared-policy contract concrete without freezing host schemas.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes competence — it never explains what hooks or plugins are, and every section is directive. Minor trimming is possible: the Codex interactive-vs-non-interactive caveat appears in both Workflow step 6 and the Output Shape list, and 'Do not freeze full hook schemas' in Pitfalls restates the 'Official Docs First' theme. | 4 / 5 |
Actionability | The guidance is concrete and executable for an instruction-only skill: a decision rule for classifying requests, an explicit normalized input shape (event name, tool name, tool input, cwd, permission mode, transcript identifiers), an output checklist, and specific doc URLs per host. Specific commands are deferred to external docs, which is explicitly justified ('Hook event names, matcher fields, input payloads... can change'), so the flexibility exception applies; a worked example of a normalized policy decision would close the remaining gap. | 4 / 5 |
Workflow Clarity | The six-step workflow is clearly sequenced (classify -> define policy -> normalize input -> implement policy once -> thin adapters -> validate per host) with explicit validation checkpoints in step 6 (validation commands, real repository, trust prompts) and an evidence checklist in Output Shape. It just misses the top anchor because there is no explicit fix-and-retry feedback loop for failed validation. | 4 / 5 |
Progressive Disclosure | No bundle files exist (no references/, scripts/, or assets/), and the body is a well-organized single file (~80 lines) with clearly labeled sections and one-level-deep external links (the official doc URLs). At ~80 lines it exceeds the under-50-line simple-skill case, and a couple of sections (per-host doc links, pitfalls) could be split into reference files, keeping it just below the top anchor. | 4 / 5 |
Total | 16 / 20 Passed |