---
name: author-agent-skills
description: Turn Paddle's public builder skills into your platform's own agent skills — wrap Paddle access behind your helpers/gateway, centralize environment handling, use the seller's credentials, and provision from webhooks — so your agent builds seller integrations consistently.
metadata:
  internal: true
---

# Author agent skills from Paddle's builder skills

## When to use this skill

Use this skill when building the **agent layer** — the part of an embedded integration your agent scaffolds inside each seller's app (catalog, checkout, webhooks, subscription management). You don't hand-build this per seller, and you don't need Paddle to write bespoke skills for you. Instead, start from Paddle's public builder skills and adapt them to your platform, so your agent builds against your backend the same way every time. In practice, building the agent layer is largely a matter of authoring these skills well.

This is a meta-skill: it's about producing skills, not calling an API.

## 1. Start from Paddle's builder skills

Paddle publishes a set of framework-generic builder skills for a normal Paddle integration — [`paddle-checkout-web`, `paddle-webhooks`, `paddle-catalog-setup`, `paddle-subscription-sync`, `paddle-subscription-cancel`, `paddle-subscription-update`, `paddle-customer-portal`, `paddle-pricing-pages`, `paddle-billing-history`, `paddle-sandbox-testing`](/sdks/ai/agent-skills). They're the correct Paddle mechanics, but written for a generic stack (for example, a Next.js app with raw price IDs). Use them as the raw material — copy each one and adapt it.

## 2. Wrap Paddle access in your platform's helpers

The adaptation is mostly about replacing generic, hand-rolled Paddle calls with calls to _your_ platform's helpers, proxies, and business logic. The patterns that make agent-built integrations reliable:

- **Route API calls through one client/gateway.** Give the agent a single helper (for example `getPaddleClient(env)`) that injects credentials and routes through your proxy, instead of letting it construct raw authenticated requests. Keys stay server-side, and you can change routing in one place.
- **Centralize environment handling.** Define one environment type and derive sandbox vs. live from the client-token prefix rather than scattering checks. Map the environment to the seller's stored per-environment keys.
- **Provide dedicated tools that enforce invariants.** For example a `create_product` / `create_price` helper that always sets your `external_id` and creates in the right environment — so the agent can't forget the invariant that keeps catalog synced across environments.
- **Use the seller's credentials for in-app work.** In-app calls use the seller's `api_key` and client-side token — never your partner key.
- **Keep provisioning in webhooks.** Grant access from `subscription.created` / `subscription.updated`, not the checkout redirect. Webhooks are the signed, retried source of truth.
- **Reference stable `external_id`s.** Store `external_id` and resolve to environment-specific `pri_` / `pro_` IDs at runtime — never hardcode a `pri_...` in app code, since it differs between sandbox and live.

## 3. Rewrite each skill for your platform

For each builder skill: keep Paddle's structure, pitfalls, and verification steps, then replace the generic code with calls to your helpers, and name your helper functions, file paths, and environment variables explicitly so the agent uses them every time. Add your platform-specific pieces (a test-mode banner, your proxy URL, your provisioning table). Encode your business logic here — this is what stops builds from drifting seller to seller.

### Before and after: opening checkout

Paddle's generic builder skill opens checkout with a raw, environment-specific price ID:

```ts
// Generic — from paddle-checkout-web
initializePaddle({
  token: process.env.NEXT_PUBLIC_PADDLE_CLIENT_TOKEN,
  environment: "sandbox",
}).then((paddle) =>
  paddle.Checkout.open({ items: [{ priceId: "pri_01h...", quantity: 1 }] }),
);
```

Your adapted skill points the agent at your helpers instead — env is derived, the price is resolved from a stable `external_id`, and credentials come from the seller's stored token:

```ts
// Adapted — uses YOUR platform's helpers
import { initPaddle, resolvePriceId } from "@yourplatform/paddle";

const paddle = await initPaddle(); // reads the seller's client token, derives the environment
const priceId = await resolvePriceId("pro_monthly"); // your external_id -> pri_ resolver, per environment
paddle.Checkout.open({ items: [{ priceId, quantity: 1 }] });
```

Server-side, the same idea applies: catalog writes and reads go through `getPaddleClient(env)`, which injects the seller's key and your proxy — the agent never handles a raw key.

## Common pitfalls

- **Leaking a key into agent-written code.** Keep credentials behind a helper/gateway; never let the agent embed a partner or seller key client-side.
- **Hardcoding `pri_` / `pro_` IDs.** They differ per environment — resolve from `external_id` at runtime.
- **Provisioning from the checkout redirect.** Users close tabs and block redirects; provision from webhooks.
- **Copying builder skills unchanged.** Without your helpers and business logic, the agent reinvents plumbing and builds drift between sellers.

## Verify

- Point your agent at an adapted skill in a sample seller app and confirm it scaffolds a working integration against your backend — using your helpers, with no raw keys in client code.
- The same prompt produces the same integration shape across sellers.
- Test the result in sandbox before go-live (Paddle's `paddle-sandbox-testing` skill).

## Related docs

- [How an embedded billing integration works](/partners/embed-billing/get-started) (the agent layer)
- [Integrate with AI](/partners/embed-billing/get-started/integrate-with-ai)
- [Agent skills and plugins](/sdks/ai/agent-skills) — the builder skills to adapt
- [`integrate-partner-platform`](/partners/embed-billing/get-started/integrate-with-ai)