paddle-subscription-sync

Mirror Paddle subscription and customer state into your database via webhooks — schema, upsert pattern, status semantics, scheduled changes, and access gating.

Quality

80%

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Advisory

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/subscription-sync/SKILL.md

Quality

Content

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, highly actionable skill that provides complete, executable code for every step of mirroring Paddle subscription state. Its main weakness is length — at ~300 lines with all content inline, it could benefit from splitting reference material (backfill scripts, MCP details) into separate files. The 'Why mirror state at all?' section and some surrounding prose add tokens without adding value for Claude.

Suggestions

Remove or drastically shorten the 'Why mirror state at all?' section — Claude doesn't need motivation for a pattern it's been asked to implement.

Consider extracting the backfill section (MCP and SDK script) into a separate BACKFILL.md reference file to reduce the main skill's token footprint.

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 understand, 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. Every major step has copy-paste-ready code with real Paddle SDK types and Supabase patterns.	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, and the pitfalls section addresses error recovery scenarios like out-of-order events.	3 / 3
Progressive Disclosure	The skill references other skills ('webhooks', 'sandbox-testing') and external docs appropriately, but the content itself is quite long (~300 lines) with everything inline. The MCP pagination details and backfill scripts could reasonably be split into separate reference files. However, the sections are well-organized with clear headers.	2 / 3
	Total	10 / 12 Passed

Description

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 that clearly identify the Paddle subscription/webhook domain. 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 carves out a distinct niche.

Suggestions

Add a 'Use when...' clause such as 'Use when integrating Paddle billing, handling Paddle webhooks, syncing subscription state, or implementing access control based on Paddle subscriptions.'

Dimension	Reasoning	Score
Specificity	Lists multiple specific concrete actions and concepts: schema design, upsert patterns, status semantics, scheduled changes, access gating, and webhook integration with Paddle. These are concrete, actionable capabilities.	3 / 3
Completeness	Clearly answers 'what does this do' (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', 'schema'. These cover the domain well and match how developers would describe this task.	3 / 3
Distinctiveness Conflict Risk	Highly distinctive — the combination of 'Paddle' (a specific payment provider), webhooks, subscription state mirroring, and the specific patterns mentioned creates a clear niche that is unlikely to conflict with other skills.	3 / 3
	Total	11 / 12 Passed

Validation

100%

Warnings & errors only

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: 72e6fdf

Reviewed: 20 days ago

Table of Contents

Discovery Implementation Validation

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.