> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# 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.

---

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.

{% callout type="warning" title="AI agents can make mistakes" %}
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.
{% /callout %}

## 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

{% skills-list /%}

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](https://developer.paddle.com/sdks/ai/docs-mcp.md) and the [Paddle MCP server](https://developer.paddle.com/sdks/ai/paddle-mcp.md).

{% card-group %}
{% card title="Claude Code" icon="claude" url="/get-started/ai/claude-code" /%}
{% card title="Codex" icon="openai" url="/get-started/ai/codex" /%}
{% card title="Gemini CLI" icon="gemini" url="/get-started/ai/gemini-cli" /%}
{%/card-group %}

#### Connect the Paddle MCP servers

When using plugins, you need to set the API keys for the environments you use. [Create API keys](https://developer.paddle.com/api-reference/about/authentication.md) at **Paddle > Developer tools > Authentication**, then export them in your shell profile:

```sh
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](https://github.com/cloudflare/agent-skills-discovery-rfc), use the skills CLI:

{% code-group sync="js-package-manager" %}

```bash {% title="pnpm" %}
pnpm dlx skills add https://developer.paddle.com/
```

```bash {% title="yarn" %}
yarn dlx skills add https://developer.paddle.com/
```

```bash {% title="npm" %}
npx skills add https://developer.paddle.com/
```

{% /code-group %}

### Manual installation

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

```bash
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:

```bash
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`](https://github.com/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](https://github.com/PaddleHQ/paddle-agent-skills)

## 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](https://github.com/cloudflare/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
```