Stripe skill: what it does and how to install it

Source: stripe/ai · Maintainer: Stripe · License: MIT · Checked: 23 October 2026

What is the Stripe skill?

The Stripe skill, stripe-best-practices, is Stripe's official guidance for coding agents that build or review a Stripe integration: which API to pick, how to handle webhooks and keys, and which deprecated patterns to avoid. It is for developers who let Claude Code, Codex or Cursor write payment code and want it to match what Stripe recommends today.

It lives in stripe/ai, Stripe's repo for AI tooling. The folder is synced automatically from Stripe's docs site at docs.stripe.com/.well-known/skills, according to the skills folder README. Its description begins: "Guides Stripe integration decisions across development and test environment planning (separate sandboxes vs the shared test mode sandbox), API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, tax and registrations (Stripe Tax, automatic_tax, product tax codes), Treasury financial accounts, integration options (Checkout, Payment Element), migrating from deprecated Stripe APIs, and security best practices (API key management, API key permissions, webhooks, OAuth)." It then says to use it when planning, building, modifying, testing or reviewing any Stripe integration.

As of 23 October 2026, its skills.sh page listed about 97,000 installs.

What does it do?

The SKILL.md opens with current defaults, then routes each kind of work to a reference file:

It tells the agent to read the matching reference before answering or writing code. The critical rules include:

• Never pass payment_method_types, except card_present for Terminal. Omitting it turns on dynamic payment methods managed from the Dashboard.
• Never present webhooks as optional. They are required for subscriptions and asynchronous payment methods. Fulfillment belongs in handlers for checkout.session.completed and checkout.session.async_payment_succeeded, not on the success page.
• Check tax registration first. Before enabling automatic_tax, confirm there is an active registration, or Stripe collects no tax while you think it does.
• Use a StripeClient instance, not the deprecated global API key pattern.
• Recommend restricted API keys (rk_) over secret keys (sk_), and separate sandboxes for local development and CI.

The SKILL.md also names the latest API version and SDK versions per language, so the agent stops writing code against old releases. Those numbers change with each sync, which is why the folder is generated from Stripe's docs.

What's in the folder:

• SKILL.md: defaults, the routing table, critical rules and links to key docs.
• references/: payments.md, billing.md, connect.md, security.md, tax.md and treasury.md. Several include "Traps to avoid" lists; security.md covers key storage, IP restrictions, webhook signature checks, CSP and incident response.

No scripts ship with it.

How do you install the Stripe skill?

Stripe documents three routes on its Skills for agents page and in the stripe/ai README.

Claude Code plugin (recommended by Stripe). The plugin bundles the Stripe MCP server and all of Stripe's skills, and updates them for you:

claude plugin install stripe@claude-plugins-official

Stripe's plugin page lists the equivalent for Codex (codex plugin add stripe@openai-curated) and Cursor (/add-plugin stripe).

Stripe CLI setup. This detects which agents you use and runs the right install for each:

npm install -g @stripe/cli@latest
stripe agent setup

Skill files only. This installs Stripe's skills from its docs site with the skills CLI. Stripe notes that manual installs don't update themselves; run npx skills update -y now and then.

npx skills add https://docs.stripe.com

To take only this one skill, the skills.sh page gives npx skills add https://github.com/stripe/ai --skill stripe-best-practices. For Claude Code the folder lands in .claude/skills/stripe-best-practices/, or ~/.claude/skills/stripe-best-practices/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

claude.ai. Zip the folder and upload it under Customize, then Skills (Claude Help Center), which suits planning and code review in chat.

How do you use it?

The skill loads when a task touches Stripe, so ask in plain words. Example prompts (suggestions, not quotes from the repo):

• "Add one-time payments to this Next.js app with Stripe, including the webhook that fulfills the order."
• "Review our Stripe integration for deprecated APIs and anything that breaks the critical rules."
• "We're building a marketplace where sellers get paid out. Which Connect setup fits, and what do we store?"
• "Turn on sales tax collection for EU and US customers, and tell me what has to be registered first."
• "Move our API keys to a restricted key with only the permissions this service needs."

The skill needs no packages. Building and testing an integration needs a Stripe account or sandbox; the SKILL.md says the agent can create a test sandbox with the Stripe CLI's stripe sandbox create, and that it should not use MCP after that unless stripe sandbox claim has been run.

For live account data (customers, payments, docs search) add Stripe's MCP server, or let the plugin add it. The best MCP servers guide has the Claude Code command and Stripe's security notes on write actions and key types.

Tips and limits

• Guidance, not access. The skill writes better integration code; it cannot see your account. That is the MCP server's job.
• Versions move. API and SDK version numbers in the SKILL.md change as Stripe syncs the folder. Plugin installs update automatically; file installs need npx skills update -y.
• It points to other Stripe skills. For usage-based billing it hands off to Stripe's separate metronome skill, and reads it from docs.stripe.com if you don't have it installed. Installing all Stripe skills avoids that fetch.
• Security audits. As of 23 October 2026, skills.sh showed Gen Agent Trust Hub and Socket as Pass and Snyk as Warn (medium, analysed 22 October 2026). Snyk's finding is that external Metronome URL, which it cannot verify at runtime. Review the files before installing, as with any skill.
• Test before live. The skill pushes sandboxes and restricted keys; keep production secret keys out of agent sessions.
• License. The stripe/ai repo is MIT licensed.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its references; for a repo with many skills, like stripe/ai, it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Note that a copy in your library won't follow Stripe's automatic syncs, so re-import it when Stripe updates. Kipt is not affiliated with Stripe.

Similar skills

• API design skill: Addy Osmani's rules for your own endpoints, including how to honour an idempotency key on payment calls.
• Postgres best practices skill: Supabase's rules for the database behind your orders and subscriptions.
• Best MCP servers: Stripe's MCP server and other official servers.
• Claude Code plugins: how plugins like Stripe's bundle skills and MCP servers into one install.