--- title: "stripe/ai" description: "One-stop shop for building AI-powered products and businesses with Stripe." source: https://github.com/stripe/ai ref: main license: MIT licenseName: "MIT License" canonical: https://skillsdocs.com/stripe/ai base: https://github.com/stripe/ai/blob/main/ chapters: 7 inlined: 7 withheld: 0 words: 5995 updated: 2026-08-08T00:26:57Z generator: "Skills Docs" --- > **stripe/ai** — every Agent Skill in this repository, inlined verbatim. > > Canonical HTML: https://skillsdocs.com/stripe/ai > Per-chapter Markdown: https://skillsdocs.com/stripe/ai/.md > Machine manifest: https://skillsdocs.com/stripe/ai/.well-known/agent-skills/index.json > JSON: https://skillsdocs.com/api/v1/books/stripe/ai > Install: `npx skills add stripe/ai` > Upstream: https://github.com/stripe/ai @ `main` > Licence: MIT > > Content is mirrored from GitHub and © its authors, served unmodified. Takedown: https://github.com/kyleledbetter/skillsdocs/issues/new?labels=takedown&title=Takedown+request # stripe/ai One-stop shop for building AI-powered products and businesses with Stripe. - **Chapters:** 7 - **Inlined:** 7 (licence detected) - **Words:** 5,995 - **Reading time:** 29 min - **Stars:** 1,731 ## Table of contents 1. [connect-recommend](https://skillsdocs.com/stripe/ai/connect-recommend.md) — Use this skill when the user asks about Stripe Connect configuration, charge patterns, Dashboard access, or how to get started with Connect, is building a mark… 2. [stripe-apps](https://skillsdocs.com/stripe/ai/stripe-apps.md) — Use when building, modifying, or reviewing a Stripe App — or when the user describes something that implies one (e.g. "add a panel to the customer page", "cust… 3. [stripe-best-practices](https://skillsdocs.com/stripe/ai/stripe-best-practices.md) — Guides Stripe integration decisions across API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), bi… 4. [stripe-directory](https://skillsdocs.com/stripe/ai/stripe-directory.md) — Use when the user wants to find businesses, software, service providers, or partners for a specific industry, workflow, pain point, capability, or job to be do… 5. [stripe-docs](https://skillsdocs.com/stripe/ai/stripe-docs.md) — Use when the user or agent needs to read, search, or look up Stripe documentation or API reference. Prefer this over curl or WebFetch for any docs.stripe.com c… 6. [stripe-projects](https://skillsdocs.com/stripe/ai/stripe-projects.md) — Use when the user wants to provision infrastructure or third-party services using Stripe Projects. Triggers: "I need a database", "set up auth", "add caching",… 7. [upgrade-stripe](https://skillsdocs.com/stripe/ai/upgrade-stripe.md) — Guide for upgrading Stripe API versions and SDKs ## Front matter _The repository README, verbatim except that relative links are resolved against https://github.com/stripe/ai/blob/main/._ ![Hero GIF](https://stripe.dev/images/badges/ai-banner.gif) # Stripe AI This repo is the one-stop shop for building AI-powered products and businesses on top of Stripe. It contains a collection of SDKs to help you integrate Stripe with LLMs and agent frameworks, including: * [`@stripe/ai-sdk`](https://github.com/stripe/ai/blob/main/llm/ai-sdk) - for integrating Stripe's billing infrastructure with Vercel's [`ai`](https://npm.im/ai) and [`@ai-sdk`](https://ai-sdk.dev/) libraries. * [`@stripe/token-meter`](https://github.com/stripe/ai/blob/main/llm/token-meter) - for integrating Stripe's billing infrastructure with native SDKs from OpenAI, Anthropic, and Google Gemini, without any framework dependencies. ## Model Context Protocol (MCP) Stripe hosts a remote MCP server at `https://mcp.stripe.com`. This allows secure MCP client access via OAuth. View the docs [here](https://docs.stripe.com/mcp#connect). You can also [build autonomous agents](https://docs.stripe.com/mcp#agents) with MCP as well. ## Agent skills [Agent skills](https://agentskills.io/home) are instructions that agents can use to build faster and more accurately. Stripe offers a collection of skills that help your agents use the latest best practices when building with Stripe. If you use one of these popular agent harnesses, we recommend installing the official Stripe plugins, which include additional agent tools and update automatically. ### Claude Code Run this command in your project: ```bash claude plugin install stripe@claude-plugins-official ``` ### Codex Run this command in your project: ```bash codex plugin add stripe@openai-curated ``` ### Cursor Run this command in your project: ```bash /add-plugin stripe ``` You can also install through the [Cursor marketplace](https://cursor.com/marketplace/stripe). ### Grok Build Run this command in your project: ```bash grok plugin install stripe --trust ``` ## Manual installation > Manually installed skills don’t auto-update. Run `npx skills update -y` to get the latest versions. Run this command in your project: ```bash npx skills add https://docs.stripe.com ``` ## License [MIT](https://github.com/stripe/ai/blob/main/LICENSE) --- ## 1. connect-recommend - **Source:** https://github.com/stripe/ai/blob/main/skills/connect-recommend/SKILL.md - **Raw:** https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/SKILL.md - **Markdown:** https://skillsdocs.com/stripe/ai/connect-recommend.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (8), referenced from this skill's directory: - `references/account-types.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/account-types.md - `references/charge-patterns.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/charge-patterns.md - `references/company-researcher.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/company-researcher.md - `references/compatibility-matrix.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/compatibility-matrix.md - `references/decision-matrix.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/decision-matrix.md - `references/discovery-questions.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/discovery-questions.md - `references/recommendation-template.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/recommendation-template.md - `references/terminology-rules.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/connect-recommend/references/terminology-rules.md --- name: connect-recommend description: >- Use this skill when the user asks about Stripe Connect configuration, charge patterns, Dashboard access, or how to get started with Connect, is building a marketplace, platform, multi-vendor store, gig platform, or subscription platform, needs to pay out sellers, vendors, or providers, mentions split payments, revenue sharing, multi-party payments, or similar payment distribution concepts, provides a company URL or business description for a recommendation, builds SaaS that routes money between parties (for example, POS, booking, invoicing — not operational SaaS without payment routing), asks about onboarding or KYC for merchants, sellers, and vendors, mentions connected account Dashboard or responsibility configurations, or asks about payment flows, white-label payments, or embedded payments. --- ## Connect recommend Recommend the right Stripe Connect integration configuration. The user only needs to provide a company URL or describe their business — the skill figures out the rest. ### Interaction model **User must confirm interactions**. Every decision point in this skill MUST be confirmed with the user with clear, numbered options and short descriptions. One question at a time — never overwhelm the user. **Auto-act on low-cost actions**. Never ask permission for: - Generating the markdown recommendation plan — just generate it - Scanning the codebase — just scan it - Reading reference files — just read them **Never end with passive text**. Every stopping point must end with a prompt to the user offering concrete next actions. ### Terminology rules (user-facing output) **Before generating any user-facing output, read **. Apply those rules to all recommendation text, warnings, explanations, and decision summaries. Key principle: describe configurations using field values (Dashboard + fee ownership + negative balance liability ownership + charge pattern), not shorthand codes. ### Output Brevity Keep responses concise. The user is making decisions, not reading documentation. - Lead with the recommendation, follow with brief rationale - Technical details (API paths, capability checks) go in a “Details” section of the final markdown plan — not inline in the main recommendation - Warning blocks: 2-3 sentences maximum. State the issue and the fix. No mechanism deep-dives unless the user asks. - Decision summary: bullet points only, one line per decision - Never output more than ~40 lines in a single response during interactive mode **Only mention out-of-scope limitations when they’re directly relevant to what the user asked about**. Don’t proactively list constraints or unsupported features (for example, OAuth, international expansion) when the user hasn’t asked about them. “Out-of-scope” here means outside what this guide supports, not outside what Stripe supports. Research these topics in the Stripe public documentation (docs.stripe.com) rather than saying they’re out-of-scope. ### Instructions #### Step 0 — Show progress Display the progress checklist so the user knows what to expect: ``` Here's what we'll do: [ ] Learn about your business [ ] Scan your project [ ] Recommend configuration + charge pattern [ ] Produce recommendation plan Let's get started. ``` #### Step 1 — Learn about the business (ALWAYS runs first) This is the most important step. Before scanning any code or asking technical questions, understand **what the business is**. **1a. Check if the user already provided a URL or business description** in their message. Look for: - A URL (for example, `https://...`, `www.`, `.com`, `.io`) - A business description (for example, “I’m building a marketplace for…”, “We connect freelancers with…”) - A company name that can be searched **1b. If nothing was provided**, ask immediately using AskUserQuestion — this is the FIRST question the user sees: ``` Tell me about your business. Pick whichever is easiest: ``` Options: - “I have a URL” — user provides URL, then research it - “Let me describe it” — user provides description, then research it - “Just scan my codebase” — skip to Step 2, rely on codebase signals only - “Skip — ask me questions instead” — skip to Step 3 with full questionnaire **1c. Research the business** — read and follow the company-researcher instructions: Read and perform those research steps, using the company URL (if provided) and business description (if provided) as inputs. The research produces a structured analysis with confidence levels (HIGH/MEDIUM/LOW) for each decision dimension. **1d. Parse the agent’s output** — it returns a Research Findings table with confidence levels per dimension. Read the decision matrix at and map the findings to a recommended configuration. Then determine pre-fill behavior per dimension: - **HIGH confidence**: Auto-fill — don’t ask about this dimension - **MEDIUM confidence**: Suggest the inferred value and ask for quick confirmation - **LOW confidence**: Ask the original open-ended question in Step 3 **1e. Present what you learned** to the user (use second-person, conversational confirmation tone): ``` Here's what I gathered about your business — let me know if anything looks off: ┌──────────────────────────┬────────────────────────────────┐ │ *Business type* │ [marketplace or SaaS platform] │ ├──────────────────────────┼────────────────────────────────┤ │ *Sellers/providers* │ [who they are] │ ├──────────────────────────┼────────────────────────────────┤ │ *Buyers/customers* │ [who they are] │ ├──────────────────────────┼────────────────────────────────┤ │ *How money flows* │ [payment flow] │ ├──────────────────────────┼────────────────────────────────┤ │ *Fee structure* │ [fee details] │ └──────────────────────────┴────────────────────────────────┘ Based on this, I'd recommend: [configuration description in plain language] I'll proceed with this unless you'd like to correct anything. ``` For MEDIUM confidence items, append: “I’m also assuming [X] — sound right?” If the agent flags “not-connect” (business doesn’t need Connect), ask the user: ``` Based on my research, your business may not need Stripe Connect — a standard Stripe integration might be a better fit. ``` Options: - “Proceed with Connect anyway” — continue discovery - “Explore standard integration instead” — exit this skill, suggest standard Stripe integration Update the checklist: ``` [x] Learn about your business [ ] Scan your project [ ] Recommend configuration + charge pattern [ ] Produce recommendation plan ``` **1f. Validate fee economics (ALWAYS runs, even on auto-filled values)** If the platform fee (from auto-fill or user input) appears low AND any of these conditions apply: - Charge pattern is `destination` or `separate` (platform pays Stripe fees by default) - Charge pattern is `direct` AND `fees_collector: "application"` (platform still pays Stripe fees) Then: - ALWAYS show a margin warning regardless of how the fee was obtained - Warn: “Your platform fee might be below Stripe’s processing fees at standard rates. Because the platform pays the Stripe processing fees, your net margin could be thin or negative. Check [stripe.com/pricing](https://stripe.com/pricing) for your region’s rates.” - If the charge pattern is `destination` or `direct` (with `fees_collector: "application"`): The platform needs to calculate `application_fee_amount` as platform fee + estimated Stripe processing fee (so that the platform preserves its margin) and (if the platform owns pricing) use the [Platform Pricing Tool](https://dashboard.stripe.com/settings/connect/platform_pricing) - If the charge pattern is `separate` (separate charges and transfers): `application_fee_amount` is NOT compatible. They need to calculate the net transfer amount to preserve margin instead of using `application_fee_amount`. - Recommend monitoring the [margin report](https://docs.stripe.com/connect/margin-reports.md) in the Stripe Dashboard This check MUST run even when the fee was auto-filled with HIGH confidence. The user needs to understand the fee economics before proceeding. #### Step 2 — Auto-detect project context Run this AFTER Step 1 (or in parallel if the user said “scan my codebase”). Use codebase signals to supplement or corroborate the company research. **Don’t ask before scanning — just scan.** 1. **Existing Connect config**: Check for `connect-recommend-plan.md` or any file at the project root that resembles a prior recommendation plan (for example, a file containing `## Recommended Connect integration plan`). If found, read it and note the prior configuration — use it to pre-fill or validate decisions in later steps, and present it to the user before asking questions they’ve already answered. 2. **Existing Stripe integration patterns**: Use Grep to search for Connect-specific patterns already in the codebase: - Connected account creation or references (`connected_account`, `account_id`, `stripe_account`) - Charge patterns in use (`destination`, `on_behalf_of`, `transfer_data`, `separate_charges`) - Transfer or payout logic (`transfers.create`, `payouts.create`) - Webhook handlers for Connect events (`account.updated`, `capability`, `payout`) - Existing `application_fee_amount` usage If codebase signals contradict the company research, note the discrepancy and ask the user to clarify. Present findings briefly (don’t repeat what Step 1 already covered): ``` Project scan: - Existing Connect plan: [found at path / not found] - Existing Connect integration: [patterns found / not found] ``` If a prior plan was found, ask the user: ``` I found an existing Connect recommendation plan at [path]. ``` Options: - “Use it as a starting point” — pre-fill all decisions from the prior plan, then confirm each with the user in Step 3 - “Start fresh” — ignore the prior plan and run full discovery Update the checklist: ``` [x] Learn about your business [x] Scan your project [ ] Recommend configuration + charge pattern [ ] Produce recommendation plan ``` #### Step 3 — Ask remaining discovery questions For any dimension not already filled with HIGH confidence from Step 1, ask the corresponding question to the user. Skip dimensions that were auto-filled or explicitly confirmed. **Read ** for complete question scripts, option mappings, and edge-case logic for Step 3, Step 3b (hybrid flows), Step 3c (sales-led/scope detection), and the fee-structure checkpoint. If Step 1 was skipped entirely, ask all six discovery questions one at a time: - Q1: Business model - Q2: Parties in the platform - Q3: Payment flow - Q4: Dashboard and onboarding preference - Q5: Dispute and refund ownership + risk management + loss liability - Q6: Fee structure + `application_fee_amount` calculation Critical guardrails (must enforce in all discovery paths): - For marketplace or intermediary checkout flows, default to destination charges unless behavior clearly indicates each seller runs their own checkout or payment relationship. - If the business mixes its own-brand sales with marketplace or intermediary flows, trigger Step 3b hybrid-flow handling and map each flow to its own charge-pattern and responsibility settings. - If the user needs hold-and-release timing, recommend separate charges and transfers (destination charges can’t hold funds and aren’t appropriate for hold-and-release behavior). - For SaaS with independent sellers that own customer relationships, use full dashboard + direct charges + embedded onboarding. - If the user asks “what account type should I use?”, reframe during discovery to Accounts v2 explicit fields (`dashboard`, `defaults.responsibilities`, and `merchant` or `recipient` by funds flow), not legacy account types. Read for the full v2 configuration reference. - When describing low-margin scenarios, present warnings and risks before mitigation steps. - If `dashboard: "none"` is selected, include a concise full-scope warning about custom UI responsibilities. - For destination or separate recommendations with `losses_collector: "application"`, explain the causal chain: platform owns negative balance liability and connected-account negative balances enable dispute-time transfer reversals. - Keep risk management and negative balance liability as separate decisions. - Trigger Step 3c when enterprise or sales-led signals appear (`on_behalf_of`, cross-border complexity, non-Connect products, or sales-gated configs). Fee structure checkpoint before Step 4: 1. Confirm fee type and fee amount 2. Confirm how `application_fee_amount` is calculated 3. Confirm whether a margin warning is required 4. Include stripe.com/pricing link in output context #### Step 4 — Generate recommendation Read the decision matrix at and apply it to the user’s answers. For charge pattern details, read . **Step 4a — Compatibility validation (MANDATORY before presenting recommendation)** Read and cross-check the proposed `(dashboard, fees_collector, losses_collector)` + `chargePattern` combination against the compatibility matrix. 1. **BLOCKED combination?** Do NOT present it. Output a visible BLOCKED warning with ALL of these: - The exact blocked config tuple (for example, `losses_collector: "stripe" + destination charges`) - A 2-3 sentence explanation of the MECHANISM of failure (for example, “With destination charges and a dispute, Stripe debits the disputed amount from the platform’s balance. The platform must then manually reverse the transfer to recover funds from the connected account — but `reverse_transfer` defaults to false on both refunds and disputes, so recovery isn’t automatic. With `losses_collector: 'stripe'`, the platform has no mechanism to push negative balance recovery onto the connected account, so it silently absorbs the loss.”) - The recommended fix (nearest ALLOWED alternative — usually switching `losses_collector` to `"application"` or switching to direct charges) Then re-run the recommendation with the corrected configuration. 2. **CAUTION combination?** Present the recommendation but include a visible warning callout explaining the specific tradeoff (for example, “dashboard visibility limitations for direct charges when using `dashboard: \"express\"`”). 3. **Additional compatibility checks (include concise warnings when triggered):** - If the user mentioned **OAuth** for connecting accounts, include a 1-2 sentence warning that accounts can disconnect and recommend embedded onboarding for stronger platform control. - If `dashboard: "none"`, include a concise warning that the platform must own onboarding and remediation, refund and dispute flows, and earnings and payout views; recommend Express dashboard with embedded components as a lower-maintenance alternative. - If user mentions **Billing, Invoicing, or Payment Links** with destination charges, include a concise compatibility warning and recommend the nearest supported path. - If `dashboard: "full"` + `fees_collector: "stripe"` + charge pattern is `destination` or `separate`, treat as BLOCKED. Do NOT present this configuration. Output a BLOCKED notice and instruct the user to switch to direct charges. - If `dashboard: "full"` + `fees_collector: "application"`, treat as SALES-GATED regardless of charge pattern. Do NOT recommend for self-serve paths. Redirect to [Stripe sales](https://stripe.com/contact/sales). - If `dashboard: "express"` + `fees_collector: "stripe"`, treat as BLOCKED and recommend either switching to full dashboard (Stripe-owned pricing) or platform-owned pricing. 4. **Merchant-of-record consistency check:** Verify the recommended charge type matches the actual business relationship. Direct charges = connected account provides goods and services directly. Destination and separate charges and transfers = platform owns the customer relationship. Stripe does NOT enforce merchant of record at the API level — the code must be consistent. 5. **Compatibility warning brevity:** Keep compatibility warning copy concise (2-3 sentences max), but include mechanism-aware reasoning and the corrective path. **Step 4b — Recommend embedded components** Embedded components are recommended, as they enable platforms to build full-featured dashboards of their own, especially when accounts are configured with `dashboard: "none"` and even if accounts are configured with (`dashboard: "full"` or `dashboard: "express"`). Select components based on user needs: Baseline (always include): - `account_onboarding` - `notification_banner` (required; keeps connected accounts healthy and enabled as requirements evolve) - `account_management` Common additions: - Transaction history → `payments` (use `payment_details` if building a custom payments list) - Disputes → included with `payments` but can use `disputes_list` if also building a standalone disputes page - Payout operations and earnings → `payouts` - Reporting and reconciliation → `balance_report`, `payout_reconciliation_report` Charge-pattern compatibility caveats: - Destination charges: payment and dispute views show reduced detail. - Separate charges and transfers: payment and dispute views show reduced detail. - Direct: payment and dispute views operate with full fidelity. Out of scope component families: - Issuing, Treasury, and Capital and Tax component sets (route through Step 3c scope handling). Be prepared to output a list of embedded components in the next step. Update the checklist: ``` [x] Learn about your business [x] Scan your project [x] Recommend configuration + charge pattern [ ] Produce recommendation plan ``` #### Step 5 — Generate recommendation plan **Read ** and follow its “Output requirements” checklist and “Canonical recommendation template” structure. That file is the single source for required sections, wording, and formatting. If any required section is missing from your output, add it before moving on. Then ask the user: ``` Does this recommendation look right? ``` Options (max 4 — options hard limit): - “Looks good” — proceed to Step 6 - “Change something” — ask which aspect to change (dashboard or responsibility settings, charge pattern, fee structure, or fee calculation) then re-ask the relevant question - “Explain more about the options” — read reference docs and explain alternatives Generate the final recommendation plan. If the user asks, also write the exact same markdown to `connect-recommend-plan.md` at the project root. When they accept the plan, update the checklist: ``` [x] Learn about your business [x] Scan your project [x] Recommend configuration + charge pattern [x] Produce recommendation plan ``` #### Step 6 — Explain what belongs in code vs Dashboard, and next actions Show a compact summary of decisions and immediate implementation priorities. Briefly explain: - **In your code**: charge pattern behavior, `application_fee_amount` math, transfer and reversal handling, and webhook handlers - **In the Stripe Dashboard**: platform profile settings, pricing tool configuration, connected-account visibility, Radar for Platforms settings, and operational monitoring - **During onboarding and runtime**: capability activation, payouts readiness, and account-state transitions **IMPORTANT: Always end with AskUserQuestion.** Never end with passive text. Use AskUserQuestion: ``` What would you like to do next? ``` Options: - “Refine a decision” — adjust dashboard, responsibilities, charge pattern, or fee model - “Expand implementation steps” — provide a deeper technical rollout checklist - “Generate `connect-recommend-plan.md` and build” — write the plan to a markdown file and handoff to a coding agent --- ## 2. stripe-apps - **Source:** https://github.com/stripe/ai/blob/main/skills/stripe-apps/SKILL.md - **Raw:** https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/SKILL.md - **Markdown:** https://skillsdocs.com/stripe/ai/stripe-apps.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (10), referenced from this skill's directory: - `references/authentication.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/authentication.md - `references/backend.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/backend.md - `references/canonical-docs.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/canonical-docs.md - `references/discovery.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/discovery.md - `references/extension-types.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/extension-types.md - `references/onboarding-ux.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/onboarding-ux.md - `references/publishing.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/publishing.md - `references/ui-extensions.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/ui-extensions.md - `references/webhooks.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/webhooks.md - `references/workflow.md` — https://raw.githubusercontent.com/stripe/ai/main/skills/stripe-apps/references/workflow.md --- name: stripe-apps description: >- Use when building, modifying, or reviewing a Stripe App — or when the user describes something that implies one (e.g. "add a panel to the customer page", "customize my Stripe Dashboard", "react to Stripe events from my app", "connect my service to Stripe without sharing API keys"). Covers the full app development workflow (scaffold, preview, upload, versioning), UI extension architecture (sandboxed iframe, Stripe UI toolkit, viewports), extension types (UI extensions, backend-only, extension interfaces, embedded apps), authentication (platform keys, OAuth, restricted API keys), stripe-app.yaml manifest setup (permissions, viewports, CSP), webhook configuration for apps, Secret Store API, `fetchStripeSignature` auth, and marketplace publishing. Use when the user mentions Stripe Apps, UI extensions, @stripe/ui-extension-sdk, stripe-app.yaml, Dashboard extensions, or customizing the Stripe Dashboard. --- ## Stripe Apps — Agent Instructions **FIRST ACTION:** Say “Loading Stripe Apps skill.” then Read `references/discovery.md`. This file has routing logic you need before asking the user questions. ### Your role You are a PROJECT BUILDER and INSTRUCTOR. Your primary output is working files on the user’s machine that they can run immediately. If you explain code without also writing it to disk using your Write tool, the user has nothing they can execute. You are also a patient guide. Many users have never heard of Stripe Apps, viewports, or webhooks. When they say “I’m not sure” or “what does that mean?”, explain concepts in plain language with examples from their specific idea. **Your tool calls (Read, Write) are your real work. Your chat messages explain what you did and teach the user why.** ### Source of truth for code patterns Your training data for Stripe Apps SDK patterns may be outdated or incorrect. Before writing any code file, you MUST read the relevant canonical docs page using WebFetch. See `references/canonical-docs.md` for the full list of docs pages. If you cannot access the docs, tell the user: “I need to check the current Stripe Apps documentation to write correct code. Can you provide the current patterns from [relevant docs URL], or shall I proceed with the scaffold and you can verify against the docs?” ## HARD RULES — violating any of these is a failure | \# | Rule | What failure looks like | | --- | --- | --- | | 0 | BEFORE ANYTHING ELSE: (1) Say “Loading Stripe Apps skill.” (2) Call Read on `references/discovery.md` to load the routing table. You need this data before you can ask informed questions. | Responding to the user before calling Read on discovery.md | | 1 | After reading discovery.md, your FIRST message to the user is ONLY the 4 discovery questions (see Step 1). No code, no plan, no summary. Even if the user’s request already mentions details — ask anyway. Users have unstated requirements that only emerge through questions. | Presenting a summary, plan, or any code before asking questions 1-4 and getting answers | | 2 | You MUST use your Write tool to create or modify files on disk. The scaffold creates base files via CLI — after that, use Write to modify scaffolded files and create new ones. A response with code only in chat gives the user nothing runnable. | Producing code in chat without calling Write to save it to disk | | 3 | Run `stripe generate app ` using your Bash tool to scaffold the project. Then use Write to modify scaffolded files and create additional files the app needs. | Writing stripe-app.yaml or package.json from scratch instead of modifying the scaffold output | | 4 | Before writing code for any topic (backend, UI, webhooks, auth), read the relevant canonical docs page using WebFetch. See `references/canonical-docs.md`. The docs are the source of truth — not this skill file, not your training data. | Writing code from memory without checking the current docs | | 5 | Tell user: `stripe apps upload` BEFORE testing fetchStripeSignature/Secret Store (the signing secret is generated during first upload). | Omitting upload-first requirement | | 6 | File names: `ui/src/views/App.tsx` (V2 workspace layout), `server.js` (project root). Only create files that are needed for the app’s architecture (see Step 3). | Using wrong filenames or creating files the architecture doesn’t need | | 7 | Every file you write to disk MUST be complete and runnable — not a skeleton or placeholder. The user should be able to run it immediately. Do not write partial files with TODOs. | Writing a file with TODO placeholders or incomplete implementations | | 8 | When presenting the development workflow, include `pnpm build` and `pnpm test` as explicit steps for apps with a UI extension. Backend-only apps without TypeScript skip `pnpm build`. | Omitting build/test steps for UI apps, or requiring them for backend-only apps | | 9 | If the user’s app requires custom objects or extension interfaces (private preview features), OR full-page apps, inform them the feature is in private preview and ask them to confirm they have access BEFORE proceeding. Do not silently proceed with a private preview feature. | Building with private preview features without confirming user has access | ## BLOCKED — these produce broken apps | BLOCKED (never use) | Use instead | | --- | --- | | `stripe apps create` | `stripe generate app ` | | Raw HTML in UI extensions (`
`, ``, `

`, `