使用 AAS 的 api-designer Skill 从零生成生产级 REST API 端点规格【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文以 agentic-awesome-skillsAAS仓库中收录的社区技能api-designer为对象系统讲解如何让 Agent 为任意业务系统或领域生成完整、可落地的 REST API 端点规格。读完本文你将掌握该技能的使用时机、两档输出模式、逐资源分组的端点设计规范、分页封装、认证选型与后续文档生成流程并了解它在本仓库中的注册信息与配套技能生态可直接在 Claude / Agent 工作流中复现整套 API 设计能力。技能概览这是什么、何时启用api-designer是一条以SKILL.md为核心的 Agent 技能位于 plugins/agentic-awesome-skills-claude/skills/api-designer/SKILL.md同名副本也收录于 skills/api-designer/SKILL.md。其 frontmatter 明确声明了它的职责nameapi-designerdescription为任何用户描述的系统或领域生成完整、生产就绪的 REST API 端点规格Generates complete, production-ready REST API endpoint specifications for any system or domain the user describesrisksafe无破坏性操作的技能source / source_repo上游来自LambdaTest/agent-skills仓库的api-skill/api-designer属社区community来源采用 MIT 许可证在 AAS 的集中式目录 data/catalog.json第 3541–3570 行中该技能被注册为id / canonical_idapi-designercategorybackendtagsapi、designertriggersapi、designer、rest、endpoint、specifications等关键词pathskills/api-designer/SKILL.md也就是说当用户提出与 API 设计、API 端点、REST API、API URL 相关的问题或说出我需要哪些端点为一个系统设计 API这类表述时该技能即应被触发。何时使用技能自身的When to Use段落给出了明确的启用条件只要用户要求为任意系统或领域生成完整、生产就绪的 REST API 端点规格就应启用典型触发句式包括what endpoints do I need for...我需要为……设计哪些端点design an API for...为……设计一个 API任何涉及 API 设计、API 端点、REST API、API URL 的请求启用后Agent 将以专家 API 架构师expert API architect的角色展开工作。两档输出模式Endpoints Only 与 Detail Design技能的第一步不是直接输出而是先向用户确认输出颗粒度——除非用户在需求中已经主动说明了细节。可选项只有两个模式输出内容Endpoints Only只输出端点清单方法 路径不展开细节Detail Design按技能定义的结构输出完整设计Headers、请求体、响应、错误码等这一设计既避免了小需求被过度设计也保证了复杂系统能拿到可落地的完整规格是技能按需输出、不做无用功的体现。标准输出结构逐资源分组展开无论采用哪种模式技能的 Output Format 都要求先把所有端点一次性列出然后按每个资源组resource group展开详细设计。每个资源组的展开必须严格遵循以下结构资源组模板### RESOURCE NAME #### METHOD /path/to/endpoint 对该端点功能不超过两行的简短描述。 **Headers** | Header | Value | Required | |--------|-------|----------| | Content-Type | application/json | Yes | | Authorization | Bearer token | Yes/No | | X-Api-Key | api-key | Yes/No | | *(按需补充其他 header)* | | | **Request Body** *(GET/DELETE 无请求体时省略)* json { field: type — description, field2: type — description }Success Response—STATUS_CODE Description{ field: value or type }Error Codes| Code | Meaning | |------|---------| |400| Bad Request — invalid or missing fields | |401| Unauthorized — missing or invalid token | |403| Forbidden — insufficient permissions | |404| Not Found | |409| Conflict — e.g. duplicate resource | |422| Unprocessable Entity — validation failed | |500| Internal Server Error |要点解读 - **Headers 表**默认给出 Content-Type: application/json 与两种主流认证载体Authorization: Bearer token、X-Api-KeyRequired 列明确标注是否必填 - **Request Body** 用注释式写法字段: 类型 — 描述给出真实感十足的 JSON 骨架便于读者直接改造成真实请求 - **Success Response** 必须携带 HTTP 状态码例如 200 OK、201 Created - **Error Codes** 提供 7 个通用错误码的语义对照400/401/403/404/409/422/500但技能要求**按端点选取相关子集**而不是机械地把 7 个全部粘贴见下方规则第 7 条。 ## 十项输出规则RESTful 约定与生产细节 技能的 Rules for Output 是该技能方法论的核心共 10 条务必完整落实 1. **覆盖系统全部主要资源**即使输入没有明确列举也要根据系统语义推断出资源 2. **始终包含 CRUD**在适用场景下必须包含 Create、Read、Update、Delete 四类操作并补充领域特有动作 3. **遵循 RESTful 约定**集合用复数名词/hotels关系用嵌套路径/hotels/{id}/rooms 4. **认证**受保护路由默认使用 Bearer tokenJWT第三方集成场景补充 API key header公开端点需明确标注 5. **请求体**展示包含字段名、类型、简短描述的贴近真实的 JSON并在注释中区分必填与可选字段 6. **响应**展示带真实字段的成功响应形状且**始终携带 HTTP 状态码** 7. **错误码**按端点列出相关子集运用判断力不要总是粘贴全部 7 个 8. **分页**列表端点必须包含查询参数page、limit、sort、filter响应包裹在分页信封中 9. **版本化**默认所有路径以 /api/v1/ 为前缀除非用户另有指定 10. **按资源分组**将端点按资源归类例如 Authentication、Hotels、Rooms、Bookings、Payments、Reviews。 这 10 条规则共同保证了输出的规格在风格统一、结构完整的同时具备直接进入开发评审和编码的可用性。 ## 列表端点的分页信封 对于返回集合的列表端点技能强制要求使用统一的分页信封Pagination Envelope而不是直接返回裸数组。标准形状如下 json { data: [...], pagination: { total: 100, page: 1, limit: 20, totalPages: 5 } }字段语义data本页数据数组pagination.total资源总量pagination.page当前页码从 1 开始pagination.limit每页条数pagination.totalPages总页数由total / limit向上取整得出。分页信封是技能第 8 条规则的具体载体让前端分页组件和后端游标实现都有据可依。通用认证模式选型表技能根据调用场景给出了 5 种认证方式的选型建议场景认证方式面向用户的 AppAuthorization: Bearer JWT服务端到服务端X-Api-Key: key公开端点无需认证 header管理端点Bearer token 角色校验非管理员返回403OAuth 流程见/auth/oauth/*端点设计时按上下文选择最合适的模式并在端点规格中明确标注公开/受保护属性。领域参考速查表技能内置了两份参考资料以加速生成、避免遗漏明显的资源references/domains.md按领域酒店预订、电商、社交媒体等预置资源清单供生成前快速检索references/testmu_example.md用于生成 API 结构并给出示例的参考。需要说明的是在本仓库当前的api-designer技能包中实际只包含 SKILL.md 一个文件上述两份参考文件属于上游LambdaTest/agent-skills技能的引用设计若需使用可结合上游仓库或自行按领域沉淀等价清单。完成设计后的下一步联动文档生成技能在交付 API 设计后不会直接结束而是主动询问Would you like me to generate API documentation for this design? (yes/no)若用户回答yes技能定义了一条清晰的决策链检查已安装技能列表中是否存在API Documentation技能存在读取并遵循该技能指令以当前 API 设计输出作为输入交付纯文本文档不存在告知用户API Documentation 技能未安装可先安装再重跑或立即生成基础文档若用户选择立即生成则基于上述设计产出覆盖端点、参数、响应的基础纯文本文档若用户选择先安装则引导其添加技能并重启。若用户回答no则任务就此结束。这条联动设计与本仓库中的配套技能形成闭环例如 skills/api-documentation/SKILL.md 就定义了API Discovery → OpenAPI Specification → Developer Guide → Code Examples → Interactive Docs → Documentation Site → Maintenance的七阶段文档工作流并引用了api-documenter、api-design-principles、openapi-spec-generation等技能——API 设计完成后即可无缝衔接到 OpenAPI 规格生成与开发者指南编写阶段。这也是 AAS 目录体系如 data/catalog.json 中同属backend/ 文档类的技能注册所支撑的技能协作范式。语气与篇幅控制为了让输出全面但易扫读技能对表达风格有明确要求善用表格与代码块所有 Header、错误码、认证选型等内容一律用表格呈现JSON 一律用代码块补充 Base URL 与认证摘要在列出全部端点后在顶部或底部补充一段简短的Base URL Auth Summary大系统分块处理若系统资源组超过 8 个主动提议分段输出或先聚焦子集按需供给主动询问用户希望在响应中看到哪些内容如 Headers、Status Codes仅提供被选择的部分。使用边界与安全提示技能自带的 Limitations 段落划清了使用边界也是落地时的安全护栏仅在任务与技能上游来源及本地项目上下文明确匹配时使用在应用变更前必须验证命令、生成代码、依赖、凭据与外部服务行为不得将示例当作环境专属测试、安全评审或用户对破坏性/高成本操作的批准的替代品。这些约束与 AAS 社区技能的risk: safe分级、以及 data/catalog.json 中对技能来源source_type: community与许可证license: MIT的登记相互印证——技能可以作为高效起点但生产落地仍需开发者自己的验证与评审。总结一条可复用的 API 设计流水线api-designer技能本质上把资深 API 架构师的思考过程固化为可复现的模板触发识别 → 确认输出粒度 → 先列全端点 → 按资源分组逐项展开Headers/请求体/成功响应/错误码→ 落实 RESTful 与分页/版本化约定 → 选型认证模式 → 询问是否联动文档生成。在 agentic-awesome-skills 中它既可以直接作为独立技能在 skills/api-designer/SKILL.md 中被 Agent 加载也通过 data/catalog.json 注册进统一目录、与api-documentation等配套技能协同覆盖从需求描述到端点规格再到API 文档的完整链路。对任何需要快速产出可评审 REST API 规格的团队来说这是一条开箱即用、且可依据本文模板人工复核的高效路径。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/21 3:29:41 · 阅读 1.2k 使用 AAS 的 api-designer Skill 从零生成生产级 REST API 端点规格
使用 AAS 的 api-designer Skill 从零生成生产级 REST API 端点规格【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills导读本文以 agentic-awesome-skillsAAS仓库中收录的社区技能api-designer为对象系统讲解如何让 Agent 为任意业务系统或领域生成完整、可落地的 REST API 端点规格。读完本文你将掌握该技能的使用时机、两档输出模式、逐资源分组的端点设计规范、分页封装、认证选型与后续文档生成流程并了解它在本仓库中的注册信息与配套技能生态可直接在 Claude / Agent 工作流中复现整套 API 设计能力。技能概览这是什么、何时启用api-designer是一条以SKILL.md为核心的 Agent 技能位于 plugins/agentic-awesome-skills-claude/skills/api-designer/SKILL.md同名副本也收录于 skills/api-designer/SKILL.md。其 frontmatter 明确声明了它的职责nameapi-designerdescription为任何用户描述的系统或领域生成完整、生产就绪的 REST API 端点规格Generates complete, production-ready REST API endpoint specifications for any system or domain the user describesrisksafe无破坏性操作的技能source / source_repo上游来自LambdaTest/agent-skills仓库的api-skill/api-designer属社区community来源采用 MIT 许可证在 AAS 的集中式目录 data/catalog.json第 3541–3570 行中该技能被注册为id / canonical_idapi-designercategorybackendtagsapi、designertriggersapi、designer、rest、endpoint、specifications等关键词pathskills/api-designer/SKILL.md也就是说当用户提出与 API 设计、API 端点、REST API、API URL 相关的问题或说出我需要哪些端点为一个系统设计 API这类表述时该技能即应被触发。何时使用技能自身的When to Use段落给出了明确的启用条件只要用户要求为任意系统或领域生成完整、生产就绪的 REST API 端点规格就应启用典型触发句式包括what endpoints do I need for...我需要为……设计哪些端点design an API for...为……设计一个 API任何涉及 API 设计、API 端点、REST API、API URL 的请求启用后Agent 将以专家 API 架构师expert API architect的角色展开工作。两档输出模式Endpoints Only 与 Detail Design技能的第一步不是直接输出而是先向用户确认输出颗粒度——除非用户在需求中已经主动说明了细节。可选项只有两个模式输出内容Endpoints Only只输出端点清单方法 路径不展开细节Detail Design按技能定义的结构输出完整设计Headers、请求体、响应、错误码等这一设计既避免了小需求被过度设计也保证了复杂系统能拿到可落地的完整规格是技能按需输出、不做无用功的体现。标准输出结构逐资源分组展开无论采用哪种模式技能的 Output Format 都要求先把所有端点一次性列出然后按每个资源组resource group展开详细设计。每个资源组的展开必须严格遵循以下结构资源组模板### RESOURCE NAME #### METHOD /path/to/endpoint 对该端点功能不超过两行的简短描述。 **Headers** | Header | Value | Required | |--------|-------|----------| | Content-Type | application/json | Yes | | Authorization | Bearer token | Yes/No | | X-Api-Key | api-key | Yes/No | | *(按需补充其他 header)* | | | **Request Body** *(GET/DELETE 无请求体时省略)* json { field: type — description, field2: type — description }Success Response—STATUS_CODE Description{ field: value or type }Error Codes| Code | Meaning | |------|---------| |400| Bad Request — invalid or missing fields | |401| Unauthorized — missing or invalid token | |403| Forbidden — insufficient permissions | |404| Not Found | |409| Conflict — e.g. duplicate resource | |422| Unprocessable Entity — validation failed | |500| Internal Server Error |要点解读 - **Headers 表**默认给出 Content-Type: application/json 与两种主流认证载体Authorization: Bearer token、X-Api-KeyRequired 列明确标注是否必填 - **Request Body** 用注释式写法字段: 类型 — 描述给出真实感十足的 JSON 骨架便于读者直接改造成真实请求 - **Success Response** 必须携带 HTTP 状态码例如 200 OK、201 Created - **Error Codes** 提供 7 个通用错误码的语义对照400/401/403/404/409/422/500但技能要求**按端点选取相关子集**而不是机械地把 7 个全部粘贴见下方规则第 7 条。 ## 十项输出规则RESTful 约定与生产细节 技能的 Rules for Output 是该技能方法论的核心共 10 条务必完整落实 1. **覆盖系统全部主要资源**即使输入没有明确列举也要根据系统语义推断出资源 2. **始终包含 CRUD**在适用场景下必须包含 Create、Read、Update、Delete 四类操作并补充领域特有动作 3. **遵循 RESTful 约定**集合用复数名词/hotels关系用嵌套路径/hotels/{id}/rooms 4. **认证**受保护路由默认使用 Bearer tokenJWT第三方集成场景补充 API key header公开端点需明确标注 5. **请求体**展示包含字段名、类型、简短描述的贴近真实的 JSON并在注释中区分必填与可选字段 6. **响应**展示带真实字段的成功响应形状且**始终携带 HTTP 状态码** 7. **错误码**按端点列出相关子集运用判断力不要总是粘贴全部 7 个 8. **分页**列表端点必须包含查询参数page、limit、sort、filter响应包裹在分页信封中 9. **版本化**默认所有路径以 /api/v1/ 为前缀除非用户另有指定 10. **按资源分组**将端点按资源归类例如 Authentication、Hotels、Rooms、Bookings、Payments、Reviews。 这 10 条规则共同保证了输出的规格在风格统一、结构完整的同时具备直接进入开发评审和编码的可用性。 ## 列表端点的分页信封 对于返回集合的列表端点技能强制要求使用统一的分页信封Pagination Envelope而不是直接返回裸数组。标准形状如下 json { data: [...], pagination: { total: 100, page: 1, limit: 20, totalPages: 5 } }字段语义data本页数据数组pagination.total资源总量pagination.page当前页码从 1 开始pagination.limit每页条数pagination.totalPages总页数由total / limit向上取整得出。分页信封是技能第 8 条规则的具体载体让前端分页组件和后端游标实现都有据可依。通用认证模式选型表技能根据调用场景给出了 5 种认证方式的选型建议场景认证方式面向用户的 AppAuthorization: Bearer JWT服务端到服务端X-Api-Key: key公开端点无需认证 header管理端点Bearer token 角色校验非管理员返回403OAuth 流程见/auth/oauth/*端点设计时按上下文选择最合适的模式并在端点规格中明确标注公开/受保护属性。领域参考速查表技能内置了两份参考资料以加速生成、避免遗漏明显的资源references/domains.md按领域酒店预订、电商、社交媒体等预置资源清单供生成前快速检索references/testmu_example.md用于生成 API 结构并给出示例的参考。需要说明的是在本仓库当前的api-designer技能包中实际只包含 SKILL.md 一个文件上述两份参考文件属于上游LambdaTest/agent-skills技能的引用设计若需使用可结合上游仓库或自行按领域沉淀等价清单。完成设计后的下一步联动文档生成技能在交付 API 设计后不会直接结束而是主动询问Would you like me to generate API documentation for this design? (yes/no)若用户回答yes技能定义了一条清晰的决策链检查已安装技能列表中是否存在API Documentation技能存在读取并遵循该技能指令以当前 API 设计输出作为输入交付纯文本文档不存在告知用户API Documentation 技能未安装可先安装再重跑或立即生成基础文档若用户选择立即生成则基于上述设计产出覆盖端点、参数、响应的基础纯文本文档若用户选择先安装则引导其添加技能并重启。若用户回答no则任务就此结束。这条联动设计与本仓库中的配套技能形成闭环例如 skills/api-documentation/SKILL.md 就定义了API Discovery → OpenAPI Specification → Developer Guide → Code Examples → Interactive Docs → Documentation Site → Maintenance的七阶段文档工作流并引用了api-documenter、api-design-principles、openapi-spec-generation等技能——API 设计完成后即可无缝衔接到 OpenAPI 规格生成与开发者指南编写阶段。这也是 AAS 目录体系如 data/catalog.json 中同属backend/ 文档类的技能注册所支撑的技能协作范式。语气与篇幅控制为了让输出全面但易扫读技能对表达风格有明确要求善用表格与代码块所有 Header、错误码、认证选型等内容一律用表格呈现JSON 一律用代码块补充 Base URL 与认证摘要在列出全部端点后在顶部或底部补充一段简短的Base URL Auth Summary大系统分块处理若系统资源组超过 8 个主动提议分段输出或先聚焦子集按需供给主动询问用户希望在响应中看到哪些内容如 Headers、Status Codes仅提供被选择的部分。使用边界与安全提示技能自带的 Limitations 段落划清了使用边界也是落地时的安全护栏仅在任务与技能上游来源及本地项目上下文明确匹配时使用在应用变更前必须验证命令、生成代码、依赖、凭据与外部服务行为不得将示例当作环境专属测试、安全评审或用户对破坏性/高成本操作的批准的替代品。这些约束与 AAS 社区技能的risk: safe分级、以及 data/catalog.json 中对技能来源source_type: community与许可证license: MIT的登记相互印证——技能可以作为高效起点但生产落地仍需开发者自己的验证与评审。总结一条可复用的 API 设计流水线api-designer技能本质上把资深 API 架构师的思考过程固化为可复现的模板触发识别 → 确认输出粒度 → 先列全端点 → 按资源分组逐项展开Headers/请求体/成功响应/错误码→ 落实 RESTful 与分页/版本化约定 → 选型认证模式 → 询问是否联动文档生成。在 agentic-awesome-skills 中它既可以直接作为独立技能在 skills/api-designer/SKILL.md 中被 Agent 加载也通过 data/catalog.json 注册进统一目录、与api-documentation等配套技能协同覆盖从需求描述到端点规格再到API 文档的完整链路。对任何需要快速产出可评审 REST API 规格的团队来说这是一条开箱即用、且可依据本文模板人工复核的高效路径。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,600 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/GitHub_Trending/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考