Content
71%Weight 40%Scale 1-5Reviews 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.
| Dimension | Reasoning | Score |
|---|---|---|
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 |