CraftKit/plugins/dev/skills/design-api/SKILL.md

name, description

name	description
design-api	基于项目需求、现有契约和对应版本官方规范设计或评审 HTTP API。适用于资源边界、方法、状态码、请求响应、兼容和 OpenAPI 契约；前后端字段对接、后端整体设计或直接编码不应触发。

API 设计

先确认项目协议、OpenAPI 版本、已有接口风格和兼容边界，再形成可实现、可验证的契约。

工作流

1. 读取 .craftkit/project.json、适用规范、现有契约和调用方证据。
2. 明确资源、动作、幂等性、认证授权、输入、输出和错误语义。
3. 方法、状态码、缓存、条件请求和重试语义以 官方来源 及项目版本为依据。
4. 输出路径与方法、参数位置、请求响应模型、错误、兼容、弃用和测试清单。
5. 默认在对话中输出；用户要求保存设计文档时读取 .craftkit/project.json 的 documents 配置，过程设计使用 workRoot，共享设计使用 designRoot，不改变接口自身的路径设计。

落盘前检索同主题的需求、设计、规范或知识，优先更新已有权威文档。共享长期文档新建或实质修改后按 .craftkit/standards/document-maintenance.md 更新审核状态；排版和错字修正不改变状态。rnrn写入后在 workRoot/<task>/task.json 登记本次创建、更新或引用的文档及 relationship；已有记录时保守合并。关联旧文档不转移所有权，也不产生删除权限；不修改项目级默认配置。 6. 未确认的业务规则和框架封装列为待确认，不生成实现代码。

项目规则高于公共建议；不得默认最新 OpenAPI 版本或把内部接口模式写成通用规则。