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.
Highly actionable content with two complete executable reference implementations and clearly signaled supporting files. The main costs are token duplication between SKILL.md and references/overview.md, a large promotional footer, and example links that resolve to nothing inside the bundle.
Suggestions
Remove the duplicated "Common Event Types" table and "Top-Level Payload Structure" sections from SKILL.md and point to references/overview.md, which already contains both.
Trim the 11-entry "Related Skills" list and the webhook-handler-patterns link list to the few most relevant, cutting ~20 lines of promotional tokens.
Fix the examples/express/, examples/nextjs/, and examples/fastapi/ links — either include those directories in the bundle or remove/replace the links, since they currently lead nowhere for a user following them locally.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Core sections are code-first and efficient, but the "Common Event Types" table and "Top-Level Payload Structure" duplicate content already in references/overview.md, and roughly 20 lines of "Related Skills" promotional links (11 external repos) pad the token budget. Mostly efficient but could be tightened — the level-3 anchor fits better than level 4 because the duplication and promotional footer go beyond minor trimming. | 3 / 5 |
Actionability | Two complete, copy-paste-ready handlers (Express with discord-interactions and FastAPI with PyNaCl) covering raw-body capture, header checks, Ed25519 verification, PING 204 response, and event dispatch, plus concrete env-var and tunnel commands ("npx hookdeck-cli listen 3000 discord --path /webhooks/discord"). Fully executable and covering the common cases — level 5. | 5 / 5 |
Workflow Clarity | The critical ordering (verify signature before parsing, respond 204 to PING) is explicit in both code examples, and the PING section states that "Endpoint registration fails until your handler does this correctly" — a real checkpoint. However the end-to-end setup sequence (public key → handler → tunnel → portal registration → PING validation) is implicit, scattered across sections rather than sequenced; level 4 with minor validation gaps. | 4 / 5 |
Progressive Disclosure | Three real, clearly labeled, one-level-deep reference files (references/overview.md, setup.md, verification.md) are well signaled in a Reference Materials section with descriptions. Minor gaps: the "examples/express/", "examples/nextjs/", and "examples/fastapi/" links point to directories that do not exist in the bundle, and the event table and payload structure duplicate reference content inline. Good structure overall — level 4 rather than 5 because of the broken example paths and inline duplication. | 4 / 5 |
Total | 16 / 20 Passed |