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.
A well-crafted skill body: executable verification code in two languages, precise gotchas, and clean one-level-deep references. The main weaknesses are broken examples/ links that promise handler code absent from the bundle, a duplicated event table, and cross-promotional link sections that spend tokens without advancing the task.
Suggestions
Fix progressive_disclosure: the links to examples/express/, examples/nextjs/, and examples/fastapi/ point to directories that don't exist in the bundle — either include those example handlers or remove the pointer to 'complete handlers with route wiring, event dispatch, and tests'.
Tighten conciseness: drop the duplicated Common Event Types table (references/overview.md already carries a richer version with use cases) and compress the Recommended/Related Skills cross-link sections to a couple of lines.
Sharpen workflow_clarity: add a short numbered handler sequence in the body (verify raw body → parse → dispatch on event type → respond 2xx, reject with 400 on signature mismatch) instead of deferring sequence and checkpoints entirely to the external handler-sequence reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The verification core is lean and earns its tokens, but ~20 lines of cross-promotion ("Recommended: webhook-handler-patterns" with four GitHub links, "Related Skills" with five, "Attribution") plus an event table duplicated in references/overview.md could be trimmed. Efficient overall with minor padding rather than the every-token-counts ideal. | 4 / 5 |
Actionability | Two copy-paste-ready snippets (Node SDK Webhook.verifyEventBody and a timing-safe Python HMAC verify), a concrete env var, a concrete tunnel command, and specific event/header tables fully cover the common verification cases. Not 4 — no executable gaps remain in the core flow. | 5 / 5 |
Workflow Clarity | The core action (verify the raw body with the shared secret, then dispatch on event type) is unambiguous with critical gotchas inline (raw body, timing-safe compare, event nested under `event`), but the body never lays out an explicit ordered handler sequence with validation checkpoints — deferring that to an external handler-sequence reference. Not 5 because checkpoints like "respond 400 on signature failure" live only in references/verification.md, not the main flow. | 4 / 5 |
Progressive Disclosure | The three references/*.md files exist, are one level deep, and are clearly signaled both inline and in a Reference Materials section. However, the prominent links to examples/express/, examples/nextjs/, and examples/fastapi/ point to directories that do not exist in the bundle, breaking navigation for the promised complete handlers. Not 5 due to these dead paths; not 3 since all present references are well-organized and clearly signaled. | 4 / 5 |
Total | 17 / 20 Passed |