paddle-webhooks
Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing.
86
80%
Does it follow best practices?
Impact
98%
1.28xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/webhooks/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a strong, specific description that clearly identifies the technology stack (Paddle, Next.js) and lists concrete capabilities (signature verification, idempotency, retry semantics, local testing). Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill over others.
Suggestions
Add a 'Use when...' clause such as 'Use when the user needs to handle Paddle webhook events, set up payment notifications, or integrate Paddle billing callbacks in a Next.js app.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: 'signature verification, idempotency, retry semantics, and local testing' alongside the core action of 'Receive and verify Paddle webhooks in a Next.js Route Handler'. | 3 / 3 |
Completeness | Clearly answers 'what' (receive/verify Paddle webhooks with signature verification, idempotency, retry semantics, local testing) but lacks an explicit 'Use when...' clause or equivalent trigger guidance, which caps this at 2 per the rubric. | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'Paddle', 'webhooks', 'Next.js', 'Route Handler', 'signature verification', 'idempotency', 'local testing'. These are terms a developer would naturally use when seeking this functionality. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive with a clear niche: Paddle webhooks specifically in Next.js Route Handlers. The combination of 'Paddle' + 'webhooks' + 'Next.js' makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a high-quality, deeply actionable skill with excellent workflow clarity and verification steps. Its main weakness is verbosity — the delivery contract section, MCP conventions sidebar, and repeated rationale for the single-catch pattern inflate the token cost. The inline length would benefit from splitting some sections (pitfalls, MCP conventions) into separate referenced files.
Suggestions
Extract the MCP server conventions into a separate referenced file (e.g., `PADDLE_MCP_CONVENTIONS.md`) to reduce inline token cost — it's a tangent from the core webhook skill.
Consolidate the single-catch/500 rationale to one location instead of repeating it in the code comment, the paragraph after Step 3, and the pitfalls section.
Consider moving the 'Common pitfalls' section to a separate file or collapsing it significantly — several items (slow handlers, wrong secret, body parsing) restate guidance already given in the main steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is thorough and mostly well-written, but includes some unnecessary verbosity: the MCP server conventions block is a large tangent, the 'delivery contract' section over-explains retry semantics Claude could look up, and several pitfalls repeat points already made in the main flow (e.g., the single-catch rationale appears three times). Could be tightened by ~30% without losing actionability. | 2 / 3 |
Actionability | Fully executable TypeScript code for every step — SDK initialization, Route Handler, event routing, idempotency patterns (both UPSERT and ledger), and SQL schema. Commands for ngrok, npm install, and env vars are copy-paste ready. The TODO stubs are clearly marked as extension points, not missing instructions. | 3 / 3 |
Workflow Clarity | The 6-step workflow is clearly sequenced from destination creation through verification. Step 6 (verify the integration) includes explicit validation checkpoints: confirm log output, confirm dashboard 200, deliberately tamper with the secret and confirm 500, then restore and confirm retry succeeds. The 5-second timeout constraint and queue-before-ack pattern provide a clear feedback loop for error recovery. | 3 / 3 |
Progressive Disclosure | The skill references related skills (subscription-sync, sandbox-testing, checkout-web, catalog-setup) and external docs, which is good. However, with no bundle files, all content is inline in one long document (~300+ lines). The MCP conventions block and the extensive pitfalls section could be split into referenced files. The related docs section at the end is well-organized but the body itself is monolithic. | 2 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- PaddleHQ/paddle-agent-skills
- Commit
86596b3
- 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.