Developer docs

AI skills

Let your coding agent set up products, push config, and wire entitlements and credits for you. One Markdown file teaches Claude Code, Codex, Cursor, and any other agent that reads skills how the purpleturret CLI and @purpleturret/sdk work, and which commands it must never run without asking.

View SKILL.md · CLI and SDK reference · OpenAPI 3.1 document

What is a skill

A skill is a folder with a SKILL.md file. The front matter tells the agent when the skill applies; the body carries the instructions and reference material the agent loads only when it needs them. Claude Code, Codex, Cursor, Gemini CLI, and most other agents discover skills from a well-known directory in your project or home folder, so installing one is a file copy.

The Purpleturret skill triggers whenever a project contains purpleturret.config.ts, imports @purpleturret/sdk, runs purpleturret or pt commands, or you ask the agent to create, price, tier, or sync checkout links or credits.

Install the skill

Run one of these from the root of your project. Each downloads the same file into the directory your agent scans.

Claude Code

curl -fsSL https://purpleturret.com/skills/purpleturret/SKILL.md \
  --create-dirs -o .claude/skills/purpleturret/SKILL.md

Codex, Cursor, Gemini CLI, and other agents that read .agents/skills

curl -fsSL https://purpleturret.com/skills/purpleturret/SKILL.md \
  --create-dirs -o .agents/skills/purpleturret/SKILL.md

Every project on this machine (Claude Code personal skills)

curl -fsSL https://purpleturret.com/skills/purpleturret/SKILL.md \
  --create-dirs -o ~/.claude/skills/purpleturret/SKILL.md

Commit the project-scoped copy so teammates and CI agents pick it up. If your agent uses a different location, drop the same file there; it is plain Markdown with YAML front matter and has no other dependencies.

The skill does not include an API key. Agents read PURPLETURRET_API_KEY from the environment or the profile saved by purpleturret login, and the skill instructs them never to print or commit it.

What the skill covers

Area	What the agent learns
Setup and auth	Package install, seller key scopes, credential and API URL resolution order, config file discovery.
Config file	Every product field with its constraints, which fields are immutable, how price changes affect existing subscribers, and how unmanaged products are protected.
CLI	All commands and flags, plan actions, exit codes, CI behavior, JSON output shape.
SDK	Client options, every method with its options and return shape, error classes, a gate-and-meter pattern.
REST	Endpoint table with required scopes, idempotency rules, wire format, rate limits.
Rules	Nine guardrails the agent follows before it touches your account (see below).

Guardrails

The skill ends with rules the agent is told to follow. They keep an eager agent from doing something you did not ask for.

Never print, log, or commit an API key, and never put one in browser or mobile code.
Always run push --dry-run (or status) and show the plan first. Only apply when you asked to, and only pass --yes when you said so.
Never add --prune unless you asked to archive products missing from the file.
Never change price.currency, billing, slug, or stripe.priceId in place. Add a new key instead.
Never rename a key to rename a product; change name.
Derive credits.consume idempotency keys from the business action so retries never double-charge.
Check entitlements on the server and gate on tier.rank, not the tier name.

Example prompts

Once the skill is installed, prompts like these work without further explanation:

Add a "Team" plan at $99/month and $990/year to purpleturret.config.ts,
in the "acme" group at tier rank 100, then show me the push plan.

Our Pro plan should include 5,000 "exports" credits that reset each month.
Update the config and explain what happens to existing subscribers.

Gate the /api/export route on the "acme" group with rank >= 50 and
consume one "exports" credit per call, using the request id as the
idempotency key.

Run purpleturret status and summarize what would change if we pushed.

AGENTS.md and CLAUDE.md

If you prefer always-on instructions over an on-demand skill, or your agent does not support skills yet, paste this into your AGENTS.md, CLAUDE.md, or Cursor rules file. It is a condensed version of the skill.

## Purpleturret

Products live in purpleturret.config.ts and are synced with `pnpm purpleturret push`.
Read https://purpleturret.com/skills/purpleturret/SKILL.md before editing the config
or using @purpleturret/sdk.

- Run `purpleturret push --dry-run` and show the plan before applying. Never pass
  --yes or --prune unless asked.
- price.currency, billing, slug and stripe.priceId are immutable: add a new key
  instead of editing them. Never rename a key; change name.
- Never print or commit PURPLETURRET_API_KEY. The SDK is server-side only.
- credits.consume needs a deterministic idempotencyKey derived from the action.
- Gate features on entitlements.tier.rank, checked on the server.

Machine-readable references

Resource	URL	Use it for
`SKILL.md`	https://purpleturret.com/skills/purpleturret/SKILL.md	Agent skill; also a compact human-readable reference for the CLI and SDK.
`openapi.json`	https://api.purpleturret.com/v1/openapi.json	Full request and response schemas for every REST endpoint, including hosting.
`llms.txt`	https://purpleturret.com/llms.txt	Index of public pages and docs for crawlers and retrieval tools.

Agents that can fetch URLs can read the skill directly instead of installing it: point them at the SKILL.md URL in your prompt.

Keeping it current

The skill carries a version in its front matter and is updated alongside the CLI and SDK. Re-run the install command to refresh it; the file is small enough to review in a diff. Breaking changes to commands or SDK methods ship with a new major package version and a matching skill update.

Found something the skill gets wrong? Tell us and include the prompt that went sideways.