Agent Skills
返回列表
🤖

Agent Skills 规范创作指南

AI Agent 更新于 2026.08.30

将以下提示词粘贴到你的 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 开发者