CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

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

82%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

The canonical home for this skill is paddle-subscription-sync in PaddleHQ/paddle-agent-skills

SKILL.md
Quality
Evals
Security

Quality

Content

88%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An unusually strong skill body: complete executable code at every step, explicit sequencing and ordering guards, a real verification checklist, and a pitfalls section that doubles as troubleshooting. The only structural weakness is that a document of this length keeps everything — including generic Supabase boilerplate and MCP usage notes — inline in SKILL.md with no reference files to offload to.

DimensionReasoningScore

Conciseness

The body is dense, code-first, and almost entirely Paddle-specific ("canceled is the terminal state", the last_event_at ordering guard, simulator destination types) rather than generic explanation, so it sits above anchor 3. It falls short of anchor 5 because the ~60 lines of standard Supabase SSR client boilerplate in "Supabase clients" and the "Why mirror state at all?" rationale section are over-explanation Claude could do without.

4 / 5

Actionability

Every stage ships fully executable, copy-paste-ready code: the complete CREATE TABLE / upsert-function SQL, the typed processEvent/saveSubscription/saveCustomer handlers, getCustomerId, getUserSubscription, the access-gate and UI-state functions, and both backfill paths (MCP pagination snippet and the cron reconcile route). The only external dependency (getPaddleInstance, the webhooks route) is explicitly scoped to a sibling skill, and common cases (scheduled cancel, pause, trial conversion, backfill) are all covered.

5 / 5

Workflow Clarity

The sequence is explicit and gated: prerequisites up front ("This skill assumes you already receive verified webhooks. If you don't, do webhooks first"), "Run it once before flipping access gating to read from your DB", and a 6-step "Verify the integration" checklist with expected outcomes per step ("Confirm the row flips to canceled and the scheduled change columns clear"). Validation for the batch/database operations is present, so the destructive/batch cap does not apply, and error recovery is covered by the scheduled reconciliation job and the Common pitfalls diagnostic list — matching anchor 5.

5 / 5

Progressive Disclosure

Structure is genuinely good — clear section headers in logical implementation order with a Related docs list — so it is above anchor 3's "some structure". But it is a ~450-line single file with no bundle files at all: content that belongs in references (the generic Supabase client wrappers, the dense Paddle MCP usage blockquote, full backfill listings) is inlined, and there is no one-level-deep reference mechanism of the kind anchor 4's example shows, placing it between anchors 3 and 4.

4 / 5

Total

18

/

20

Passed

Description

66%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A specific, well-scoped description that clearly communicates what the skill does and covers its full component range, anchored by the distinctive "Paddle" domain term. Its one real weakness is the absence of any "Use when…" trigger clause, which both caps completeness and leaves natural trigger synonyms ("sync", "billing") uncovered.

Suggestions

Add an explicit trigger clause, e.g. "Use when syncing or mirroring Paddle subscriptions and customers into your database, gating feature access by subscription status, or handling Paddle subscription webhooks" — this lifts completeness from 3 toward 5 and adds the natural synonyms (sync, billing) currently missing from trigger_term_quality.

Consider narrowing the webhook framing (e.g. "Mirror Paddle subscription and customer state into your database from subscription and customer webhooks") to reduce overlap with the sibling `webhooks` skill that handles route setup and signature verification.

State the primary user-facing outcomes as actions rather than topic nouns — e.g. "define the mirror schema, upsert rows safely, map app users to Paddle customers, and gate access by subscription status" — to move specificity from a topic list toward anchor 5's concrete-action style.

DimensionReasoningScore

Specificity

"Mirror Paddle subscription and customer state into your database via webhooks" names a concrete action in a specific domain, and "schema, upsert pattern, status semantics, scheduled changes, and access gating" enumerates specific deliverables with near-comprehensive coverage — slightly below anchor 5 because that enumeration is a list of topic-nouns rather than the multiple parallel action verbs ("Extract text… fill forms, merge documents, convert pages to images") of the anchor 5 example, putting it between anchors 4 and 5.

4 / 5

Completeness

The "what" is clearly and comprehensively answered (mirror Paddle subscription/customer state into the database via webhooks, with the component list), but there is no "Use when…" clause or any equivalent explicit trigger guidance anywhere in the description — "when" is at best weakly implied by the topic itself, which per the judging guidelines caps this dimension at 3. It is not a 2 because the "what" is concrete and detailed, not vague.

3 / 5

Trigger Term Quality

Good keyword coverage of terms users would naturally say: "Paddle", "subscription", "customer", "webhooks", "database", "upsert", "access gating". It falls short of anchor 5's "comprehensive coverage of natural terms including synonyms" because common synonyms and phrasings are missing — a user would likely say "sync" (only "Mirror" appears) or "billing"/"billing portal", neither of which is present.

4 / 5

Distinctiveness Conflict Risk

"Paddle" plus subscription mirroring is a clear niche with distinct triggers, but "via webhooks" is prominent in the description while a closely related sibling skill (`webhooks`) exists in the same suite — a request like "set up Paddle webhooks" could plausibly route here when the route-handler/verification skill is intended. That is minor overlap risk with a closely related skill, matching anchor 4 rather than anchor 5's "minimal conflict risk".

4 / 5

Total

15

/

20

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository

PaddleHQ/paddle-agent-skills

Path

providers/claude/plugin/skills/subscription-sync/SKILL.md

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.