跳到主要内容

Skill 编写规范与 SKILL.md 模板

目录​

好 Skill 的判定标准​

一份合格的 Skill 应满足：

  1. 场景单一：一个 Skill 解决一类重复问题；不要写成「公司所有制度大全」。
  2. 输入明确：列出执行前必须收集的字段；缺失时先追问，不要猜。
  3. 步骤可执行：逐步列出，避免只有口号。
  4. 完成可验证：有 checklist 或量化阈值。
  5. 失败可恢复：超时、工具失败、证据不足时怎么办。

推荐目录与文件命名​

通用习惯（具体宿主可能略有差异）：

skills/
  <skill-id>/
    SKILL.md           # 主说明（必须）
    references/        # 可选：长文档拆分
    scripts/           # 可选：辅助脚本（注意权限）
    assets/            # 可选：模板、图片、数据表等静态资源

<skill-id> 建议使用 小写连字符，与 URL、包名风格一致，例如 rag-release-check。

Agent Skills 规范 还要求：目录名与 frontmatter 里的 name 一致，且 name 仅含小写字母、数字与连字符（其它约束见下表）。若你与该标准对齐，Skill 更容易被遵循同一标准的宿主直接识别。

Agent Skills 官方 YAML 元数据（摘要）​

完整字段与正则约束以 Specification 为准。下表便于你写 SKILL.md 顶部 YAML 时快速自查：

字段是否必填含义（简述）
name是与父目录同名；小写、a-z0-9-、长度等有上限
description是非空，≤1024 字符；说明做什么与何时用，并含利于匹配的用语
license否许可证名或指向同包内许可证文件
compatibility否运行环境（产品、系统依赖、网络等），≤500 字符
metadata否字符串键值扩展，键名建议有一定唯一性
allowed-tools否空格分隔的工具白名单（实验性，各宿主支持度不同）

正文前须为 YAML frontmatter + Markdown 正文，与下节「可复制模板」可同时使用：在下列模板最上方增加 --- 包裹的 YAML 块即可与官方格式一致。

SKILL.md 推荐结构（可复制）​

# Skill: <skill-id>

## Metadata
- Version: 0.1.0
- Owner: <团队/个人>
- Last reviewed: YYYY-MM-DD

## When to use
- 触发条件 1
- 触发条件 2

## When NOT to use
- 明确不适用场景（避免误用）

## Inputs（必填）
| 字段 | 类型 | 说明 |
|------|------|------|
| ... | ... | ... |

## Outputs
- 交付物格式（markdown/json/表格）
- 必须包含的章节或字段

## Workflow
1. 步骤一 …
2. 步骤二 …
3. …

## Quality checklist
- [ ] 项 1
- [ ] 项 2

## Fallback
- 工具失败：…
- 证据不足：…

## Security notes
- 禁止写入 Skill 的内容：密钥、客户隐私原文 …

若采用官方 frontmatter，可在全文最上方增加类似：

---
name: release-smoke-check
description: 在发版前按团队清单执行 staging 冒烟与门禁；用户在对话中提到发版、staging、冒烟时使用。
---

渐进披露、篇幅与校验​

  • 主文件：规范建议 SKILL.md 主体控制在约 500 行、约 5000 tokens 以内；更长说明应拆到 references/ 等，并在正文中写明触发条件再按需读取（见 Progressive disclosure）。
  • 引用路径：引用包内其它文件时，用相对 Skill 根目录的路径，并保持「不要套娃式链式引用过多层」（见 File references）。
  • 校验：可用官方维护的 skills-ref 校验 frontmatter 与命名，例如：skills-ref validate ./my-skill。

输入输出：尽量结构化​

自然语言输入可以保留，但建议同时给出表格或 JSON 模板，例如：

{
  "release_version": "1.4.2",
  "environment": "staging",
  "rollback_plan": "yes|no"
}

这样便于：自动化脚本对接、评测集构造、以及后续改成 Plugin 内的表单。

质量清单与失败兜底​

质量清单应可勾选、可机器辅助校验（例如「引用编号是否齐全」）。

失败兜底至少覆盖：

  • 检索无结果：拒答还是扩大检索？
  • 工具超时：重试几次？是否降级为只读？
  • 模型输出不合规：是否强制二次生成？

安全与敏感信息​

  • 不要把 API Key、token、客户身份证写进 Skill 正文；用环境变量或密钥系统引用。
  • 若 Skill 描述涉及操作生产数据，注明 审批人/双人复核 要求。

完整示例：发布前检查 Skill​

# Skill: release-smoke-check

## When to use
- 每次发版前 2 小时内执行

## Inputs
| 字段 | 说明 |
|------|------|
| version | 发布版本号 |
| changelog_url | 变更说明链接 |

## Workflow
1. 对照 changelog 列出风险点
2. 在 staging 执行冒烟用例集 A/B/C
3. 记录失败用例与是否阻塞发布

## Quality checklist
- [ ] 核心路径 0 P0 失败
- [ ] 监控大盘无新增 5xx 尖峰

## Fallback
- 若 staging 不可用：停止发布并通知负责人

延伸阅读​