CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

paddle-webhooks

Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing.

71

1.20x
Quality

82%

Does it follow best practices?

Impact

100%

1.20x

1 of 3 eval scenarios. Add 2 more for a full score.

SecuritybySnyk

Medium

Suggest reviewing before use

SKILL.md
Quality
Evals
Security

Quality

Content

81%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An excellent, highly executable skill: complete code paths, explicit validation with failure-injection, and dense Paddle-specific knowledge that Claude cannot infer. Its two weaknesses are repeated restatement of the same rationale (status-code semantics, timeouts, replay) and some inline content (MCP conventions, full pitfalls list) that belongs in a reference file.

Suggestions

State the 401/500 rationale once (e.g. in the delivery-contract or Step 3 prose) and reference it from the route-handler comment and the pitfalls bullets instead of re-deriving it three times.

Move the generic Paddle-MCP conventions blockquote and the less-common pitfalls (clock skew, IP allowlisting, Pages Router) into a reference file (e.g. references/paddle-mcp.md, references/troubleshooting.md) and link to them, trimming the main body's token cost.

DimensionReasoningScore

Conciseness

Mostly efficient — the retry schedules, 5-second timeout, per-destination secrets, and simulator quirks are genuinely non-obvious domain knowledge Claude cannot know. But the 401-vs-500 rationale is explained three times (the route comment, the following prose paragraph, and two pitfall bullets), and the 5-second timeout and replay/missed-events guidance are each repeated, so noticeable tightening is possible. Above the 2 anchor (the verbosity is limited to a few repeated passages, not pervasive padding) but below 4, where only minor trims would be needed.

3 / 5

Actionability

Fully executable throughout: copy-paste-ready TypeScript for the route handler, SDK helper, typed event switch, guarded UPSERT SQL, event-id ledger with its table DDL, exact env vars, npm/ngrok commands, dashboard click-paths, and MCP `execute` snippets. Specific examples cover the common cases (subscription, transaction, customer) plus edge handling, matching the top anchor.

5 / 5

Workflow Clarity

A clearly sequenced pipeline (prerequisites → destination → SDK helper → route handler → event routing → idempotency → queueing → local testing) closes with an explicit "Verify the integration" checklist that includes a deliberate failure-injection feedback loop (tamper the secret, confirm non-2xx, restore, replay). Error-recovery guidance (409 duplicate destination, clock skew, missed events) is explicit, matching the validation-with-feedback-loop anchor.

5 / 5

Progressive Disclosure

Good single-file structure with well-labeled sections and clearly signaled outgoing pointers (sibling skills `subscription-sync`/`sandbox-testing`/`checkout-web` and a Related-docs list, all one level deep — no bundle files exist, so nothing is dangling). Minor gap: the long generic Paddle-MCP conventions blockquote and the ~12-item pitfalls list are inline material that would sit better in a reference file, which keeps it below the 5 anchor's 'appropriately split' bar.

4 / 5

Total

17

/

20

Passed

Description

75%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that names the exact domain and enumerates concrete capabilities, but it omits any explicit 'Use when...' trigger clause, leaving the 'when' half implicit. Adding one sentence of trigger guidance would move it to the top tier.

Suggestions

Append an explicit trigger clause, e.g. "Use when building the server-side endpoint that receives Paddle (Billing) webhook events in a Next.js app, or when debugging Paddle webhook delivery, signature, or retry issues."

Include a couple of natural synonym phrasings users might say, such as "webhook endpoint" or "Paddle notifications", to broaden trigger-term coverage.

DimensionReasoningScore

Specificity

"Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing" lists five concrete, distinct actions (receive, verify signatures, handle idempotency, handle retries, test locally) that comprehensively cover the skill's scope, matching the multi-action comprehensive anchor rather than the 'minor gaps' anchor below.

5 / 5

Completeness

The 'what' is clear and concrete, but there is no explicit 'Use when...' clause or equivalent trigger guidance — the 'when' is only weakly implied by the domain naming. Per the judging guideline, a missing explicit trigger clause caps completeness at 3 even though the what-side is strong.

3 / 5

Trigger Term Quality

Natural terms users would say are present — "Paddle webhooks", "signature verification", "Next.js Route Handler", "retry semantics", "local testing" — but a few common phrasings are missing, e.g. "webhook endpoint", "Paddle notifications", or naming the events (subscription/transaction). Not the 5-level anchor, which requires synonym-level coverage; clearly above the 3-level 'some relevant keywords' anchor.

4 / 5

Distinctiveness Conflict Risk

The pairing of "Paddle" + "webhooks" + "Next.js Route Handler" carves out a clear niche with distinct triggers; it would not plausibly fire for a generic Next.js API skill or another payment provider's webhooks. Minimal conflict risk.

5 / 5

Total

17

/

20

Passed

Validation

100%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

PaddleHQ/paddle-agent-skills

Path

skills/webhooks/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.