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 domain-specific trigger terms that clearly identify the Paddle webhook integration niche. Its main weakness is the absence of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. The description is concise, uses third person voice appropriately, and lists concrete capabilities.
Suggestions
Add a 'Use when...' clause such as 'Use when integrating Paddle webhooks, syncing subscription data to a database, 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 handling, 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', 'database'. These cover the domain well and match how developers would describe this task. | 3 / 3 |
Distinctiveness Conflict Risk | Very distinct niche — specifically about Paddle payment platform webhook integration for subscription management. The combination of 'Paddle', 'webhooks', 'subscription state', and 'upsert pattern' makes it highly 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 strong, highly actionable skill that provides complete executable code for every step of Paddle subscription syncing — from schema to upsert handlers to access gating to backfill. The workflow is well-sequenced with explicit verification steps. The main weakness is length; the document could be more concise by trimming explanatory prose (e.g., 'Why mirror state at all?') and potentially splitting the backfill section into a separate file.
Suggestions
Remove or drastically shorten the 'Why mirror state at all?' section — Claude understands the performance benefits of local state without explanation.
Consider splitting the backfill section (MCP approach + SDK script) into a separate BACKFILL.md file referenced from the main skill, reducing the main document's length.
| 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 a concept Claude already understands, and some prose around the code blocks could be tightened). The 'Common pitfalls' section is valuable but slightly verbose. | 2 / 3 |
Actionability | Excellent actionability — provides complete, executable SQL schema, TypeScript upsert handlers, query utilities, backfill scripts, and access-gating functions. All code is copy-paste ready with real Paddle SDK types and Supabase patterns. The status table with access recommendations is immediately usable. | 3 / 3 |
Workflow Clarity | The workflow is clearly sequenced: schema → customer mapping → event processing → status semantics → scheduled changes → querying → backfill → verification. The 'Verify the integration' section provides explicit validation checkpoints with expected outcomes. The prerequisites establish clear ordering with the webhooks skill. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and logical sections, and references external skills ('webhooks', 'sandbox-testing') and external docs. However, the document is quite long (~300 lines) and some sections like the MCP backfill details and the full backfill script could be split into separate files. No bundle files are provided to offload content to. | 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.