Source: stripe/ai · Maintainer: Stripe · License: MIT · Checked: 24 October 2026
What is the upgrade-stripe skill?
The upgrade-stripe skill is Stripe's official Agent Skill for moving an integration to a newer Stripe API version: it tells your coding agent how to choose the target version, update SDKs and Stripe.js, handle webhook endpoints, and test before switching. Install it with npx skills add https://github.com/stripe/ai --skill upgrade-stripe.
Its full description is: "Guide for upgrading Stripe API versions, webhook endpoints, server-side SDKs, Stripe.js, and mobile SDKs". The folder holds a single SKILL.md.
The skill lives in stripe/ai, whose skills README says the folder is "synced automatically from docs.stripe.com/.well-known/skills". The same skill is part of the set you get from Stripe's Skills for agents page. As of 24 October 2026, its skills.sh page listed 72.6K installs (snapshot, 24 October 2026), second in the repo after stripe-best-practices.
What does it do?
The skill is model-invoked: the agent loads it when you ask to upgrade Stripe, bump an SDK or move webhooks to a new version. The SKILL.md covers five areas.
Choosing the target version. If you name a version, the agent uses it. If not, it looks up the current one on docs.stripe.com, for example with stripe docs /api/versioning in the Stripe CLI. The skill bundles a fallback, 2026-09-30.endive, and says it is "only a snapshot from the last time this skill was generated, on 2026-10-24." It adds: "Never guess about a newer version number." That fallback matched Stripe's versioning page on 24 October 2026, which said: "The current version is 2026-09-30.endive."
Before changing anything, the agent compares the target with every pinned version (client config, per-request overrides, webhook endpoints). It won't move a pin to an older version or a stable pin to a preview version unless you ask, and it reports pins that already match. If it can't verify the latest version live, it must say so.
How Stripe versioning works. The skill restates Stripe's model: since 2024-09-30.acacia, new API versions ship monthly with no breaking changes, and twice a year a major release starts with a version that has breaking changes. It lists which changes are backward compatible (new resources, optional parameters, response properties, event types) and which are breaking (renames or removals, behavior changes, removed endpoints).
Server-side SDKs. The rules split by language:
| SDK type | Languages | What the agent does |
|---|---|---|
| Dynamically typed | Ruby, Python, PHP, Node.js | Sets the version globally or per request |
| Strongly typed | Java, Go, .NET | Picks an SDK release that targets the version; never overrides it |
| Preview targets | All | Uses the matching beta SDK release |
It also tells the agent to always pin the version in code ("Good: Explicit version") rather than rely on the account default. Stripe's upgrade guide gives the same advice.
Stripe.js and mobile SDKs. Stripe.js has major releases twice a year (Acacia, Basil, Clover, Dahlia, Endive), loaded by script tag such as https://js.stripe.com/endive/stripe.js or through @stripe/stripe-js, and each pairs with its API version. iOS and Android SDKs use semantic versioning; React Native uses a 0.x.y scheme where minor versions can break.
An upgrade checklist. Nine steps: read the API changelog, check the upgrade guide, update the SDK package, set apiVersion, test with the Stripe-Version header, review event destinations, update Stripe.js and mobile SDKs, and make sure database columns can hold Stripe object IDs up to 255 characters with case-sensitive collation.
The event destination step is the most involved. A destination's snapshot_api_version can't be changed after creation, so the agent creates and tests a replacement, keeps both signing secrets during cutover, then disables the old one. Thin event destinations are left alone because their payloads are unversioned.
How do you install it?
Stripe documents its install routes on its Skills for agents page and in the stripe/ai README. The plugin and CLI routes install all of Stripe's skills.
Claude Code plugin (recommended by Stripe). The plugin includes this skill, the other Stripe skills and the Stripe MCP server, and updates itself:
claude plugin install stripe@claude-plugins-official
It comes from Anthropic's official plugin marketplace; see Claude Code plugins. The README gives codex plugin add stripe@openai-curated for Codex and /add-plugin stripe for Cursor.
Stripe CLI setup. This detects which agents you use and runs the matching install:
npm install -g @stripe/cli@latest
stripe agent setup
Skill files from Stripe's docs. Stripe notes that manual installs don't update themselves, so run npx skills update -y from time to time:
npx skills add https://docs.stripe.com
Just this skill. The command on skills.sh:
npx skills add https://github.com/stripe/ai --skill upgrade-stripe
For Claude Code the folder lands in .claude/skills/upgrade-stripe/, or ~/.claude/skills/upgrade-stripe/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.
Because the bundled fallback version goes stale each month, keep the skill updated, or make sure the agent can reach docs.stripe.com.
How do you use it?
Point the agent at your integration and name the scope. It should report the version it chose and where that came from before editing.
Example prompts (suggestions, not quotes from the repo):
Upgrade this app to the latest Stripe API version. Show me every pinned version first.We're on 2024-12-18.acacia. List the breaking changes that affect our code before upgrading.Move our webhook endpoint to the new API version without dropping events.Upgrade stripe-java to a release that targets the current API version.Switch our Stripe.js script tag to the current major version and check what changes.
For a large jump, ask for a plan first. The skill points the agent to the changelog and upgrade guide, but it can't know which product areas your code uses until it reads your code.
Tips and limits
From the SKILL.md, Stripe's docs and skills.sh, not from testing:
- Test before switching. The skill uses the
Stripe-Versionheader to try a new version without changing your default, and Stripe's guide recommends testing in a sandbox. - Rollback window. The skill says that for 72 hours after upgrading you can roll back to your previous API version in Workbench.
- Webhooks need two endpoints. Replacing a destination means events reach both during cutover, so Stripe's upgrade guide says your handler must be idempotent.
- The fallback version ages. It is dated, and the skill itself says a fallback more than a month old is "probably stale."
- Audits. On 24 October 2026, skills.sh showed Pass from Gen Agent Trust Hub, Socket and Snyk, all audited that day. Gen Agent Trust Hub noted that the skill reads version data from docs.stripe.com and the Stripe CLI, which it treated as official sources.
- License. MIT, from the stripe/ai LICENSE file; the skill folder has none of its own. Copy and change it, keeping the copyright notice.
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. Paste the repo link instead and Kipt lists the Stripe skills in skills/ so you can take stripe-best-practices too. Your library stays in a private GitHub repo you own and installs into Claude Code or Codex with one command:
npx skills add https://github.com/<you>/<repo>.git --all -g
Kipt is not affiliated with Stripe.
Similar skills
- Stripe skill (stripe-best-practices): Stripe's most installed skill, for choosing the right APIs when you build an integration.
- Deprecation and migration skill: a general skill for planning migrations off deprecated APIs and code.
- Neon skill: Neon's official overview skill, another vendor skill that tells the agent to check current docs first.
- Supabase skill: Supabase's official skill, often used alongside Stripe in SaaS apps.