For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL.

Skip to content
Docs

Agent skills and plugins

Drop-in instructions that teach AI coding agents how to integrate Paddle, including catalog setup, checkout, webhooks, subscription sync, pricing pages, and sandbox testing.

AI summary

Agent skills are drop-in instruction files that teach AI coding agents how to integrate specific Paddle workflows — covering catalog setup, checkout, webhooks, subscription sync, pricing pages, and sandbox testing.

  • • Install all six skills at once with pnpm dlx skills add @PaddleHQ/paddle-agent-skills, which drops them into .agents/skills/ where agents load them on demand when their description matches the task.
  • • Skills complement the docs MCP server (Paddle knowledge) and Paddle MCP server (actions) — each has a different role and all three work best together.
  • • Skills are updated periodically as Paddle evolves — re-fetch from the discovery index URL or GitHub to keep your local copies current.

Agent skills are a standardized way to give AI agents instructions on how to integrate Paddle. They give your agent specialized knowledge and instructions for specific Paddle workflows, helping it to build integrations faster and more accurately.

How it works

Skills tell an agent how to use Paddle in code, with framework-specific patterns, verification instructions, and best practices. They're written specifically for agents, rather than humans.

They complement the docs MCP server, which gives agents knowledge of Paddle, and the Paddle MCP server, which lets agents take actions in Paddle. Skills are deliberately short and focused, so agents know exactly what to do. They include links to the relevant docs and MCP tool calls.

Agents automatically load skills on demand when their description matches the task they're working on.

Available skills

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.

Each skill is self-contained, but several link to each other. For example, paddle-subscription-sync assumes you have paddle-webhooks working.

Install in your project

Agentic coding plugins

If you use Claude Code or another agentic coding plugin, the fastest way to get started is to use one of our official plugins. Plugins bundle skills with the Paddle docs MCP server and the Paddle MCP server.

Claude Code
Codex
Gemini CLI

Connect the Paddle MCP servers

When using plugins, you need to set the API keys for the environments you use. Create API keys at Paddle > Developer tools > Authentication, then export them in your shell profile:

Shell
export PADDLE_SANDBOX_API_KEY= # Your sandbox API key
export PADDLE_LIVE_API_KEY= # Your live API key

Restart your agentic coding plugin and your terminal after setting the variables so the MCP servers pick them up. The skills default to sandbox unless you've explicitly opted into live, so PADDLE_SANDBOX_API_KEY is the one to start with during development.

Skills CLI

For Cursor, Windsurf, and other agent tools that support the agent skills discovery RFC, use the skills CLI:

pnpm
pnpm dlx skills add https://developer.paddle.com/
yarn
yarn dlx skills add https://developer.paddle.com/
npm
npx skills add https://developer.paddle.com/

Manual installation

Save each skill in the .agents/skills directory. For example, to install the paddle-webhooks skill:

Shell
mkdir -p .agents/skills # if not created
curl -fsSL https://developer.paddle.com/.well-known/skills/paddle-webhooks/SKILL.md \
  -o .agents/skills/paddle-webhooks/SKILL.md

Repeat for each skill you want available. Claude Code loads skills on demand when their description matches the task you're working on.

To install all skills at once:

Shell
for slug in paddle-billing-history paddle-catalog-setup paddle-checkout-web \
            paddle-customer-portal paddle-pricing-pages paddle-sandbox-testing \
            paddle-subscription-cancel paddle-subscription-sync \
            paddle-subscription-update paddle-webhooks; do
  mkdir -p .agents/skills/$slug # if not created
  curl -fsSL https://developer.paddle.com/.well-known/skills/$slug/SKILL.md \
    -o .agents/skills/$slug/SKILL.md
done

You can also fork the @PaddleHQ/paddle-agent-skills repository and add the SKILL.md files to your agent's rules or context directory.

Fork or clone paddle-agent-skills on GitHub

Update skills

Paddle updates skills periodically as features are added or changed. Re-fetch periodically (or have your CI do it) to make sure your local copies stay current.

Discovery and verification

Paddle publishes skills using the agent skills discovery RFC. This means agents should be able to automatically discover the skills when hitting developer.paddle.com

The RFC is still in progress, so if it's not automatically detected by your agent, then ask it to fetch the index from:

text
https://developer.paddle.com/.well-known/agent-skills/index.json

Was this page helpful?