AI Skill 编写完全教程
一、什么是 Skill?
一句话总结:Skill 是一份'让 AI 学会重复做某件复杂事'的说明书。
把它想象成你给 AI 写的一本《操作手册》——以后遇到同类任务,AI 会自动按手册执行,而不是每次从零开始摸索。
Skill 解决的核心问题:
- AI 每次遇到相同任务,行为不稳定、结果不一致
- 复杂流程需要反复编写相同代码,浪费时间和 token
- 没有固定的输出格式,结果参差不齐
AI Skill 的编写方法,包括标准目录结构、SKILL.md 核心指令文件、scripts 脚本规范、assets 资源管理、references 文档加载以及 evals 测试用例。通过实例展示了如何构建稳定、可复用的 AI 技能,涵盖元数据配置、工作流程定义、错误处理及打包发布流程,旨在帮助开发者将重复任务自动化,提升 AI 执行效率与一致性。
一句话总结:Skill 是一份'让 AI 学会重复做某件复杂事'的说明书。
把它想象成你给 AI 写的一本《操作手册》——以后遇到同类任务,AI 会自动按手册执行,而不是每次从零开始摸索。
Skill 解决的核心问题:
my-skill/
├── SKILL.md # 必需:核心指令文件(入口)
├── scripts/ # 可选:可直接执行的脚本
│ └── process_data.py
├── references/ # 可选:大型参考文档,按需加载
│ └── api_docs.md
├── assets/ # 可选:模板文件、图片、字体等
│ └── template.docx
├── evals/ # 可选:测试用例(开发阶段使用)
│ └── evals.json
└── .skillignore # 可选:打包时忽略的文件列表
各部分角色一览:
| 文件/目录 | 必需? | 作用 | 加载时机 |
|---|---|---|---|
SKILL.md | ✅ 是 | 核心指令,包含元数据和工作流 | 技能触发时立即加载 |
scripts/ | 否 | 可执行脚本,用于确定性任务 | 按需执行,不占上下文 |
references/ | 否 | 大型参考文档 | 按需读取 |
assets/ | 否 | 静态资源(模板、图片等) | 按需读取或复制 |
evals/ | 否 | 测试用例 | 仅开发阶段使用 |
.skillignore | 否 | 打包排除规则 | 打包时使用 |
SKILL.md 是整个技能的入口,由两部分组成:YAML 元数据和 Markdown 指令正文。
---
name: skill-name # 技能唯一标识符,小写连字符形式
description: |
⚠️ 最重要!AI 决定是否调用的主要依据
简短说明技能做什么,以及何时触发。要包含关键词、场景,甚至可以"pushy"一些: "当用户提到……时,务必使用本技能。"
compatibility:
# 可选:依赖的工具或库
- Python 3.8+
- pandas
- openpyxl
---
关键提示:
description决定 AI 是否主动调用你的技能。写得越具体、越贴近用户的实际措辞,触发越准确。
正文是 AI 执行任务的完整说明,建议控制在 500 行以内,内容超长则拆分到 references/。
推荐结构如下:
# 技能标题
## 目的
一句话说明这个技能解决什么问题。
## 使用时机
- 用户明确要求……
- 用户提供了……并希望得到……
- 用户需要……且输出格式为……
## 工作流程
1. 第一步:……(何时调用脚本、读取哪些文件)
2. 第二步:……
3. 第三步:……
## 输出格式
规定最终输出的文件结构、命名规则等。
文件名格式:`output_YYYYMMDD_HHMMSS.xlsx`
## 示例
**输入**:用户说:"……"
**输出**:AI 执行……,生成……,并告知用户……
## 注意事项
- 常见错误和边界情况
- 依赖缺失时的处理方式
- 数据量过大时的降级策略
写作要点:
脚本是技能的"执行引擎"——它把 AI 反复写的重复代码固定下来,以后直接调用,既稳定又省 token。
#!/usr/bin/env python3
"""
脚本名称及简要说明
用法:python script.py input.csv output.xlsx [--option]
"""
import argparse
import sys
def main(input_file, output_file, option=False):
# 核心业务逻辑
pass
if __name__ == "__main__":
# 1. 依赖检查
try:
import pandas
import openpyxl
except ImportError as e:
print(f"缺少依赖库:{e}")
print("请运行:pip install pandas openpyxl")
sys.exit(1)
# 2. 参数解析
parser = argparse.ArgumentParser(description="脚本功能说明")
parser.add_argument("input", help="输入文件路径")
parser.add_argument("output", help="输出文件路径")
parser.add_argument("--option", action="store_true", help="可选功能开关")
args = parser.parse_args()
# 3. 执行逻辑,捕获错误
try:
main(args.input, args.output, args.option)
except Exception as e:
print(f"错误:{e}", file=sys.stderr)
sys.exit(1)
必须包含的要素:
| 要素 | 原因 |
|---|---|
argparse 参数解析 | AI 调用时能灵活传递参数 |
| 依赖检查 | 缺库时给出明确提示,AI 可协助安装 |
try/except 错误处理 | 出错时定位问题,而非凭空猜测 |
| 避免交互式输入 | AI 无法响应 input() 等待 |
存放输出时会用到的非文本文件:Office 模板、图片、Logo、字体、配置文件等。
| 场景 | 建议 |
|---|---|
| 样式要求高(特定配色、字体、公司品牌) | 提供完整设计好的模板,脚本只负责填数据 |
| 样式简单或经常变化 | 提供最小占位模板(只有标题行),样式由脚本动态设置 |
| 完全灵活 | 不提供模板,全部由脚本动态创建(代码量增加,但最灵活) |
黄金法则:如果 AI 在多次测试中反复设置同样的样式,就把它固化成模板文件。
create_template.py)来创建初始版本存放大型参考文档,AI 只在需要时才读取,避免每次都占用上下文窗口。
适合放入的内容:API 文档、风格指南、复杂配置说明、领域知识等。
使用方式:在 SKILL.md 正文中写明触发条件:
如果用户要求使用「品牌视觉规范」,请阅读 `references/brand_style_guide.md` 了解详细的色彩和字体要求。
最佳实践:
用于技能开发阶段,存放测试提示和预期结果。
{
"skill_name": "my-skill",
"evals": [
{
"id": 1,
"prompt": "根据这个 sales.csv 生成报表",
"expected_output": "应生成包含汇总行和图表的 Excel 文件",
"files": ["sales.csv"]
},
{
"id": 2,
"prompt": "帮我把这份数据做成 Excel 报告",
"expected_output": "应识别为报表需求并调用技能"
}
]
}
按照以下循环迭代,直到技能稳定可靠:
写技能文档
↓
用测试用例运行(带技能 vs 不带技能)
↓
对比结果差异
↓
真人评估反馈(哪里不对?哪里缺失?)
↓
修改 SKILL.md / 脚本 / 模板
↓
重复,直到满意
↓
打包发布
第一步:写测试用例
准备 3~5 个有代表性的提示,覆盖典型场景和边界情况:
"根据 sales.csv 生成一份报表" ← 典型场景
"帮我把这些数据整理成 Excel 报告" ← 不同措辞
"生成报表,要包含图表和汇总行" ← 带附加要求
"处理一个 20000 行的大文件" ← 边界情况
第二步:运行对比
同一个提示,让「带技能的 AI」和「不带技能的 AI」各做一遍,对比结果:
第三步:收集反馈,修改迭代
根据评估结果,针对性修改:
| 发现的问题 | 修改位置 |
|---|---|
| AI 没有主动使用技能 | 优化 description 中的触发描述 |
| 脚本报错或结果不对 | 修改 scripts/ 中的脚本 |
| 输出样式不符合要求 | 调整 assets/ 中的模板 |
| 流程遗漏了某个步骤 | 补充 SKILL.md 的工作流程 |
| 某个参考文档没被读到 | 在正文中添加明确的触发条件 |
技能调试完成后,打包为 .skill 文件(本质是 zip 压缩包):
python -m scripts.package_skill /path/to/skill-folder
生成的 .skill 文件可直接导入到 Claude Code 或其他支持技能的工具中。.skillignore 文件可控制打包时排除哪些内容(类似 .gitignore)。
| 原则 | 说明 |
|---|---|
| 保持 SKILL.md 精简 | 超过 500 行即拆分到 references/ |
| 触发描述要"推人" | 不只说功能,要列出具体触发场景和措辞 |
| 脚本要健壮 | 包含参数解析、错误处理、依赖检查,禁止交互式输入 |
| 善用渐进式加载 | 只把最常用的指令放主文件,细节放 references |
| 测试先行 | 用 evals/ 确保技能可靠,跟无技能版本对比 |
| 版本控制 | 用 Git 管理技能源码,便于迭代和协作 |
| 解释原因而非规则 | 让 AI 理解"为什么",而不是机械执行 |
一句话记住核心:Skill 的本质是把「AI 反复重复的事」固定下来——反复写的代码变成脚本,反复设置的样式变成模板,反复说明的流程写进 SKILL.md。固定一次,受益无限次。

微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online