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 an explicit 'Use when...' clause, e.g., '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: 'receive and verify Paddle webhooks', 'signature verification', 'idempotency', 'retry semantics', and 'local testing'. These are all concrete, well-defined capabilities. | 3 / 3 |
Completeness | Clearly answers 'what does this do' (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', 'retry', 'local testing'. These cover the terms a developer would naturally use when seeking this functionality. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — the combination of 'Paddle webhooks' + 'Next.js Route Handler' creates a very specific niche that is unlikely to conflict with other skills. The domain is narrow and well-defined. | 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 executable code at every step, a clear multi-step workflow, and thorough verification instructions including deliberate failure testing. Its main weakness is verbosity — the delivery contract section, MCP conventions tangent, 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) — this tangent adds ~150 tokens that are only relevant when using the MCP tool, not for the core webhook skill.
Consolidate the repeated single-catch/500 rationale — it appears in the code comment, the paragraph after Step 3, and again in Common Pitfalls. State it once definitively and reference that location.
Consider moving the 'Common pitfalls' section to a separate PITFALLS.md or trimming it to a compact checklist, since several items restate guidance already given in the main flow.
| 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 placeholders are clearly marked as extension points, not missing instructions. | 3 / 3 |
Workflow Clarity | The 6-step workflow is clearly sequenced (create destination → SDK helper → route handler → event routing → idempotency → queue heavy work), with explicit validation in the 'Verify the integration' section that includes a deliberate failure test (tamper the secret, confirm 500, restore, confirm retry succeeds). The 5-second timeout constraint and feedback loop for retries are well-articulated. | 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
62438cd
- 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.