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.
The body is a dense, highly actionable reference for a provider whose facts (no signature, no event type, legacy callback_url, dhi_metadata, 255-char URL limit) Claude cannot know or infer, with executable code, exact env vars, and explicit validation checkpoints. The main weaknesses are repetition of the unsigned-webhook point, a dangling set of examples/ links, and a layered-bullet rather than sequenced presentation of the handler flow.
Suggestions
State the unsigned/no-HMAC fact once in the Verification section and reference it from elsewhere (intro, env-var comments, dhi_metadata) instead of restating the full enumeration three or four times — the repetition is the main token cost in the body (conciseness).
Fix or remove the links to examples/express/, examples/nextjs/, and examples/fastapi/ — those directories are not in the bundle, so following them for 'complete handlers with tests' dead-ends (progressive_disclosure).
Present the handler flow as an explicit ordered sequence (verify URL token → validate payload shape → check repo allowlist → re-confirm tag via GetRepositoryTag → dispatch async → respond 2xx) with per-step error handling, rather than a list of layered controls (workflow_clarity).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most content is non-obvious provider fact Claude cannot infer ("The registered URL must be 255 characters or fewer", the callback_url deprecation history, the dhi_metadata schema), but there is redundancy: the unsigned/no-HMAC point is restated in the intro ("No signature header, no shared secret, no HMAC, no timestamp"), the Verification section ("Do not write an HMAC verifier, a signature-header check, a timestamp/replay window"), the env-var comments, and the dhi_metadata section; the nine-item Related Skills list and Attribution block also add tokens without operational value. Not 3 because nearly every section adds provider-specific knowledge; not 5 because of the repetition and boilerplate sections that could be trimmed. | 4 / 5 |
Actionability | Guidance is fully executable: a copy-paste timing-safe token verifier with a length guard (crypto.timingSafeEqual), exact env var names and example values (DOCKER_HUB_WEBHOOK_TOKEN, DOCKER_HUB_ALLOWED_REPOS=myorg/myapp,myorg/dhi-python), an exact CLI command ("npx hookdeck-cli listen 3000 docker-hub --path /webhooks/docker-hub"), the exact Hub API endpoint and auth flow (GET .../tags/{tag}, POST /v2/auth/token), and explicit status codes for every failure path (500 fail closed, 400 malformed, 403 non-allowlisted). Not 4 because the inline material alone is enough to build a working handler for the common case. | 5 / 5 |
Workflow Clarity | The verification section enumerates controls with explicit checkpoints ("If the token env var is unset, fail closed (500)", "reject malformed bodies with 400", re-confirm the tag via GetRepositoryTag before acting, dedupe on repo_name + tag + pushed_at), so validation is clearly present. It is not 5 because the handler flow is presented as layered bullets rather than a sequenced workflow with error-recovery feedback loops, deferring the sequence to the external webhook-handler-patterns skill; it is above 3 because every risky step carries an explicit validation rule and status code. | 4 / 5 |
Progressive Disclosure | Structure is good: a Reference Materials section gives descriptive labels for each of the three real one-level-deep reference files, and inline pointers appear where relevant ("See [references/verification.md] ... for the full rationale, the Hub API re-check"). However, the body links "examples/express/", "examples/nextjs/", and "examples/fastapi/" for "complete handlers with tests" and those directories are not present in the bundle, and the inline payload field table duplicates content said to live in references/overview.md. Not 3 because the core split (actionable overview + three clearly-signaled reference files) works well; not 5 because of the dangling examples/ links and the duplication. | 4 / 5 |
Total | 17 / 20 Passed |