用途：这是一份参考性技能（skill），提炼 Stripe 的 JSON HTTP API 设计约定，共 52 条可执行规则，分 8 类并按“错误决策向后级联的不可逆程度”排序。适用场景包括：设计新的 JSON HTTP API 或已有 API 的新端点；评审 API 设计提案、OpenAPI 规范或增改端点的 PR；排查因 API 形状不当引发的客户端缺陷；审计命名一致性、错误形状统一性与兼容性风险；产出 API 设计报告（Critical/Warning/Suggestion/Positive）；在两套设计间做选择时寻找权威依据；入门 API 设计。触发词含 API design、OpenAPI、endpoint、schema、webhook、idempotency、pagination、API versioning 及 YAML/JSON 规范文件审阅。
主要能力（类别与优先级）：1 资源建模与标识符（Critical，resource- 前缀）：预定义前缀字符串 ID、只读 object 判别字段、不透明 ID（≤255 字符）、Unix 秒时间戳、ISO 8601 纯日期、生日用 {day,month,year} 哈希、金额用整数最小单位、货币放独立字段而非字段名、高精度小数用 decimal 后缀字符串。2 URL 结构与 HTTP 语义（Critical，url-）：集合复数化、类型单数化、用 POST 更新（不用 PUT/PATCH）、非 CRUD 动作用祈使式子路径、每请求一个对象不设批量端点、版本同时放路径与 Stripe-Version 头、复杂查询用专用 /search 端点。3 请求与响应格式（High，format-）：接受表单编码请求并始终返回 JSON、嵌套字段用中括号记法、列表用 {object,url,has_more,data} 信封、游标分页（starting_after/ending_before）而非偏移量、用 has_more 布尔值不返回总数、用 expand[] 单次往返展开关联对象、支持点号嵌套展开（最深 4 层）。4 错误与状态码（High，error-）：失败包裹在顶层 error 对象、固定的小型 type 枚举、message 必填而 code 可选、错误码用小写 snake_case、type 与 HTTP 状态码一致映射、每个错误附 doc_url 与请求 ID。5 幂等与安全重试（High，idem-）：所有变更请求接受 Idempotency-Key 头、键按账户隔离、键保留 24 小时并在 72 小时回收、键被不同参数复用时返回 409、多步操作使用恢复点。6 版本与向后兼容（High，ver-）：用日期版本（YYYY-MM-DD）而非 v1/v2/v3、账户固定到首次请求版本、明确何为兼容性变更、用版本变更模块封装破坏性变更、要求客户端容忍未知字段/事件/枚举。7 命名、多态与元数据（Medium-High，naming-）：线上标识符统一 snake_case、美式英语拼写（canceled）、名称简洁无歧义且不以数字开头、多态用 type 字段与同级对象区分、提供有严格限制的 metadata 透传、布尔用过去式或形容词、新状态字段优先枚举而非布尔。8 认证、Webhook 与搜索（Medium-High，ops-）：API 密钥带范围与模式前缀（sk_live、pk_test_、rk_）、仅 HTTPS 且密钥作 Basic Auth 用户名、多租户用专用 On-Behalf-Of 头、Webhook 事件用 {id,object,type,data,created} 固定信封、事件类型命名 <resource>.<past_tense_action>、用 HMAC 与时间戳容差签名、声明至少一次投递且处理器按 event.id 去重。
使用方式：针对聚焦问题直接跳到相关规则（如字段该用布尔还是枚举，可查 naming-enums-over-booleans）；完整审计则自上而下遍历类别，顺序对应 Stripe 的设计优先级；产出结构化报告时按规则 slug 引用。参考文件含 references/_sections.md（类别定义与排序）、assets/templates/_template.md（新增规则模板）、metadata.json（版本与参考 URL）、gotchas.md（应用规则时发现的失败点）。
限制：资料未提供各规则进一步细节、示例代码内容、收费或授权方式，暂未提供。规则为通用 JSON HTTP API 设计建议，非强制标准；具体采纳需结合自身项目评估。