{
  "markdown": "# Paddle agent skills\n\n[Paddle Billing](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills) is the developer-first merchant of record, designed for modern SaaS, AI, mobile app, and digital product businesses. We take care of payments, tax, subscriptions, and metrics with one unified API that does it all.\n\nThis repo contains a collection of agent skills that help you implement Paddle in your product. Load them into Claude Code, Codex, Cursor, Gemini CLI, or any agentic coding tool that supports the skills format and your assistant gains step-by-step guidance for the most common Paddle integration tasks.\n\n> **Important:** These skills are written for Paddle Billing. They don't cover Paddle Classic. If you're working with Paddle Classic, see the [Paddle Classic dev docs](https://classic.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills).\n\n## What's included\n\nTen skills covering the most common Paddle integration tasks:\n\n- **[`paddle-billing-history`](skills/billing-history/SKILL.md)** — show authenticated customers their past Paddle transactions with invoice download links.\n- **[`paddle-catalog-setup`](skills/catalog-setup/SKILL.md)** — create the Paddle products and prices that other skills depend on.\n- **[`paddle-checkout-web`](skills/checkout-web/SKILL.md)** — add a Paddle Checkout (overlay or inline) to a Next.js app, with event handling and customer pre-fill.\n- **[`paddle-customer-portal`](skills/customer-portal/SKILL.md)** — mint authenticated customer portal sessions so users can self-serve subscriptions, payment methods, and invoices.\n- **[`paddle-pricing-pages`](skills/pricing-pages/SKILL.md)** — render country-localized prices using `Paddle.PricePreview()`, with billing frequency toggle and currency formatting.\n- **[`paddle-sandbox-testing`](skills/sandbox-testing/SKILL.md)** — exercise the integration end-to-end in the Paddle sandbox: test cards, webhook simulator, local tunnels.\n- **[`paddle-subscription-cancel`](skills/subscription-cancel/SKILL.md)** — build a \"cancel at end of period\" flow with the right ownership checks and webhook reconciliation.\n- **[`paddle-subscription-sync`](skills/subscription-sync/SKILL.md)** — mirror Paddle subscription and customer state into your database via webhooks.\n- **[`paddle-subscription-update`](skills/subscription-update/SKILL.md)** — upgrade, downgrade, or change subscription items via the API with proration handling.\n- **[`paddle-webhooks`](skills/webhooks/SKILL.md)** — receive and verify Paddle webhooks in a Next.js Route Handler, with idempotency and retry handling.\n\nEach skill lives in its own directory under [`skills/`](skills) and ships with a `SKILL.md` containing the skill's frontmatter and instructions. The same skills are mirrored into each provider's plugin folder under [`providers/`](providers) by [`scripts/sync-skills.mjs`](scripts/sync-skills.mjs) — see [CONTRIBUTING.md](CONTRIBUTING.md) for the layout.\n\n## Install as a Claude Code plugin\n\nInside [Claude Code](https://claude.com/claude-code), run:\n\n```text\n/plugin marketplace add PaddleHQ/paddle-agent-skills\n/plugin install paddle@paddle-agent-skills\n```\n\nThen ask Claude something Paddle-shaped, like \"help me verify a Paddle webhook in Next.js,\" and the relevant skill is selected automatically.\n\nWhen you enable the plugin, Claude Code prompts for your Paddle sandbox API key and stores it securely in your keychain — no shell environment variables needed. The live MCP server authorizes with OAuth in your browser, so it needs no key. (Requires Claude Code v2.1.207 or later.)\n\nTo update later, run `/plugin marketplace update paddle-agent-skills`.\n\n## Install as a Codex plugin\n\nFrom your terminal, run:\n\n```sh\ncodex plugin marketplace add PaddleHQ/paddle-agent-skills\n```\n\nThen install the `paddle` plugin from the Codex plugin directory.\n\n## Install as a Cursor plugin\n\nCursor doesn't have a `/plugin install` style command yet, so install via the skills CLI (which adds skill files to your project) and the Cursor MCP deeplinks (which wire up the Paddle MCP servers).\n\n```sh\npnpm dlx skills add https://developer.paddle.com/\n```\n\nSee the [Cursor setup guide](https://developer.paddle.com/get-started/ai/cursor) for the MCP deeplinks and a Paddle rules file.\n\n## Install as a Gemini CLI extension\n\nFrom your terminal, run:\n\n```sh\ngemini extensions install PaddleHQ/paddle-agent-skills\n```\n\nGemini auto-discovers the bundled [`skills/`](skills) directory at the extension root and wires up the docs and Paddle MCP servers via [`gemini-extension.json`](gemini-extension.json). Export `PADDLE_SANDBOX_API_KEY` for the sandbox server (see [Connect the Paddle MCP servers](#connect-the-paddle-mcp-servers)); the live server authorizes with OAuth.\n\n## Connect the Paddle MCP servers\n\nAll of the plugins wire up the same three MCP servers. How you authenticate depends on the environment:\n\n| MCP server       | URL                                  | Authentication                    |\n| ---------------- | ------------------------------------ | --------------------------------- |\n| `paddle-docs`    | `https://paddlehq.mcp.kapa.ai`       | Google or GitHub sign-in          |\n| `paddle-sandbox` | `https://sandbox-mcp.paddle.com/mcp` | Sandbox API key                   |\n| `paddle-live`    | `https://mcp.paddle.com/mcp`         | OAuth (authorize in your browser) |\n\nYou only need the environments you use. The skills default to sandbox unless you've explicitly opted into live, so the sandbox key is the one to set up first.\n\n`paddle-docs` is hosted by [Kapa.ai](https://kapa.ai) and needs no Paddle credentials. It does ask you to sign in with Google or GitHub the first time you connect, which Kapa uses only for per-user rate limiting and abuse prevention — it requests the `openid` scope from Google and no scopes at all from GitHub.\n\n### Sandbox: set an API key\n\n`paddle-sandbox` authenticates with a sandbox API key. Generate one at **Paddle > Developer tools > Authentication** in the [sandbox dashboard](https://sandbox-vendors.paddle.com/authentication-v2) (keys are prefixed `pdl_sdbx_`), granting the permissions you want the agent to use.\n\nHow you supply it depends on the tool:\n\n- **Claude Code** — prompts you for the key when you enable the plugin and stores it in your OS keychain. No shell setup. (See [Install as a Claude Code plugin](#install-as-a-claude-code-plugin).)\n- **Codex** and **Gemini CLI** — read the key from the process environment of whatever launches your editor. Set it in your shell profile:\n\n  ```sh\n  export PADDLE_SANDBOX_API_KEY=pdl_sdbx_...\n  ```\n\n  Restart your editor afterwards so the MCP server picks it up.\n\n- **Cursor** — you paste the key into the install deeplink. (See the [Cursor setup guide](https://developer.paddle.com/get-started/ai/cursor).)\n\nSee [`.env.example`](./.env.example) for the full list of variables and inline guidance.\n\n### Live: authorize with OAuth\n\n`paddle-live` authorizes with OAuth, so there's no key to create or store. The first time your agent uses the server, your client opens a browser window to sign in to Paddle and approve access. Depending on the client you may need to trigger this manually — Claude Code and Gemini CLI use `/mcp`, Codex uses `codex mcp login paddle-live`.\n\nAn OAuth connection starts with **read** access to what your Paddle user's role permits. To let the agent make changes in live, grant write permissions under **Paddle > Connectors > MCP**, where you can also review or revoke connections.\n\nIf a browser sign-in isn't practical (an automated environment, for example), `paddle-live` also accepts a live API key as a Bearer token. See the [Paddle MCP server docs](https://developer.paddle.com/sdks/ai/paddle-mcp) for that configuration.\n\n### Picking the right MCP at runtime\n\nWith both servers connected, the agent sees two parallel toolsets. Be explicit in your prompts about which environment you mean. For example, \"create a product in sandbox\" routes to `paddle-sandbox`; \"create the equivalent product in live\" routes to `paddle-live`. Sandbox keys only authenticate against the sandbox URL, so a mismatch surfaces as an auth failure.\n\n## Use the skills outside a plugin\n\nSkills also work in any agentic tool that supports the agent-skills format. Use the [`skills` CLI](https://github.com/vercel-labs/agent-skills) to add them to your project:\n\n```sh\npnpm dlx skills add https://developer.paddle.com/\n```\n\nYou can also add skills manually by copying the contents of a skill's directory into your project's `.agent/skills/` directory, or a global `~/.agent/skills/` directory to share across projects.\n\n## Contributing\n\nFound a bug or want to suggest an improvement? See [CONTRIBUTING.md](CONTRIBUTING.md) and open an issue.\n\n## Get help\n\nFor help with your Paddle integration, contact our support team at [sellers@paddle.com](mailto:sellers@paddle.com).\n\nFor feedback about Paddle's developer experience or these skills specifically, contact the Paddle DX team at [team-dx@paddle.com](mailto:team-dx@paddle.com).\n\n## Learn more\n\n- [Paddle developer docs](https://developer.paddle.com/?utm_source=dx&utm_medium=paddle-agent-skills)\n- [Paddle agent skills](https://developer.paddle.com/sdks/ai/agent-skills?utm_source=dx&utm_medium=paddle-agent-skills)\n- [Paddle docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp?utm_source=dx&utm_medium=paddle-agent-skills)\n- [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp?utm_source=dx&utm_medium=paddle-agent-skills)\n- [Sign up for Paddle Billing](https://login.paddle.com/signup?utm_source=dx&utm_medium=paddle-agent-skills)\n",
  "bytes": 9613,
  "sha": "eb32d41cf5b76d37f4295a28e3cf282edb2f79394827e3c39d6f1e3dcd14d194",
  "repo_slug": "paddlehq/paddle-agent-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_paddlehq_paddle_agent_skills_635566bd/readme"
}