API 与命名空间设计规范
为 SkillHub 定义 REST API 约定、命名空间坐标、RBAC 角色与 OpenAPI 契约同步规则，确保后端一致性与可维护性。
证据显示技能明确描述了RBAC角色、CSRF防护、会话管理和OpenAPI同步等安全相关的API设计约定，但未提供具体的安全审计细节或执行验证。由于未验证发布者身份且未发现恶意行为或敏感数据处理不当，给予中等分数。扣分原因：缺少对权限细化、异常处理和数据流透明度的深入说明。
技能提供了清晰的触发条件和API端点列表，但未包含可执行的测试用例或错误处理示例。静态审查无法执行验证，因此可靠性较低。扣分原因：缺少失败反馈和质量保证证据。
技能定义了明确的适用范围和边界（如新增或修改REST API端点、命名空间坐标逻辑等），并提供了中文支持说明。但未充分展示非适用场景和触发条件的精确性。扣分原因：边界定义基本清晰，但环境适配证据有限。
文档结构清晰，包含触发条件、坐标系统、API设计、常见陷阱等章节，但缺少安装/依赖说明、版本更新日志和已知限制的详尽说明。扣分原因：信息架构完整但治理细节不足。
技能旨在指导API和命名空间设计，但其直接使用的输出（如代码或配置）未验证，边际价值证据有限。扣分原因：静态审查无法确认实际效果。
提供了一些CI和工作流文件作为证据，但静态审查无法独立验证其有效性。扣分原因：证据类型单一，缺少第三方验证。
- 静态审查无法验证实际操作结果，建议运行测试和CI流程以获得更高置信度。
- 发布者身份未验证，使用时应自行评估风险。
- 技能依赖外部服务和工具（如Docker、Kubernetes），在中国大陆可能需要配置镜像加速。
这个 Skill 能做什么，适合哪些场景？
该技能是 SkillHub 后端开发的参考规范，覆盖 REST API 设计、命名空间坐标系统、RBAC 角色、ClawHub 兼容层、OpenAPI 契约同步以及 CSRF/会话处理。它指导开发者在添加或修改 API 端点、调整命名空间或用户坐标逻辑、处理 ClawHub CLI 兼容、更新 OpenAPI 规范或新增治理端点时遵循既定模式。技能强调控制器仅负责传输，业务逻辑应放在领域或应用服务中，并强制所有 API 的用户身份使用字符串。
该技能提供了一套可读的规范文档，明确了：两层命名空间坐标（如 @global/my-skill、@team/my-skill）及命名空间状态和角色；平台级 SUPER_ADMIN 角色；ClawHub 兼容层的单 slug 映射规则；REST API 控制器的职责边界（仅传输，不包含业务逻辑）；请求/响应 DTO 模式及异常处理；CSRF 保护（XSRF-TOKEN cookie 与 X-XSRF-TOKEN 头）；会话认证与本地测试的 mock 认证（X-Mock-User-Id 头）；/.well-known/clawhub.json 发现端点；OpenAPI 类型生成命令（make generate-api 和 check-openapi-generated.sh 脚本）；版本化规则与常用 API 端点列表。
- 后端开发者添加或修改 REST API 端点时，遵循控制器职责划分和 DTO 模式。
- 开发者在实现命名空间或用户坐标逻辑时，参考坐标系统和 slug 验证规则。
- 需要维护 ClawHub CLI 兼容层的工程师，查阅兼容 slug 映射和冲突解决规则。
- 更新 OpenAPI 规范或生成的 TypeScript 类型时，运行 make generate-api 并提交变更。
- 新增管理或治理端点（如标签管理）时，确认 RBAC 权限和审计要求。
- 调试 CSRF 或会话认证流程时，参考 CSRF cookie 和 header 的规则及 mock 认证方法。
这个 Skill 有哪些优点和局限？
- 提供了完整的 API 设计约定，减少团队决策成本。
- 明确了 RBAC 角色和命名空间模型，有助于治理。
- 包含 ClawHub 兼容层映射，方便 CLI 集成。
- 强制 OpenAPI 契约同步，避免前后端类型漂移。
- 文档清晰，包含常见陷阱列表，便于规避错误。
- 该技能只是规范文档，不包含自动化脚本或验证工具，无法自动检查代码合规性。
- 如果 SkillHub 项目本身不使用，则适用性有限。
- 未提供测试用例或示例代码，仅有文字描述。
- 未覆盖错误处理的详细模式（如错误响应结构）。
如何安装这个 Skill？
该技能位于仓库的 .agents/skills/api-and-namespace-design/SKILL.md。若要使用，请克隆整个 iflytek/skillhub 仓库，或将 .agents/skills/api-and-namespace-design 文件夹复制到您 Agent 技能目录中。该技能仅作为文档规范，无独立安装包。
如何使用这个 Skill？
在开发 SkillHub 后端时，触发此技能：例如，当您添加新端点或修改命名空间逻辑时，可向 Agent 提问“参考 api-and-namespace-design 技能，设计新的认证端点”。Agent 将读取 SKILL.md，并应用其中的约定，如控制器传输层、DTO 模型、CSRF 要求和 OpenAPI 同步步骤。