Content
82%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.
An information-dense, highly actionable body built around provider-specific facts and copy-paste verification code, with well-signaled references that all resolve except the examples/ paths. The main deductions are the promotional tail sections (Recommended + Related Skills, with a duplicated entry) and the absence of a single consolidated handler sequence or in-bundle examples to back the 'complete handlers' pointer.
Suggestions
Consolidate the 'Recommended: webhook-handler-patterns' and 'Related Skills' sections: webhook-handler-patterns appears in both with overlapping link lists — a single line per related skill (or one merged section) would reclaim ~20 lines of pure promotion.
Add a short numbered end-to-end sequence (read raw body → verify signature → 401 on fail → parse → dispatch on top-level event → respond 2xx within 20s → dedupe on envelope id → defer slow work) so the workflow reads as one coherent order instead of being assembled across three sections.
Fix or fulfill the examples/ references: the body cites examples/express/, examples/nextjs/ and examples/fastapi/ for 'complete handlers with tests' but no examples/ directory exists in the bundle — either ship it or remove/redirect those links (e.g., to the repository URL).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core sections are dense and every token earns its place — provider facts Claude cannot know (raw-body HMAC, no timestamp signed, retry schedule '12 s, 2m24s, 30m8s', 20-second 2xx deadline, 20th failure disables) with zero padding or explanation of known concepts. Sits at 4 rather than 5 because ~20 lines of tail content could be trimmed: the 'Recommended' section's four external link bullets and the nine-bullet 'Related Skills' list are cross-promotion, and webhook-handler-patterns is listed in both sections. | 4 / 5 |
Actionability | Copy-paste-ready executable verification code with input validation, timing-safe comparison, and the express.raw reading instruction; plus concrete commands ('npx hookdeck-cli listen 3000 agentset --path /webhooks/agentset'), an env var with its dashboard location, explicit 401-on-mismatch failure behavior, and a Python pointer ('hmac.compare_digest on bytes'). Fully executable and covers the common cases, matching the top anchor. | 5 / 5 |
Workflow Clarity | The sequence is explicit and in the right order — read the body raw, verify first ('parse only after the check'), 401 on malformed/mismatch, dispatch on the top-level event, respond 2xx within 20 seconds, 'Make handlers idempotent (dedupe on the envelope id) and do slow work asynchronously' — with the signature check acting as a built-in validation checkpoint. Not 5 because no single end-to-end ordered sequence is presented in SKILL.md: the steps are distributed across the Verification, Event Types, and Delivery sections, and the complete handler flow is deferred to the examples/ directory. | 4 / 5 |
Progressive Disclosure | Good structure with clearly signaled one-level-deep references: the three references/*.md files listed in Resources each exist in the bundle with a one-line description, and the event table/env-var/retry content is appropriately inlined. Not 5 because the body repeatedly points to examples/express/, examples/nextjs/, examples/fastapi/ and examples/ ('For complete handlers with tests, see...') yet no examples/ directory exists in the bundle — dangling key references are a navigation gap beyond the 'minor organization gaps' of the top anchor. | 4 / 5 |
Total | 17 / 20 Passed |