这个 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？
- 静态审查无法验证实际操作结果，建议运行测试和CI流程以获得更高置信度。
- 发布者身份未验证，使用时应自行评估风险。
- 技能依赖外部服务和工具（如Docker、Kubernetes），在中国大陆可能需要配置镜像加速。
- Shell / 命令行
- 本地文件系统
Java 21DockerMaven
该技能位于仓库的 .agents/skills/api-and-namespace-design/SKILL.md。若要使用，请克隆整个 iflytek/skillhub 仓库，或将 .agents/skills/api-and-namespace-design 文件夹复制到您 Agent 技能目录中。该技能仅作为文档规范，无独立安装包。
tmp="$(mktemp -d)"
git clone --depth 1 https://github.com/iflytek/skillhub.git "$tmp"
mkdir -p ~/.claude/skills
cp -R "$tmp/.agents/skills/api-and-namespace-design" ~/.claude/skills/
rm -rf "$tmp"根据源仓库地址和 Skill 路径自动生成，只复制这个 Skill 的文件夹。如果上文有作者提供的安装方式，请优先按作者说明操作；想只在当前项目中使用，把 ~/.claude/skills 换成项目里的 .claude/skills。
如何使用这个 Skill？
安装后，把下面任意一句发给 Agent 即可触发：
- 参考 api-and-namespace-design 技能，设计新的认证端点
在开发 SkillHub 后端时，触发此技能：例如，当您添加新端点或修改命名空间逻辑时，可向 Agent 提问“参考 api-and-namespace-design 技能，设计新的认证端点”。Agent 将读取 SKILL.md，并应用其中的约定，如控制器传输层、DTO 模型、CSRF 要求和 OpenAPI 同步步骤。
这个 Skill 有哪些优点和局限？
- 提供了完整的 API 设计约定，减少团队决策成本。
- 明确了 RBAC 角色和命名空间模型，有助于治理。
- 包含 ClawHub 兼容层映射，方便 CLI 集成。
- 强制 OpenAPI 契约同步，避免前后端类型漂移。
- 文档清晰，包含常见陷阱列表，便于规避错误。
- 该技能只是规范文档，不包含自动化脚本或验证工具，无法自动检查代码合规性。
- 如果 SkillHub 项目本身不使用，则适用性有限。
- 未提供测试用例或示例代码，仅有文字描述。
- 未覆盖错误处理的详细模式（如错误响应结构）。
这个 Skill 与同类方案有什么区别？
与相关 Skills 并排比较；分数均按同一 FSRS 标准得出。
| Skill | FS 评分 | Star 数 | 最近更新 | License |
|---|---|---|---|---|
| API 与命名空间设计规范 本页 | 50 · 谨慎使用 | ★ 5.2k | 3 天前 | Apache-2.0 |
| 稳定接口设计指南 | 50 · 谨慎使用 | ★ 103k | 8 天前 | MIT |
| FreeHire 技术职位搜索技能 | 63 · 推荐 | ★ 45k | 3 天前 | MIT |
| AMC 样例数据集校准 ✓ NVIDIA · 官方 | 55 · 谨慎使用 | ★ 3.5k | 3 天前 | Apache-2.0 |
| step.parts 标准件检索技能 | 55 · 谨慎使用 | ★ 19k | 1 天前 | MIT |
FollowSkills 如何评估这个 Skill？
证据显示技能明确描述了RBAC角色、CSRF防护、会话管理和OpenAPI同步等安全相关的API设计约定，但未提供具体的安全审计细节或执行验证。由于未验证发布者身份且未发现恶意行为或敏感数据处理不当，给予中等分数。扣分原因：缺少对权限细化、异常处理和数据流透明度的深入说明。
技能提供了清晰的触发条件和API端点列表，但未包含可执行的测试用例或错误处理示例。静态审查无法执行验证，因此可靠性较低。扣分原因：缺少失败反馈和质量保证证据。
技能定义了明确的适用范围和边界（如新增或修改REST API端点、命名空间坐标逻辑等），并提供了中文支持说明。但未充分展示非适用场景和触发条件的精确性。扣分原因：边界定义基本清晰，但环境适配证据有限。
文档结构清晰，包含触发条件、坐标系统、API设计、常见陷阱等章节，但缺少安装/依赖说明、版本更新日志和已知限制的详尽说明。扣分原因：信息架构完整但治理细节不足。
技能旨在指导API和命名空间设计，但其直接使用的输出（如代码或配置）未验证，边际价值证据有限。扣分原因：静态审查无法确认实际效果。
提供了一些CI和工作流文件作为证据，但静态审查无法独立验证其有效性。扣分原因：证据类型单一，缺少第三方验证。
点击维度查看打分理由
证据充分度：低 — 主要依赖静态检查、作者材料或有限演示；适合发现线索，不适合做高风险决策。
查看完整评分方法 →