AI Skill 使用指南· №5
如何编写标准规范的 Skills：从入门到精通的完整指南
本文是基于OpenClaw/Codex官方规范写的完整指南，手把手教你从零写出一个标准、规范、可分发的Skill。涵盖SKILL.md结构、触发词写作、scripts/references/assets规范，以及完整示例。
约 7 分钟阅读1,867 字292 次阅读博主
AI Skill 使用指南· №5
本文是基于OpenClaw/Codex官方规范写的完整指南，手把手教你从零写出一个标准、规范、可分发的Skill。涵盖SKILL.md结构、触发词写作、scripts/references/assets规范，以及完整示例。
2026年，Skills 已经成为 AI Agent 扩展能力的主流方式。
但很多人做的 Skills 问题一堆：触发词写得模糊、SKILL.md 过于冗长、资源文件乱放、描述和实际功能对不上——导致 AI 要么选错 Skill，要么根本不知道什么时候该调用它。
本文是基于 OpenClaw / Codex 官方规范写的完整指南，手把手教你从零写出一个标准、规范、可分发的 Skill。
Skill 是一个自包含的能力扩展包，让 AI 在特定领域具备专业知识和操作流程。
一个 Skill 由以下部分组成：
skill-name/
├── SKILL.md # 核心文件（必须）
├── scripts/ # 可执行脚本（可选）
├── references/ # 参考文档（可选）
└── assets/ # 资源文件（可选）
| 文件/目录 | 职责 | 何时加载 |
|---|---|---|
| SKILL.md | 触发条件和核心指令 | 始终加载（触发前） |
| scripts/ | 确定性逻辑代码 | 执行时调用 |
| references/ | 详细参考资料 | 按需加载 |
| assets/ | 模板、图片等输出资源 | 生成内容时使用 |
SKILL.md 是 Skill 的核心，每个 SKILL.md 由两部分组成：
Frontmatter 里的 name 和 description 是唯一被 AI 在触发前读取的字段，决定了这个 Skill 什么时候被激活。
标准格式：
---
name: my-custom-skill
description: 描述这个Skill做什么，以及什么时候应该触发它
---
⚠️ 注意事项：
name 只允许小写字母、数字、连字符description 要写清楚触发场景，而不是功能描述好例子：
---
name: pdf-editor
description: PDF文档编辑和处理。当用户说"帮我旋转这个PDF"、"合并多个PDF"、"从PDF里提取文字"、"给PDF加水印"、"压缩PDF"时触发。
---
坏例子：
---
name: pdf-editor
description: 这个Skill可以编辑PDF文件，支持多种操作。
---
（坏在哪里：没有触发场景，AI 不知道什么时候该用它）
正文在 Skill 被触发后才加载，包含使用说明和操作指南。
核心原则：保持精简。
my-skill/
├── SKILL.md # ✅ 必须
├── scripts/ # 可选
│ ├── do_something.py
│ └── helper.sh
├── references/ # 可选
│ ├── api_docs.md
│ └── schemas.md
└── assets/ # 可选
├── template.html
└── logo.png
❌ 不要创建这些文件：
Skill 目录下只放 AI 执行任务需要的文件，不需要给人类看的说明文档。
这是最多人犯错的地方。
AI 在收到用户消息时，会对比所有 Skill 的 description，找出最匹配的那个。Description 就是你的 Skill 的"广告词"和"匹配钥匙"。
原则1：列出具体触发场景
description: 当用户说"帮我XXX"、"做一下YYY"、"生成ZZZ"时触发。
原则2：包含变体表达
用户说"旋转PDF"和"把PDF转个方向"和"PDFOrientation调转"，意思一样，你的 description 要能覆盖这些变体。
原则3：区分相似 Skill
如果你的 Skill 叫 pdf-rotate，description 要和 pdf-compress 明确区分开。
原则4：说明不适用的场景
有时候说清楚"什么时候不要用"比"什么时候用"更重要。
description: PDF旋转和方向调整。当用户明确说"旋转"、"转方向"、"orientation"时触发。
# 主动排除：PDF内容识别（那是OCR Skill的事）
| 质量 | Description |
|---|---|
| ⭐⭐⭐ | "当用户说'帮我旋转PDF'、'把PDF转90度'、'orientation'、'rotate'时触发。" |
| ⭐⭐ | "PDF编辑工具，可以旋转和调整PDF方向。" |
| ⭐ | "这是一个PDF编辑Skill，功能很强大。" |
# ✅ 正确
Extract text from PDF using pdfplumber.
Run `python scripts/extract_text.py --input <file>`.
# ❌ 错误
This skill can be used to extract text. It uses pdfplumber library.
You might want to try extracting the text when working with PDFs.
# Skill Name
## 快速用法（最常用）
[最简单的调用方式]
## 进阶用法（备用）
[复杂场景]
## 配置选项
[可调整的参数]
## 注意事项
[容易出错的地方]
## 参考资料
- 详细内容：See [references/api.md](references/api.md)
- 示例：See [references/examples.md](references/examples.md)
不要把所有信息都塞进 SKILL.md 正文。遵循原则：
正文只写：每次执行都需要的基础信息 references/ 放：详细文档、API 列表、示例代码
# PDF Processing
## 基本用法
使用 pdfplumber 提取文本：[示例]
## 进阶用法
- 表单填写：See [references/forms.md](references/forms.md)
- API 参考：See [references/api.md](references/api.md)
- 更多示例：See [references/examples.md](references/examples.md)
| 内容 | 建议行数 | 原因 |
|---|---|---|
| SKILL.md 正文 | < 500 行 | 超过会让上下文膨胀 |
| references/ 单文件 | < 100 行 | 文件太长时加目录 |
| 总 token 预算 | < 5000 tokens | 留空间给对话和其他 Skills |
"脚本是'执行而不读入'的——零 token 成本。"
把命名转换、长度约束、格式校验这些细碎但脆弱的操作封装进脚本，不占用 AI 的上下文窗口。
⚠️ 重要：所有 scripts 必须实际运行验证，不能只写代码不测试。
至少测试以下场景：
references/
├── api.md # API 文档
├── schemas.md # 数据结构
├── examples.md # 示例
└── policies.md # 政策/规范
如果单个文件超过 100 行，在文件顶部加一个目录：
# API Reference
## 目录
- [create](#create) - 创建资源
- [update](#update) - 更新资源
- [delete](#delete) - 删除资源
## create
...
Assets 是直接复制到输出的，不是给 AI 读的。如果 AI 需要参考某些内容，应该放 references/ 而不是 assets/。
brand-skill/
├── SKILL.md
└── assets/
├── logo.png # 直接复用
├── email-template.html # 直接复用
└── colors.css # 直接复用
| 规则 | 正确 | 错误 |
|---|---|---|
| 字符 | 小写字母、数字、连字符 | 大写、空格、下划线 |
| 长度 | 64 字符以内 | 超过 64 |
| 格式 | 词根用连字符连接 | 驼峰或下划线 |
code-review、image-resize、data-exportgh-address-comments、linear-address-issueskill、tool、helper好名字：
pdf-rotatenotion-page-creatorfeishu-calendar-event坏名字：
my-skilltool1pdftool_new用户会说：
mkdir -p pdf-rotate/{scripts,references,assets}
touch pdf-rotate/SKILL.md
---
name: pdf-rotate
description: PDF文档旋转和方向调整。当用户说"旋转PDF"、"PDF转方向"、"rotate PDF"、"PDF orientation"、"把PDF转90度"时触发。
---
# PDF Rotate
## 快速用法
使用 `scripts/rotate_pdf.py`：
```bash
python scripts/rotate_pdf.py --input <file.pdf> --angle 90 --output <output.pdf>
| 参数 | 说明 | 默认值 |
|---|---|---|
--input | 输入PDF文件路径 | 必填 |
--output | 输出PDF文件路径 | <input>_rotated.pdf |
--angle | 旋转角度（90/180/270） | 90 |
### 10.4 编写旋转脚本
```python
#!/usr/bin/env python3
"""PDF旋转脚本"""
import argparse
from pypdf import PdfReader, PdfWriter
def rotate_pdf(input_path, output_path, angle):
reader = PdfReader(input_path)
writer = PdfWriter()
for page in reader.pages:
page.rotate(90) # 简单处理
writer.add_page(page)
with open(output_path, 'wb') as f:
writer.write(f)
if __name__ == '__main__':
parser = argparse.ArgumentParser()
parser.add_argument('--input', required=True)
parser.add_argument('--output')
parser.add_argument('--angle', type=int, default=90)
args = parser.parse_args()
output = args.output or args.input.replace('.pdf', '_rotated.pdf')
rotate_pdf(args.input, output, args.angle)
python scripts/package_skill.py pdf-rotate
# 生成 pdf-rotate.skill 文件
# 错误
description: 这个Skill用于处理PDF文件，可以旋转、合并、分割等。
# 正确
description: PDF旋转。当用户说"旋转PDF"、"PDF转方向"、"rotate PDF"时触发。
# 错误：正文写了 2000 行
# 包括所有API、所有示例、所有变体
# 正确：正文精简，详细内容放 references/
# 错误
name: My Custom Skill # 包含空格和大写
name: my_custom_skill # 下划线而非连字符
# 正确
name: my-custom-skill
# 错误：创建了这些
my-skill/
├── SKILL.md
├── README.md # ❌ 不需要
├── CHANGELOG.md # ❌ 不需要
├── INSTALL.md # ❌ 不需要
└── ...
# 正确：只有必要的文件
my-skill/
├── SKILL.md
├── scripts/
└── references/
scripts/ 里的代码必须实际运行验证，否则可能带着 bug 交付。
name 字段：全小写、连字符、64字符以内description 字段：列出具体触发词，不是功能描述python scripts/package_skill.py 通过写好一个 Skill 的核心就三句话：
1. Description 是钥匙 — 写得具体、写得场景化，AI 才能正确触发
2. 正文要精简 — 只放核心用法，详细内容放 references/
3. Scripts 是执行层 — 把确定性逻辑封装进去，不占上下文
记住这个设计哲学：
"Codex 已经足够聪明了。只需要告诉它'什么时候用'和'怎么用'，不需要教它'为什么'。"
参考工具：
scripts/init_skill.py：自动生成标准目录结构scripts/package_skill.py：打包并验证参考资料：OpenClaw skill-creator SKILL.md、DigitalOcean Agent Skills 教程、AgentSkills.io Best Practices、GitHub datawhale/hello-agents
标签：#Skills #教程 #SKILL.md #OpenClaw #AIAgent #技能开发
Conversation
0 条