用途
create-api-design 用于从功能规格或资源描述出发，设计一份完整、可投入生产的 API 设计文档。当用户提出设计 API、创建端点、定义 API 契约或规划 API 资源时使用。输出内容涵盖端点、数据结构、错误契约、分页、认证、限流和缓存，并要求与项目中已有的 API 模式保持一致。
主要能力
- 读取并匹配现有 API 模式：读取 .chalk/docs/engineering/ 下的现有 API 设计文档、架构文档、认证模式与中间件、错误处理约定；若无文档，则扫描代码库中的路由定义来推断模式。
- 扫描代码库中的当前约定：使用 Grep 查找路由定义（如 router.get、app.post、@GetMapping、@api_view）、错误响应结构、分页模式（游标或偏移、参数名）、认证中间件用法（JWT、API key、OAuth scopes）、响应包裹模式（是否包裹为 { data, meta } 或返回原始数据）。
- 确定下一个文档编号：列出 .chalk/docs/engineering/ 中匹配 api_design.md 的文件，取最大编号加 1。
- 明确资源与操作：从参数和对话上下文中识别资源（名词而非动词）、所需操作（CRUD 及领域特定动作）、API 消费方（前端、移动端、第三方、内部服务）、认证要求（公开、需认证、基于角色、基于 scope）。若资源边界不清晰，会向用户请求澄清。
- 设计端点：严格遵循 REST 约定，使用复数名词路径、嵌套资源表示归属、嵌套最多 2 层、正确使用 HTTP 方法、集合端点使用查询参数进行过滤/排序/分页、路径参数仅用于资源标识符。
- 定义 schema：为每个端点定义请求体 JSON schema（POST/PUT/PATCH）、响应体 JSON schema（所有方法）、查询参数 schema（GET 集合端点），字段命名保持一致（camelCase 或 snake_case，匹配现有约定）。
- 定义错误契约：设计跨所有端点一致使用的错误响应结构，包含校验错误、业务逻辑错误和系统错误。
- 写入文档：保存到 .chalk/docs/engineering/<n>api_design<resource_slug>.md。
- 确认：告知用户 API 设计已创建、其路径以及所定义端点的摘要。
使用方式
该技能以工作流方式运行：先读取现有 API 模式，再扫描代码库中的当前约定，确定下一个文档编号，明确资源与操作，设计端点，定义 schema，定义错误契约，写入文档，最后确认。文件名约定为 <number>api_design<snake_case_resource>.md，例如 4_api_design_user_profiles.md、8_api_design_billing_subscriptions.md、11_api_design_notification_preferences.md。
生成的 API 设计文档包含以下结构：标题与最后更新日期、概述、Base URL、认证（含端点模式与所需认证/scope/角色的表格）、端点（集合资源与单个资源的列表、创建、获取、更新、删除）、请求/响应 schema、错误契约（含校验错误示例与错误码表）、分页策略（偏移分页与游标分页）、限流（含分层限流表与限流响应头）、缓存（含缓存策略表与响应头）、示例请求（cURL 与 JavaScript Fetch）。
文档还包含 URL 设计规则、字段命名规则和反模式说明。URL 设计规则要求：使用复数名词、kebab-case、URL 中不含动词（非 CRUD 动作可用 POST，但优先用 PATCH 做状态转换）、最多 2 层嵌套、一致的 ID 格式（前缀 ID 或 UUID，不用自增整数）、URL 中带版本（如 /api/v1/）。字段命名规则要求：匹配现有项目约定且不混用、布尔字段以 is_/has_/can_ 为前缀、时间戳以 _at 为后缀、计数以 _count 为后缀、外键 ID 以 _id 为后缀。
反模式部分列出了应避免的做法：错误结构不一致、无分页、RPC 风格 URL、未指定认证、破坏现有命名约定、暴露内部 ID、无版本策略、状态码不一致。
适用场景
适用于需要从功能规格设计 REST 或 GraphQL API 的工程场景，包括创建端点、定义 API 契约、规划 API 资源。适合需要与项目现有 API 模式保持一致、并产出结构化设计文档的团队。
限制
资料未提供该技能的具体安装命令、收费方式、价格、支持平台或运行环境要求。资料未说明其是否支持除 REST 与 GraphQL 之外的其他 API 风格。资料未提供该技能的实际效果验证信息。