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.
86
80%
Does it follow best practices?
Impact
96%
1.35xAverage score across 3 eval scenarios
Advisory
Suggest reviewing before use
Optimize this skill with Tessl
npx tessl skill review --optimize ./skills/subscription-update/SKILL.mdQuality
Discovery
82%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a highly specific and technically detailed description that clearly identifies a narrow domain (Paddle subscription plan changes via Next.js Server Actions). Its main weakness is the lack of an explicit 'Use when...' clause, which would help Claude know exactly when to select this skill. The specificity and distinctiveness are excellent, making it easy to distinguish from other skills.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user needs to change, upgrade, or downgrade a Paddle subscription plan in a Next.js application.'
Consider adding common user-facing synonyms like 'upgrade', 'downgrade', 'switch plan', or 'billing change' to improve trigger term coverage for less technical phrasings.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: changing a Paddle subscription plan, auth, ownership check, proration billing mode, items-array replace semantics, preview-before-commit, and on_payment_failure handling. These are highly specific technical capabilities. | 3 / 3 |
Completeness | The 'what' is well-covered with specific actions and technical details, but there is no explicit 'Use when...' clause or equivalent trigger guidance. The when is only implied by the description of capabilities. Per rubric guidelines, missing 'Use when...' caps completeness at 2. | 2 / 3 |
Trigger Term Quality | Includes strong natural keywords a developer would use: 'Paddle', 'subscription', 'plan', 'Next.js Server Action', 'proration', 'on_payment_failure', 'preview-before-commit'. These are terms a user would naturally mention when needing this specific functionality. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — the combination of Paddle, subscription plan changes, Next.js Server Actions, and specific implementation details like prorationBillingMode and items-array replace semantics creates a very clear niche that is unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong, highly actionable skill with excellent workflow clarity and a thorough verification checklist. Its main weakness is verbosity — some sections repeat earlier guidance (e.g., pitfalls restating table content), and the skill could benefit from splitting detailed reference material into separate files. The proration mode tables and executable code examples are standout strengths.
Suggestions
Trim the 'Common pitfalls' section by removing items that directly restate guidance already covered in earlier sections (e.g., proration mode selection, items replacement semantics) — keep only the non-obvious traps.
Consider extracting the proration mode tables and payment failure handling into a separate reference file to reduce the main skill's token footprint and improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is thorough and mostly earns its length given the complexity of proration modes and edge cases, but several sections are verbose — e.g., the 'When to use this skill' intro paragraph, the lengthy 'Common pitfalls' section repeats guidance already covered in earlier sections, and some explanations (like what happens on payment failure) could be tightened. The tables are efficient, but surrounding prose could be leaner. | 2 / 3 |
Actionability | The skill provides a complete, copy-paste-ready Server Action with auth, ownership check, and SDK call. The preview code snippet is executable, the proration mode tables give concrete guidance for each scenario, and the items-replacement semantics are demonstrated with clear before/after code examples. | 3 / 3 |
Workflow Clarity | The skill presents a clear multi-step workflow: authenticate → verify ownership → (optionally) preview → update → revalidate → return slim DTO. The 'Verify the integration' section provides an 8-step validation checklist covering happy path, payment failure, invalid inputs, and auth bypass — explicit feedback loops for error recovery are present throughout. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headings and logical section ordering, and it references related skills (subscription-sync, subscription-cancel) and external Paddle docs. However, with no bundle files, the entire ~300-line skill is monolithic — the proration mode tables, common pitfalls, and payment failure handling could reasonably be split into referenced files for a skill this long. | 2 / 3 |
Total | 10 / 12 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 — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
- Repository
- PaddleHQ/paddle-agent-skills
- Commit
86596b3
- 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.