api-design-principles 是帮助 AI 设计和评审 REST、GraphQL 接口的 Skill。给它业务需求或现有接口规格，可以检查命名、数据结构、错误响应与版本演进，减少接入方反复猜规则。
例如同一套接口，有的列表叫 user，有的叫 products；出错有时返回文本，有时返回对象。单个接口也许能用，接到一起就增加判断成本。这份文档要求保持集合命名一致、使用合适的状态码，并为大列表安排分页。
接口结构也不必照抄数据库表。它应服务调用者的任务；GraphQL 则先设计类型和查询结构，再考虑取数效率、复杂度与逐步弃用旧字段。
对正在定接口规范的团队，它能把“以后再统一”的问题提前到实现前讨论。交付可以是一份调整后的规格及理由，而不只是生成几个路由。版本变化怎么通知和兼容，也需要从一开始纳入设计。