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

Securityby

Medium

Suggest reviewing before use

Quality

Content

92%Weight 40%Scale 1-3

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

A dense, highly actionable integration guide with executable code and a verification checklist; its main weakness is monolithic structure with no reference files. Splitting backfill/status details into referenced files would improve progressive disclosure.

Suggestions

Move the backfill + MCP pagination details (the 50-call cap material) into a separate referenced file (e.g. `references/backfill.md`) and link to it from the main body.

Extract the full status-semantics table and UI-state logic into `references/status-semantics.md`, keeping only the access-gate snippet inline.

Fix the run-together sentence on line 182 ("update their payment method.Paddle Retain automatically retries") for readability.

Dimension	Reasoning	Score
Conciseness	The body is lean for the complexity it covers: executable SQL/TS blocks, a tight status table, and short prose that carries non-obvious domain gotchas (RLS service-role key, idempotent UPSERT, terminal `canceled` semantics) rather than explaining concepts Claude already knows.	3 / 3
Actionability	Fully executable, copy-paste-ready code with file paths (schema DDL, `processEvent` router, upsert functions, UI-state helper, backfill scripts) plus concrete event names and status values.	3 / 3
Workflow Clarity	The integration is sequenced topic-by-topic and closes with an explicit "Verify the integration" checklist (sandbox create → check tables → cancel → confirm status flip → simulator), with the Common pitfalls section providing error-recovery guidance.	3 / 3
Progressive Disclosure	Sections are clearly labeled, but the file is a ~330-line monolith with no bundle/reference files; content that could be split out (backfill/MCP details, full status reference) is inline, so it does not meet the "appropriately split, one-level-deep references" anchor for 3.	2 / 3
	Total	11 / 12 Passed

Description

72%Weight 40%Scale 1-3

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, distinctive description that names concrete capabilities, but it lacks an explicit "Use when..." trigger clause and slips into second-person voice ("your database"). Adding a trigger clause and rephrasing in third person would raise the score.

Suggestions

Append a "Use when..." clause, e.g. "Use when syncing Paddle subscription/customer state into your DB, gating features by subscription status, or rendering billing/account pages without Paddle API round-trips."

Rephrase in third person to avoid the second-person "your database", e.g. "Mirrors Paddle subscription and customer state into a local database via webhooks...".

Dimension	Reasoning	Score
Specificity	Lists several concrete capabilities ("schema, upsert pattern, status semantics, scheduled changes, and access gating"), but the imperative "Mirror ... into your database" uses second-person voice ("your database"), which per the rubric reduces specificity by one level from 3.	2 / 3
Completeness	It clearly states what the skill does but omits any "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 2 per the rubric.	2 / 3
Trigger Term Quality	Natural terms a user would say are well covered — "Paddle subscription", "customer state", "webhooks", "database", "access gating" — giving good coverage of likely phrasings.	3 / 3
Distinctiveness Conflict Risk	The Paddle-specific subscription-mirroring niche is clearly carved out and unlikely to trigger for unrelated skills.	3 / 3
	Total	10 / 12 Passed

Validation

93%

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

Validation for skill structure

Criteria	Description	Result
referenced_paths_exist	Referenced path issues: 1 missing	Warning

	Total	15 / 16 Passed

Repository: PaddleHQ/paddle-agent-skills
Path: skills/subscription-sync/SKILL.md
Commit: cbd404f

Reviewed: 3 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.