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

85%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.

A strong, highly actionable body whose core value is genuinely non-obvious Paddle-specific knowledge, with a real validation checklist and safe batch handling. Its two weaknesses are the inlined Supabase/MCP peripheral content in an otherwise monolithic 450-line file and the boilerplate client code that could be cut.

Suggestions

Move the Supabase client setup section and the Paddle MCP tool-usage block into a references/ file (e.g. references/clients.md), keeping only a one-line pointer plus the RLS/service-role warning in SKILL.md.

Replace the two full createServerClient boilerplate blocks with just the cookie-less service-role wrapper — the one variant Claude wouldn't guess — and reference the standard setup by name.

Consider splitting the backfill/reconciliation section into its own reference so SKILL.md stays a lean overview of the core webhook-sync path.

DimensionReasoningScore

Conciseness

Nearly every section contributes non-obvious domain knowledge (out-of-order-event guards, service-role vs anon RLS pitfalls, terminal-state semantics, sandbox simulation quirks) with no padding explaining concepts Claude already knows. The two full Supabase client boilerplate blocks are the exception — the skill itself says "If your app already has equivalents, use those", so ~45 lines of standard @supabase/ssr setup could be trimmed to the one non-obvious detail (the cookie-less service-role wrapper).

4 / 5

Actionability

Guidance is fully executable: complete SQL DDL and upsert functions, typed TypeScript webhook handlers with import paths and env vars, a ready cron route with its bearer-secret auth check, and a concrete verification procedure. Copy-paste-ready code covers the common cases (single-item subscriptions, email fallback matching, backfill pagination).

5 / 5

Workflow Clarity

The sequence is clear (prerequisites → schema → handlers → user mapping → status gating → querying → backfill → verify), the batch backfill includes ordering guards plus the 50-call-cap splitting strategy, and the "Verify the integration" section is an explicit 6-step validation checklist with error signals (rows appearing, scheduled-change columns set, status flipping to canceled).

5 / 5

Progressive Disclosure

The ~450-line body is a single monolithic file with no bundle files at all. Structure within the file is good, but content that belongs in separate references is inlined — the Supabase client setup section and the ~28-line MCP tool-usage block are peripheral to the core mirroring workflow and would be better as a one-level-deep reference file, per the anchor's "content that should be separate is inline".

3 / 5

Total

17

/

20

Passed

Description

70%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 distinctive, vendor-specific description with a clear concrete capability list, undermined by the complete absence of "when to use" trigger guidance. Adding a Use-when clause with natural phrases like "syncing Paddle subscriptions" or "billing webhooks" would move it into the top band.

Suggestions

Append an explicit trigger clause, e.g. "Use when syncing Paddle subscriptions or customers into your database, or when gating feature access by subscription status."

Include the natural verb "sync" (users say "sync Paddle subscriptions", not "mirror") and "billing" among the keywords.

Mention the backfill/reconciliation capability so the description's coverage matches the skill body.

DimensionReasoningScore

Specificity

The description gives one concrete action — "Mirror Paddle subscription and customer state into your database via webhooks" — and enumerates specific capabilities ("schema, upsert pattern, status semantics, scheduled changes, and access gating") in third-person voice. It falls short of 5 because backfill/reconciliation, a major section of the skill, is unmentioned — a minor coverage gap; it exceeds 3 because several concrete actions are named, not just a domain.

4 / 5

Completeness

"What" is explicit and concrete (mirroring subscription/customer state into a database via webhooks), but there is no "Use when..." clause or any equivalent trigger guidance, capping completeness at 3 per the rubric guideline.

3 / 5

Trigger Term Quality

Natural terms a user would say are present: "Paddle", "subscription", "customer", "webhooks", "database". A few natural variants are missing — users would likely say "sync" rather than "Mirror", and "billing" is absent — so it does not reach comprehensive synonym-level coverage.

4 / 5

Distinctiveness Conflict Risk

"Paddle subscription and customer state" names a clear vendor-specific niche with distinct triggers; only a skill about exactly this Paddle integration would match, so conflict risk is minimal.

5 / 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/codex/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.