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.

1.35x

Quality

72%

Does it follow best practices?

Impact

96%

1.35x

Average score across 3 eval scenarios

Securityby

Medium

Suggest reviewing before use

Fix and improve this skill with Tessl

tessl review fix ./skills/subscription-update/SKILL.md

Quality

Content

77%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 strong, action-first skill with executable code and excellent validation checkpoints in both the implementation and verification sections. The main weakness is length for a single file — it would benefit from splitting dense reference material (proration tables, pitfalls) into bundle files.

Suggestions

Move the proration mode and payment-failure tables plus the Common pitfalls list into a `references/` file, keeping SKILL.md a lean overview that points to it.

Tighten the prose around each table — the tables already convey the when-to-use guidance, so the surrounding explanation can be cut.

Add explicit one-level-deep reference links (e.g. "See PRORATION.md for the full mode table") once bundle files exist.

Dimension	Reasoning	Score
Conciseness	Mostly efficient and tightly written, but the body is long with some restate-and-justify prose (e.g. repeated explanations of why each proration mode is right and a large Common pitfalls list that re-explains points already covered by the tables).	2 / 3
Actionability	Provides fully executable TypeScript Server Action code, copy-paste-ready `previewUpdate`/`update` snippets, exact env vars, and concrete verification commands with a test-card link.	3 / 3
Workflow Clarity	The Server Action is a clearly numbered 5-step sequence with explicit auth + ownership validation checkpoints before the SDK call, plus a dedicated "Verify the integration" checklist with error-path validation (declining card, forged subscriptionId).	3 / 3
Progressive Disclosure	Well-organized with clear sections, but it is a single monolithic SKILL.md with no bundle files and no one-level-deep references to split out the lengthy API detail; the tables and pitfalls could live in reference files.	2 / 3
	Total	10 / 12 Passed

Description

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

Highly specific and distinct description that names concrete operations and disambiguates from related skills. The main gap is the absence of an explicit "Use when..." trigger clause and a reliance on SDK terminology over natural user phrasing.

Suggestions

Add an explicit "Use when..." trigger clause (e.g. "Use when the user asks to upgrade, switch, or change a subscription's plan or billing term in a Paddle + Next.js app").

Lead with natural user-facing phrasing ("upgrade plan," "change tier," "switch billing term") before the SDK field names so the description matches what a user would actually say.

Trim the dense list of SDK field names into the trigger clause and reserve the API detail for the body.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions: "auth, ownership check, `prorationBillingMode`, items-array replace semantics, preview-before-commit, and `on_payment_failure` handling" — specific and substantive.	3 / 3
Completeness	The "what" is clear (change a Paddle subscription's plan), but there is no explicit "Use when..." trigger clause — the when is only implied by the action names, so completeness caps at 2 per the guideline.	2 / 3
Trigger Term Quality	Includes some natural terms ("Upgrade plan," "Switch tier," "Change subscription") but the field is dominated by technical SDK jargon like `prorationBillingMode` and `on_payment_failure` rather than language a user would say.	2 / 3
Distinctiveness Conflict Risk	Scopes tightly to Paddle subscription plan-change from a Next.js Server Action and explicitly distinguishes itself from sibling `subscription-sync` and `subscription-cancel` skills, making false-trigger risk low.	3 / 3
	Total	10 / 12 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: PaddleHQ/paddle-agent-skills
Path: skills/subscription-update/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.