稳定接口设计指南
帮助工程团队设计稳定、清晰且难以误用的 API 与模块接口。
内容聚焦接口设计，没有恶意行为、凭据窃取、隐蔽外传或高风险自动化操作；也强调边界验证和不暴露内部错误。扣分原因是未说明权限最小化、用户确认、敏感数据处理、依赖安全、外部副作用、回滚或数据流披露；来源归属仅能由仓库 README/LICENSE 间接确认，且发布者未被验证。
章节结构和建议基本一致，包含契约、错误语义、验证、兼容性及检查清单；仓库 CI 对整体技能结构和评估脚本有验证。扣分原因是目标技能没有专属可执行测试，示例含省略实现，异常输入、失败反馈和关键路径复现不足；静态评估不超过 10 分。
前置描述明确指向 API、模块边界、组件 props、REST/GraphQL 和前后端边界，触发条件较清楚。扣分原因是未明确非适用场景、输入输出边界或不同技术栈的适配限制，也没有中文支持或中国大陆网络可达性说明。
文档有 frontmatter、Overview、When to Use、原则、模式、反例表、Red Flags 和 Verification，示例较丰富；README 提供安装说明，仓库提供 MIT 许可证、维护者和 CI。扣分原因是目标文件缺少版本、变更记录、维护责任和更新路径的直接说明，安装依赖、FAQ、已知限制及故障排查不足。
内容可直接作为 API 设计检查框架，涵盖契约优先、错误一致性、边界验证、分页、兼容性和命名规范，核心任务目标明确。扣分原因是没有针对真实项目的完整输出模板、代表性产物或执行证据，仍需代理结合项目上下文判断；按静态校准不超过 7 分。
目标技能包含可审计的原则、代码示例和末尾检查清单，仓库 CI 也显示存在全局技能验证和评估运行步骤。扣分原因是没有目标技能专属测试覆盖、第三方来源或多源交叉佐证，且静态读取无法确认实际执行结果；因此仅给有限证据分。
- 这是静态源文件审查，未执行示例、CI 或评估脚本；不要将仓库级 CI 视为该技能关键路径已验证。
- 使用该技能设计真实接口时，仍需补充认证授权、敏感数据、速率限制、幂等性、审计、回滚和兼容性策略。
- 发布者身份未通过 FollowSkills 企业精选注册表验证，应在采用前独立核验来源和维护状态。
- 文档未提供中文或中国大陆网络环境适配说明。
这个 Skill 能做什么，适合哪些场景？
这是 addyosmani/agent-skills 仓库中的一个独立技能，专注于 API、模块边界、组件属性和前后端契约设计。它采用契约优先、统一错误语义、边界验证和向后兼容等原则，并涵盖 REST、GraphQL 及 TypeScript 接口模式。技能还使用 Hyrum 定律和单版本规则提醒团队管理可观察行为与版本复杂度。它适合需要设计或修改公共接口的开发者，但提供的材料没有展示该技能的自动化测试或运行时验证结果。
指导用户先定义输入、输出和错误契约，再设计 REST 或 GraphQL 接口、模块边界及组件属性；给出分页、过滤、PATCH 局部更新、命名和子资源路径示例；说明应在 API 路由、表单、第三方响应和环境变量等系统边界执行验证；建议使用判别联合、输入输出分离和品牌类型；最后通过接口 schema、错误格式、分页、命名、兼容性和文档清单进行检查。
- 后端开发者设计新的 REST 任务 API，需要统一资源路径、状态码、错误响应和分页格式。
- 前后端团队建立共享类型契约，明确输入对象与服务端生成输出字段。
- TypeScript 工程师为不同状态或不同 ID 类型建模，避免调用方误传参数。
- 维护者修改已有公共接口，希望通过增加可选字段减少对现有消费者的破坏。
- 团队定义模块或组件边界，需要明确哪些行为会成为长期契约。
这个 Skill 有哪些优点和局限？
- 覆盖 REST、GraphQL、TypeScript、模块边界和组件属性等多种接口场景。
- 提供可直接采用的错误响应、分页、过滤、PATCH 和命名示例。
- 强调向后兼容、边界验证和可验证的设计检查清单。
- SKILL.md 仅使用标准 name 和 description 前置字段，没有显示平台专属扩展。
- 提供的材料未展示该技能的自动化测试套件或实际运行结果。
- 内容主要是设计指导，不包含生成、部署或运行 API 的脚本。
- 没有给出针对具体框架、数据库或 API 网关的实现步骤。
如何安装这个 Skill？
该技能位于仓库的 skills/api-and-interface-design/SKILL.md。安装整个技能集合可执行：npx skills add addyosmani/agent-skills。README 说明该仓库包含 24 个技能，也提供按名称安装单个技能的命令格式：npx skills add addyosmani/agent-skills --skill api-and-interface-design。
如何使用这个 Skill？
在支持 Agent Skills 的客户端中安装后，在设计或修改 API、模块边界、组件属性或其他公共接口时触发它。例如："设计一个任务 REST API，先定义输入输出契约、统一错误格式、边界验证和分页方案。"具体客户端的自动触发细节未在该技能文件中单独说明。
这个 Skill 与同类方案有什么区别？
README 将 Superpowers 和 Matt Pocock's skills 列为可比较的替代方案，并链接到比较文档；提供的材料未包含该比较文档的具体结论。