supercent-io/api-design Skill 技能

supercent-io-api-design 是一款面向 REST 与 GraphQL 接口设计的 Agent Skill。它把原本散落在各团队的「API 设计规范」——资源命名、HTTP 方法与状态码、请求/响应/错误格式、分页/过滤/排序、版本管理与 OpenAPI 文档——打包成 Claude / Codex / Claude Code 三个 Agent 都能直接套用的标准化工作流，让 AI 在动手写代码之前先把接口契约设计清楚。

核心能力：

• REST 资源建模：引导 Agent 按 REST 风格进行资源命名、HTTP 方法选择与状态码匹配，避免动词 / 名词混用。
• 统一请求响应规范：定义统一的请求字段、响应结构与错误格式，跨服务保持一致，便于前端与客户端团队接入。
• 分页过滤排序：覆盖 limit/offset、cursor、field selection、batch operation 等常见分页与批处理模式，避免每个端点重新设计。
• 认证与版本管理：对比 OAuth、JWT、API Key 等常见认证选项，提供 URL-based / Header-based 等主流版本管理实践。
• OpenAPI 3.0 契约：按 OpenAPI 3.0 规范生成 endpoint、schema、认证、错误与版本号结构，方便接入 Swagger / Redoc 文档站。
• REST vs GraphQL 选型：当数据形态高度嵌套且前端多变时，给出 GraphQL 替代方案，并分析缓存、鉴权、版本管理上的取舍。

安装配置：

• 通过 npx skillstore add supercent-io/api-design 一键安装到 Claude / Codex / Claude Code Agent 环境。
• 建议在团队 .claude/skills/ 或 .codex/skills/ 目录同步启用，确保整个工程团队用同一规范设计接口。
• 如团队使用 Stoplight、Redocly、SwaggerHub 等文档平台，可在 prompt 中说明目标平台，Agent 会按对应格式生成 OpenAPI 文档片段。

使用步骤：

1. 梳理业务资源：列出所有需要暴露的业务对象及其关系，区分主资源、子资源、关联资源。
2. 设计资源路径：按「复数名词 + HTTP 方法」生成 RESTful 路径，并在每个方法上绑定合适的 2xx/4xx/5xx 状态码。
3. 定义请求响应：统一请求 query / body / header 字段，定义响应结构与错误码体系，确保跨服务一致。
4. 规划分页与过滤：对所有列表类端点统一规定分页、过滤、排序、字段选择与批处理模式。
5. 起草 OpenAPI 契约：用 OpenAPI 3.0 描述 endpoints、schemas、认证、错误与版本管理，并附最小可运行示例。
6. REST / GraphQL 选型评估：对关联数据密集、客户端多端的场景，输出 REST 与 GraphQL 的取舍分析，明确推荐方案。

适用场景：

• 新 SaaS / 微服务项目立项初期，从 0 设计对外 API 契约。
• 已有 API 治理混乱（错误码不一致、版本号乱跳、文档缺失）需要系统性重构。
• 准备把内部 API 开放给第三方开发者，需要 OpenAPI 文档与统一错误码。
• 团队从 REST 迁移到 GraphQL，或在新老端点间做技术选型决策。

工作原理： Skill 加载后会在 Agent 推理上下文中注入「API 设计规范 + 检查清单 + OpenAPI 模板」。Agent 在收到用户的「设计一个 X 资源的 API / 评估 REST vs GraphQL」指令时，会按清单顺序输出资源模型、端点表、错误码矩阵与 OpenAPI 片段。它的设计目标是「让 AI 输出可直接被后端工程团队评审与落地的 API 契约」，而不是替代威胁建模与安全审计。

适用人群：

• 后端架构师、API 平台工程师、技术负责人。
• 全栈工程师、独立开发者、独立 SaaS 创业者。
• OpenAPI / Stoplight / Redocly 文档生态的使用者。
• 任何需要把零散接口经验沉淀为团队规范的工程团队。

官方链接：

• 技能主页：https://skillstore.io/skills/supercent-io-api-design
• 源码仓库：https://github.com/supercent-io/skills-template/tree/main/.agent-skills/api-design/
• 安装命令：npx skillstore add supercent-io/api-design