PayKit skill for AI agents

What this is. A single Markdown file that teaches an AI coding agent what PayKit is and how it works: the catalog model (features, plans, immutable plan versions, add-ons), how entitlements resolve, the subscribe, checkout, webhook and gate loop, and the rules every integration must follow. Install it once and your agent stops guessing.

The file: /skills/paykit/SKILL.md

It follows the open Agent Skills format (a SKILL.md with name and description frontmatter), so any agent that supports skills picks it up automatically when you work on billing, plans, add-ons or feature gating. Agents without skill support can simply read the same URL.

Install

Claude Code, for every project on your machine:

mkdir -p ~/.claude/skills/paykit
curl -fsSL /skills/paykit/SKILL.md -o ~/.claude/skills/paykit/SKILL.md

Claude Code, for one repository only (commit it so your whole team gets it):

mkdir -p .claude/skills/paykit
curl -fsSL /skills/paykit/SKILL.md -o .claude/skills/paykit/SKILL.md

Other agents that read skills (Codex, Gemini CLI, Copilot CLI and others that scan ~/.agents/skills):

mkdir -p ~/.agents/skills/paykit
curl -fsSL /skills/paykit/SKILL.md -o ~/.agents/skills/paykit/SKILL.md

Any other agent: paste this into its instructions or your project's AGENTS.md:

Before working on PayKit billing, read /skills/paykit/SKILL.md

Restart your agent session after installing so it sees the new skill.

Keeping it current

The skill carries a version, and it tells your agent when to look for a newer one: when the API answers with something the skill does not describe, when you ask about a capability it does not cover, or when the installed copy is more than 30 days old. If the live version differs, the agent downloads it over the installed file and carries on with the new one.

To update by hand at any time, re-run the same curl command; the file is replaced in place. The full API reference stays the authority on exact request and response shapes, and the skill links to it.

What the skill covers

• The object model: client, project (test or live), catalog, customers, subscriptions and add-on grants.
• Features and their kinds, and which kind does what.
• Plans and immutable plan versions: pricing, trials, annual discounts, custom pricing, dunning rules, and why existing subscribers keep their version.
• Add-ons: what a version grants, how long it lasts, how it is paid, the rules that bind those together, and recipes for common products.
• How entitlements merge across subscriptions and add-on grants.
• The integration loop, webhooks, idempotency and money handling.
• Which actions an API key can take and which stay in the dashboard.
• A ready-to-import catalog file, and the mistakes integrations most often make.

Ask your agent

Once installed, try prompts like these:

• "Design a PayKit catalog for a three-tier SaaS with a free plan and a seat-pack add-on, as an import file."
• "Add PayKit subscriptions to this app: create the customer on sign-up, start checkout, and handle the activation webhook."
• "Gate the export feature on the customer's PayKit entitlements."