Stripe 集成最佳实践
为支付、订阅、平台业务、税务和安全集成选择合适的 Stripe API 与实现方式。
文件明确建议受限 API key、最小权限、密钥保管、轮换、Webhook 签名验证、OAuth state、2FA 和税务操作前确认，并避免自动创建或过期税务注册，显示出较强的安全与外部影响意识。扣 6 分：Stripe CLI 生成测试密钥的说明缺少权限边界与风险提示；未系统说明个人数据流、回滚方案和所有外部副作用；Connect 安全建议之间存在冲突。
集成路由、关键规则和失败陷阱写得较具体，且引用了配套 reference 文件。扣 13 分：Connect 部分同时要求 Accounts v2，又称 Standard 是更安全默认且不应推荐 Express/Custom，和前文 v2 dashboard 配置建议冲突；未提供针对该技能关键路径的专门测试、输入校验或可诊断失败反馈。静态评估按上限不超过 10 分。
描述覆盖支付、订阅、税务、Connect、Treasury 和安全等明确场景，路由表也有助于语义触发。扣 6 分：范围非常宽，缺少明确的非适用场景、输入输出约定和触发排除条件；未说明中文交互支持，也未讨论中国大陆网络访问 docs.stripe.com、npm 或 Stripe CLI 的可达性。
技能具有 front matter、分域 reference 文件、目录、安装说明、MIT 许可证和仓库级同步维护信号，结构清晰。扣 7 分：技能自身没有版本号、变更记录、明确维护责任人或稳定更新路径；部分安装和维护信息只在 README 中，故障排查、FAQ 和已知限制仍不完整。
规则可直接指导 API 选择、动态支付方式、税务前置条件、Connect 责任配置和密钥安全，核心任务大致可完成。扣 9 分：没有针对典型用户请求的完整可复制输出或端到端示例，若缺少外部文档访问仍需较多人工核验；Connect 的矛盾建议可能导致错误实现。静态评估按上限不超过 7 分。
文件包含大量指向 Stripe 官方文档的主张，并有仓库 CI 与技能同步工作流，具备一定审计线索。扣 6 分：CI 主要覆盖工具包而非该技能关键建议，没有提交的技能测试或第三方执行证据；无法从静态文件独立验证 API 版本、Metronome、Accounts v2 等时效性主张。静态评估按上限不超过 5 分。
- 修复 Connect 安全章节中 Accounts v2、Standard、Express 和 Custom 之间的冲突，并明确不同 API 版本下的适用配置。
- 对最新 API 版本、Metronome 和 Accounts v2 等时效性主张增加版本来源、更新时间和变更记录。
- 补充不适用场景、失败处理、端到端示例，以及中国大陆网络不可达时的替代路径。
- 使用 Stripe CLI 生成密钥前，应明确仅限 sandbox、权限范围和密钥生命周期。
它能做什么 & 适用场景
该技能用于构建、修改或审查各种 Stripe 集成。它覆盖一次性付款、Checkout、Payment Element、Setup Intents、订阅、Connect 平台、Stripe Tax、Treasury 财务账户以及密钥和 Webhook 安全。技能会根据业务场景推荐 API，并要求先阅读对应的参考文件。它还规定使用最新 Stripe API 版本，并优先推荐受限 API 密钥。
根据集成目标在 Checkout Sessions、PaymentIntents、Setup Intents、Accounts v2、Billing APIs、Metronome、Stripe Tax、Registrations API 和 v2 Financial Accounts 之间进行路由；提示读取 payments、connect、billing、tax、treasury 或 security 参考文件；检查启用自动税务前是否存在有效注册；指导动态支付方式、Checkout 会话标识、API 密钥、Webhook、OAuth、2FA 和 Connect 责任相关实现；可通过 npm 安装 Stripe CLI，并运行 stripe sandbox create 生成测试 API 密钥。
- 开发一次性支付流程的工程师，需要在 Checkout Sessions 与自定义支付界面之间选择合适的方案。
- 搭建市场平台的团队，需要配置 Connect Accounts v2 和控制器属性。
- 实现订阅或按用量计费的产品团队，需要选择 Billing APIs、Checkout Sessions 或 Metronome。
- 在多个国家或地区收取销售税、VAT 或 GST 的团队，需要核对 Stripe Tax、Registrations API 和有效税务注册。
- 审查生产环境 Stripe 集成的工程师，需要改进受限密钥、Webhook、OAuth、2FA 和 API 密钥管理。
- 迁移旧版或已弃用 Stripe API 的团队，需要依据最新 API 版本调整实现。
优缺点一览
- 覆盖支付、订阅、Connect、税务、Treasury 和安全等常见 Stripe 集成领域。
- 提供明确的 API 路由表和关键实现规则。
- 强调税务注册、动态支付方式和受限 API 密钥等容易出错的事项。
- 基于 MIT 许可发布。
- SKILL.md 引用了多个未随用户提供的 references 文件，无法仅凭当前材料核验其全部细节。
- 没有提供测试套件、示例项目或平台兼容性测试证据。
- 技能主要提供决策和审查指导，不是独立的 Stripe SDK 或完整支付实现。
- 部分操作依赖 Stripe 文档、Stripe CLI 和网络访问。
如何安装
在项目中运行 npx skills add https://docs.stripe.com 进行手动安装。手动安装的技能不会自动更新，可运行 npx skills update -y 获取最新版本。README 未说明如何只安装 monorepo 中的这一项技能。
如何使用
将该技能放入 Agent Skills 兼容客户端可加载的技能目录，然后提出具体任务，例如：“审查我的 Stripe 订阅集成，检查 Checkout Sessions、automatic_tax、Webhook 和受限 API 密钥的使用。”回答集成问题或编写代码前，应先阅读对应的参考文件。最新 Stripe API 版本为 2026-06-24.dahlia；除非用户另有指定，应使用最新 API 版本和 SDK。
对比同类
技能明确区分 Checkout Sessions 与 PaymentIntents：一次性付款推荐 Checkout Sessions；自定义嵌入式支付界面推荐 Checkout Sessions 搭配 Payment Element；保存支付方式则推荐 Setup Intents。它还要求除 Terminal 外不要传入 payment_method_types，以启用动态支付方式。