What's new?
We've released Paddle agent skills, a set of drop-in instructions that teach AI coding agents how to integrate Paddle. Each skill covers a specific workflow, so your agent knows exactly what to do when you ask it to build a Paddle feature.
We've also released an official Claude Code plugin that installs every skill in one command and wires up the Paddle docs MCP server at the same time.
Skills make agents more accurate, not infallible. Always review the code an agent writes before merging or deploying it, especially around authentication, webhook secrets, and access gating.
How it works
Skills are short, framework-specific patterns written for agents rather than humans. They include verification instructions, best practices, and links to the relevant docs and MCP tool calls. Agents load them on demand when a skill's description matches the task you're working on.
Skills sit alongside our Paddle MCP servers and play a distinct role:
- Agent skills tell agents how to build for Paddle, including the patterns and conventions to follow when writing integration code.
- The Paddle docs MCP server gives agents up-to-date knowledge of Paddle, useful for troubleshooting and planning.
- The Paddle MCP server lets agents take actions in your Paddle account, like creating products and prices, minting client-side tokens, and simulating webhooks.
Available skills
Ten skills are available at launch, covering the most common Paddle workflows:
| Skill | What it covers |
|---|---|
paddle-billing-history | Render the authenticated user's billing history in Next.js — listing transactions via the Paddle Node SDK, the mandatory customer-id filter, pagination via `.next()`/`.hasMore`, status filtering, and formatting raw transaction totals (lowest-unit conversion + Intl.NumberFormat, with the zero-decimal currency special case for JPY/KRW/CLP). |
paddle-catalog-setup | Create the Paddle products and prices that other Paddle skills depend on — try MCP tools first, fall back to a Node SDK seed script, or dictate dashboard steps as a last resort. |
paddle-checkout-web | Add a Paddle Checkout to a Next.js web app — overlay or inline, with event handling, customer pre-fill, and dynamic line item updates. |
paddle-customer-portal | Mint a Paddle customer portal session URL from a Next.js Server Action — the portal-vs-custom-billing-screen trade-off, auth, ownership, URL structure (overview vs deep links), and the security model. |
paddle-pricing-pages | Render country-localized prices on a Next.js pricing page using Paddle.js PricePreview — country detection, billing frequency toggle, and currency formatting. |
paddle-sandbox-testing | Test a Paddle integration end-to-end using the sandbox environment, test cards, the webhook simulator, and local tunnels — without taking real money. |
paddle-subscription-cancel | Cancel a Paddle subscription from a Next.js Server Action — auth, ownership check, safe `effectiveFrom` default, revalidation, and the `canceled` vs `scheduledChange` distinction. |
paddle-subscription-sync | Mirror Paddle subscription and customer state into your database via webhooks — schema, upsert pattern, status semantics, scheduled changes, and access gating. |
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. |
paddle-webhooks | Receive and verify Paddle webhooks in a Next.js Route Handler — signature verification, idempotency, retry semantics, and local testing. |
How skills compare
Alongside skills, we've published data on how we evaluated skills against LLMs in our LLM benchmark. It's a real-world test of how well LLMs build with Paddle, and shows how skills and MCP help models do better.
Across the board, we saw that skills lift model performance an average of 13% across all models we tested. They unblock tasks that even large, frontier models couldn't do without help, and significantly improved smaller models' performance.
Shoutout to the Clerk.com team for the inspiration for this page.
Install using the skills CLI
For Cursor, Windsurf, and other agent tools that support the agent skills discovery RFC, you can install the skills via the skills CLI:
pnpm dlx skills add https://developer.paddle.com/yarn dlx skills add https://developer.paddle.com/npx skills add https://developer.paddle.com/Install in Claude Code
For Claude Code, the fastest way to install all the skills is via the official Paddle plugin:
/plugin marketplace add PaddleHQ/paddle-agent-skills/plugin install paddle@paddle-agent-skillsThe plugin installs every skill and configures the Paddle MCP servers in one step. To update later, run /plugin marketplace update paddle-agent-skills.
Next steps
Agent skills and the Claude Code plugin are available now. See agent skills for the full skill list and installation options, or build with Claude Code for an end-to-end walkthrough of setting up Claude Code with Paddle.