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

77%

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

Fix and improve this skill with Tessl

tessl review fix ./providers/cursor/plugin/skills/subscription-sync/SKILL.md

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

SKILL.md
Quality
Evals
Security

Quality

Content

71%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 actionable, information-dense skill: every section delivers executable code or concrete Paddle-specific semantics, and it closes with a real verification procedure. Its weaknesses are structural and budgetary — generic Supabase/Next.js boilerplate and obvious rationale pad the token cost, and the whole thing is one monolithic file where backfill, MCP usage, and client setup belong in one-level-deep reference files.

Suggestions

Move the generic Supabase client wrappers (`server.ts` / `server-internal.ts`) and the Paddle MCP tool-usage notes into a `references/` file (e.g. `references/backfill.md`), keeping only the service-role-vs-anon distinction inline.

Cut or compress the "Why mirror state at all?" section — the read-your-own-DB-vs-API tradeoff is one sentence of common knowledge.

Add failure-path guidance to the verification steps (what to check when rows are missing or the status doesn't flip: destination Usage type, webhook receipt logs, ordering guard) to complete the feedback loop.

DimensionReasoningScore

Conciseness

The body is dense with genuinely non-obvious Paddle knowledge (the `last_event_at` ordering guard, scheduled-change semantics, the 50-call MCP cap), but it includes unnecessary explanation Claude already knows: the ~25-line generic Supabase `createServerClient` cookie wrapper boilerplate, and the "Why mirror state at all?" section explaining that checking your own DB is faster than an API round-trip. Not 4: the Supabase boilerplate block is more than a minor instance of over-explanation; not 2: the majority of sections are tight and earn their tokens.

3 / 5

Actionability

Fully executable, copy-paste-ready guidance throughout: complete SQL DDL and `upsert_subscription`/`upsert_customer` functions, a typed `processEvent` webhook router, `getCustomerId`/`getUserSubscription` readers, an MCP pagination snippet, a cron Route Handler for backfill, and a concrete `hasActiveSubscription` gate. Specific examples cover the common cases (out-of-order events, no-customer-yet, cancel-mid-period); no gaps found.

5 / 5

Workflow Clarity

Clear sequence — prerequisites, schema, handlers, status semantics, querying, backfill, then a numbered "Verify the integration" section with explicit checkpoints ("both should have the new rows within a second", "Confirm the row flips to `canceled` and the scheduled change columns clear"), and the batch backfill does include verification plus a scheduled reconciliation job. Not 5: there is no error-recovery feedback loop — the steps say what to confirm but not what to do when a checkpoint fails (e.g. rows missing or status not flipping); not 3: validation checkpoints for the risky batch operation are explicitly present.

4 / 5

Progressive Disclosure

Sections are well-organized with clear headers, but this is a ~450-line monolithic SKILL.md with no bundle files; content that clearly belongs at one level deeper is inlined — the generic Supabase client setup, the Paddle MCP tool usage notes, and the backfill/reconciliation job would each fit a `references/` file. Cross-references to sibling skills (`webhooks`, `checkout-web`, `subscription-cancel`, `sandbox-testing`) are prose mentions rather than clearly signaled links, though the external "Related docs" section is fine. Not 2: structure is present and navigable; not 4: several large blocks should be split out of the main file.

3 / 5

Total

15

/

20

Passed

Description

71%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 states what the skill does with an enumerated action list, but it lacks any explicit 'Use when...' trigger clause, which both caps completeness and leaves the when-to-use boundary with sibling Paddle skills implicit. Adding trigger phrases (e.g. "Use when syncing/mirroring Paddle subscriptions or billing state into a local database") would lift it to top tier.

Suggestions

Add an explicit 'Use when...' clause naming trigger phrases, e.g. "Use when you need to sync or mirror Paddle subscriptions, customers, or billing state into your own database, or when gating features on subscription status."

Include the synonym "sync" (already in the skill name) alongside "Mirror", since users are more likely to say 'sync Paddle subscriptions to my database' than 'mirror'.

Clarify the boundary with the sibling `webhooks` skill (e.g. "after verified webhooks are already set up") so 'via webhooks' does not cause this skill to trigger for plain webhook-handler requests.

DimensionReasoningScore

Specificity

"Mirror Paddle subscription and customer state into your database via webhooks" plus the enumerated actions "schema, upsert pattern, status semantics, scheduled changes, and access gating" lists multiple concrete capabilities that comprehensively cover the skill's scope. Not 4: the action list is complete rather than having minor coverage gaps; not below: every clause names a concrete action, no vague filler.

5 / 5

Completeness

The "what" is explicit and detailed ("Mirror Paddle subscription and customer state into your database... schema, upsert pattern, status semantics, scheduled changes, and access gating"), but there is no "Use when..." clause or equivalent trigger guidance — the "when" is only weakly implied by naming the inputs. Per the judging guidelines, a missing explicit 'Use when' clause caps completeness at 3; not 2 because the "what" half is clearly and fully stated.

3 / 5

Trigger Term Quality

Strong natural keywords: "Paddle", "subscription", "customer", "database", "webhooks", "upsert", "access gating" — exactly what a user would say. Not 5: it uses "Mirror" but omits the common synonyms "sync" (the skill's own name) and "billing", so a few natural phrasings a user would actually say are missing.

4 / 5

Distinctiveness Conflict Risk

"Paddle subscription and customer state" pins a clear niche with distinct triggers, so it is unlikely to fire for unrelated skills. Not 5: the phrase "via webhooks" creates minor overlap risk with a closely related sibling webhook-handling skill (the body references a separate `webhooks` skill), though the mirrored-database framing mostly disambiguates.

4 / 5

Total

16

/

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/cursor/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.