---
name: skill-authoring-guide
description: 编写新的 SKILL.md 资产时使用。当要把一段"程序性知识"（操作步骤、领域方法论、检查清单）封装成 AI 可调用的 Skill 时，按此规范执行：frontmatter 怎么写、正文怎么组织、怎么验证 AI 真的会用。
tags: [skill, skillmd, agent, documentation]
category: skills
---


# SKILL.md 编写规范

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 系统质量时使用。当需要判断能否上生产或建立评测闭环时，按此清单执行`
- 公式：`<做什么>时使用。当<触发条件>时，按此<清单/步骤/指引>执行`

## 正文的四条军规

1. **自包含**：不依赖"之前的对话"或外部上下文，一个陌生 Agent 拿到就能执行
2. **可执行**：有具体步骤、代码块、判定数值（如"Faithfulness ≥ 0.85"），不要只讲概念
3. **渐进披露**：正文保持主干（一屏能扫完），细节和长代码放参考链接或附属文件
4. **有验证方式**：告诉 Agent 怎么确认做对了（验收标准、测试命令）

## 写完后的验证（三问）

1. 把 Skill 喂给一个不知情的 AI，问触发场景相关的问题——它会不会主动引用？
2. 按正文步骤走一遍——能不能跑通？
3. 把 description 遮住，只看正文——能反推出它适用什么场景吗？

## 参考

- Anthropic 官方 Skills 主仓（学结构）：https://github.com/anthropics/skills
- 官方"写 Skill 的 Skill"：仓库内 skill-creator
- Codex Skills 规范（跨厂商对照）：https://developers.openai.com/codex/skills/