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 in Next.js). 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 distinctive terminology are excellent strengths.
Suggestions
Add an explicit 'Use when...' clause, e.g., 'Use when the user needs to change, upgrade, or downgrade a Paddle subscription plan from a Next.js Server Action.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: changing a 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 very well covered with specific actions and technical details. However, there is no explicit 'Use when...' clause or equivalent trigger guidance, which per the rubric 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 developers would naturally search for when dealing with this exact scenario. | 3 / 3 |
Distinctiveness Conflict Risk | Extremely specific niche: Paddle subscription plan changes via Next.js Server Actions. The combination of Paddle + subscription + Next.js Server Action + specific implementation details like prorationBillingMode makes this highly 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 — while the content is accurate and useful, it could be 30-40% shorter by trimming repeated guidance (e.g., pitfalls that restate earlier sections) and trusting Claude to infer context. The inline-only structure is acceptable but would benefit from splitting reference material into separate files for a skill of this length.
Suggestions
Trim the 'Common pitfalls' section by removing items that directly restate guidance already covered in earlier sections (e.g., replace semantics, proration mode selection, ownership checks) — a brief cross-reference is sufficient.
Consider extracting the proration mode tables and payment failure details 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 real SDK calls, concrete preview code, explicit parameter values, and specific examples of items-array replace semantics. The code is executable TypeScript with clear comments explaining each step. | 3 / 3 |
Workflow Clarity | The skill clearly sequences the workflow: auth → ownership check → (optional) 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. The preview-before-commit pattern is an explicit validation checkpoint for non-trivial changes, and the payment failure section covers error recovery paths. | 3 / 3 |
Progressive Disclosure | The content is well-structured with clear headers and logical sections, and references related skills (subscription-sync, subscription-cancel) and external Paddle docs. However, with no bundle files, all content is inline in a single long document (~250+ lines). The proration mode tables, common pitfalls, and verification steps could benefit from being split into referenced files, especially given the document's length. | 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
62438cd
- 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.