Agent Skills 规范创作指南
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/apollographql-skills-skill-creator。
技能介绍
要解决什么问题
在 Apollo GraphQL / GraphQL 生态里给 AI 助手加「技能」时,常见问题不是缺模板,而是不符合 Agent Skills 规范:目录名与 name 不一致、description 无法让代理判断何时启用、正文结构松散导致上下文浪费,或在生成鉴权、CORS、缓存等配置时没有显式安全警示,模型容易按默认公开策略写配置。
技能如何工作
本指南把「可发布的技能包」拆成可执行的写作流程:
- 最小结构:技能目录至少包含
SKILL.md,并说明 frontmatter 各字段(name、description、license、compatibility、metadata、allowed-tools)的必填与长度限制。 - 命名与描述:小写连字符、
name必须与父目录一致;description面向「何时激活技能」,而非产品口号式简介。 - 正文骨架:建议
Overview、Process(可用 checkbox)、Quick Reference、Security、Reference Files、Key Rules、Ground Rules等分区,便于代理按任务加载。 - 安全敏感内容:若涉及权限、密钥、对外暴露数据或网络绑定,必须在
## Security中写清风险、在风险点旁放警告、在验收清单中列安全检查,并用 MUST/NEVER 的 Ground Rules;不能假定模型能从 schema 推断哪些字段是私有的。 - 渐进披露:启动只加载元数据(约百 token),详细说明按需展开,控制总上下文占用。
适用边界与注意点
这是写作与规范指南,不替代 Rover、Apollo Server 或具体 GraphQL 实现的官方文档;也不负责替你实现业务 resolver。适合你在新建或改版 apollographql-skills 仓库内技能、或要对齐 SkillHub 发布要求时使用。若技能完全不碰配置与权限,安全章节可简化,但一旦生成访问控制相关配置,应按文内清单逐项核对,避免把软提示写成可选项。
使用场景
- 在 apollographql-skills 仓库新建目录时,需要按规范写好 SKILL.md 的 frontmatter 与正文分区。
- 把现有 GraphQL 运维说明改成技能时,要补全 description 触发条件与安全相关的 Ground Rules。
- 技能会生成 CORS 或鉴权配置前,需对照指南增加 ## Security 与验收清单项。
- 发布到 SkillHub 前自检:目录名与 name 一致、allowed-tools 未误含 Bash(curl:*)。
适合人员
- 维护 Apollo 相关技能仓库的维护者,需要统一团队技能目录与 frontmatter 写法
- 编写会输出网关或缓存配置的 GraphQL 平台工程师,担心模型默认公开暴露数据
- 在 RealQ / SkillHub 生态发布技能的内容编辑,要对齐 Agent Skills 正文结构与安全披露
- 初次把 Rover、schema 工作流沉淀为可加载技能包的 GraphQL 开发者