paddle-subscription-sync
Mirror Paddle subscription and customer state into your database via webhooks — schema, upsert pattern, status semantics, scheduled changes, and access gating.
67
80%
Does it follow best practices?
Impact
—
No eval scenarios have been run
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/subscription-sync/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 well-crafted description with strong specificity and excellent trigger terms targeting Paddle billing integration. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. The domain-specific terminology makes it highly distinctive and unlikely to conflict with other skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when integrating Paddle billing, setting up subscription webhooks, syncing customer/subscription data, or implementing access control based on Paddle subscription status.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: schema design, upsert patterns, status semantics, scheduled changes, and access gating. These are concrete, actionable capabilities rather than vague abstractions. | 3 / 3 |
Completeness | Clearly answers 'what' (mirror Paddle subscription/customer state via webhooks with specific patterns), 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', 'subscription', 'webhooks', 'customer', 'upsert', 'access gating', 'scheduled changes'. These are terms a developer working with Paddle billing integration would naturally use. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — the combination of 'Paddle' (a specific payment platform), 'webhooks', 'subscription state mirroring', and 'upsert pattern' creates a very clear niche that is 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, actionable skill with executable code examples covering the full lifecycle of Paddle subscription mirroring. Its main strength is the completeness and concreteness of guidance — from schema to event handling to access gating to backfill. The primary weakness is length; at ~300 lines it could benefit from splitting some sections (like backfill strategies or the MCP usage block) into separate referenced files, and a few explanatory passages could be trimmed.
Suggestions
Remove or significantly shorten the 'Why mirror state at all?' section — Claude understands the performance benefits of local state without explanation.
Consider extracting the backfill section (MCP + SDK approaches) into a separate referenced file to reduce the main skill's length and improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient with good code examples and tables, but includes some unnecessary explanation (e.g., 'Why mirror state at all?' section explains something Claude would already understand, and some prose around the code blocks could be tightened). The 'Common pitfalls' section is valuable but slightly verbose. | 2 / 3 |
Actionability | Fully executable TypeScript and SQL code throughout — schema DDL, upsert handlers, query functions, backfill scripts, and access-gating logic are all copy-paste ready with real Paddle SDK types and Supabase client usage. Every section provides concrete, runnable guidance. | 3 / 3 |
Workflow Clarity | The skill clearly sequences the full workflow: prerequisites → schema → user mapping → event processing → status semantics → scheduled changes → querying → backfill → verification. The 'Verify the integration' section provides explicit validation checkpoints with expected outcomes, and the pitfalls section addresses error recovery and edge cases like out-of-order events. | 3 / 3 |
Progressive Disclosure | The skill references other skills ('webhooks', 'sandbox-testing') and external docs, which is good. However, the content is quite long (~300 lines) and some sections like the MCP backfill details and the full common pitfalls list could potentially be split into referenced files. Without bundle files, everything is inline in one monolithic document. | 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.