CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

paddle-subscription-update

Change a Paddle subscription's plan from a Next.js Server Action — auth, ownership check, `prorationBillingMode`, items-array replace semantics, preview-before-commit, and `on_payment_failure` handling.

80

1.14x
Quality

85%

Does it follow best practices?

Impact

100%

1.14x

2 of 3 eval scenarios. Add 1 more for a full score.

SecuritybySnyk

Medium

Suggest reviewing before use

The canonical home for this skill is paddle-subscription-update 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 excellent, deeply knowledgeable skill body: executable code, explicit decision tables, error-code handling, and a thorough verification checklist. Its only weaknesses are mild repetition, inlined boilerplate helpers, and a lack of any reference-file split for the long single-file body.

Suggestions

Move the Supabase helper code and environment-variable setup into a reference file (e.g. references/helpers.md) and keep a one-line pointer in SKILL.md.

Consolidate the trialing/`do_not_bill` rule, currently restated in the proration table, flow table, status table, code comments, and pitfalls, into one authoritative section.

Trim the "What the user sees vs what gets billed" narrative, which overlaps with the webhook side already delegated to `subscription-sync`.

DimensionReasoningScore

Conciseness

The body is dense with non-obvious Paddle-specific knowledge (status rules, error codes, renewal lock, credit-not-refund semantics) and assumes competence, but the ~50 lines of Supabase helper boilerplate and repeated restatements of the trialing/`do_not_bill` rule (4+ places) are minor over-explanation that could be trimmed.

4 / 5

Actionability

Fully executable, copy-paste-ready guidance: a complete Server Action with auth and ownership checks, a previewUpdate snippet with field-by-field comments, an onPaymentFailure override example, named API error codes mapped to UI messages, and a 9-step verification checklist covering the common cases.

5 / 5

Workflow Clarity

The sequence is explicit — choose proration mode, check subscription status, preview before committing, execute with auth/ownership validation, verify via dashboard/webhook — with an explicit verification section, error-code feedback loops, and expected outcomes at each checkpoint for this billing operation.

5 / 5

Progressive Disclosure

Well-organized single file with clear section headers and no nested references, but everything is inlined (Supabase helper code, related-docs lists) in a ~330-line body where splitting the helper/environment boilerplate into a reference file would improve the overview-to-detail structure.

4 / 5

Total

18

/

20

Passed

Description

75%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 highly specific, well-scoped description that clearly states what the skill does with concrete technical actions, but it lacks any explicit "Use when..." trigger clause and omits natural user phrasings like "upgrade plan" or "switch tier" that would improve discoverability.

Suggestions

Add an explicit trigger clause, e.g. "Use when building 'Upgrade plan', 'Switch tier', or 'Change subscription' actions in a Next.js billing UI."

Include natural synonyms users would say — "upgrade", "downgrade", "switch plan/tier" — alongside the technical parameter names.

State the third-person verb form consistently and keep the enumerated action list as the "what" portion.

DimensionReasoningScore

Specificity

The description enumerates multiple concrete actions — "auth, ownership check, `prorationBillingMode`, items-array replace semantics, preview-before-commit, and `on_payment_failure` handling" — comprehensively covering the pipeline for this domain, matching the comprehensive-coverage anchor rather than the minor-gaps anchor below.

5 / 5

Completeness

The "what" is clear and concrete, but there is no "Use when..." clause or equivalent explicit trigger guidance, which caps completeness at 3 per the judging guidelines; the "when" is only weakly implied by the action described.

3 / 5

Trigger Term Quality

Natural terms like "Change a Paddle subscription's plan" and "Next.js Server Action" are present, but common user phrasings such as "upgrade plan", "switch tier", or "downgrade" are missing from the description (they only appear in the body), so coverage is good but not comprehensive.

4 / 5

Distinctiveness Conflict Risk

"Paddle subscription's plan" combined with "Next.js Server Action" carves out a clear niche with distinct triggers, minimal overlap with related subscription skills (cancel, sync); it would not fire for the wrong skill.

5 / 5

Total

17

/

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-update/SKILL.md

Revision

70cb70d

Reviewed

Table of Contents

DiscoveryImplementationValidation

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.

Claim skill