首页 / Skills 资产 / skill-authoring-guide
skill-authoring-guide
编写新的 SKILL.md 资产时使用。当要把一段"程序性知识"（操作步骤、领域方法论、检查清单）封装成 AI 可调用的 Skill 时，按此规范执行：frontmatter 怎么写、正文怎么组织、怎么验证 AI 真的会用。
SKILL.md 是开放的 Agent 技能标准（Anthropic 发起，Claude Code / Codex 兼容）。一份合格的 Skill = 元数据（让 AI 知道何时用）+ 正文（让 AI 知道怎么用）。
结构模板
markdown---
name: my-skill-name # 小写连字符，即目录名
description: 什么场景下使用。当用户……时，按此步骤……（这行是 AI 的触发依据，最重要）
tags: [tag1, tag2]
---
# 标题
（正文：步骤、代码、判定标准、参考链接）description 的写法（决定 AI 会不会用它）
- 写触发场景，不写内容摘要。AI 靠它匹配当前任务。
- 差：
关于 RAG 的知识
- 好：
评测 RAG 系统质量时使用。当需要判断能否上生产或建立评测闭环时，按此清单执行
- 公式：
<做什么>时使用。当<触发条件>时，按此<清单/步骤/指引>执行
正文的四条军规
- 自包含：不依赖"之前的对话"或外部上下文，一个陌生 Agent 拿到就能执行
- 可执行：有具体步骤、代码块、判定数值（如"Faithfulness ≥ 0.85"），不要只讲概念
- 渐进披露：正文保持主干（一屏能扫完），细节和长代码放参考链接或附属文件
- 有验证方式：告诉 Agent 怎么确认做对了（验收标准、测试命令）
写完后的验证（三问）
- 把 Skill 喂给一个不知情的 AI，问触发场景相关的问题——它会不会主动引用？
- 按正文步骤走一遍——能不能跑通？
- 把 description 遮住，只看正文——能反推出它适用什么场景吗？
参考
- Anthropic 官方 Skills 主仓（学结构）：https://github.com/anthropics/skills
- 官方"写 Skill 的 Skill"：仓库内 skill-creator
- Codex Skills 规范（跨厂商对照）：https://developers.openai.com/codex/skills/