【大模型】AI Skill 编写完全教程
📖 AI Skill 编写完全教程
一、什么是 Skill？
一句话总结：Skill 是一份"让 AI 学会重复做某件复杂事"的说明书。
把它想象成你给 AI 写的一本《操作手册》——以后遇到同类任务，AI 会自动按手册执行，而不是每次从零开始摸索。
Skill 解决的核心问题：
- AI 每次遇到相同任务，行为不稳定、结果不一致
- 复杂流程需要反复编写相同代码，浪费时间和 token
- 没有固定的输出格式，结果参差不齐
二、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：核心文件详解
SKILL.md 是整个技能的入口，由两部分组成：YAML 元数据和 Markdown 指令正文。
3.1 YAML Frontmatter（元数据）
---name: skill-name # 技能唯一标识符，小写连字符形式description:|# ⚠️ 最重要！AI 决定是否调用的主要依据 简短说明技能做什么，以及何时触发。 要包含关键词、场景，甚至可以"pushy"一些： "当用户提到……时，务必使用本技能。" compatibility:# 可选：依赖的工具或库 Python 3.8+, pandas, openpyxl ---关键提示：description 决定 AI 是否主动调用你的技能。写得越具体、越贴近用户的实际措辞，触发越准确。3.2 Markdown 正文（指令）
正文是 AI 执行任务的完整说明，建议控制在 500 行以内，内容超长则拆分到 references/。
推荐结构如下：
# 技能标题 ## 目的 一句话说明这个技能解决什么问题。 ## 使用时机 - 用户明确要求…… - 用户提供了……并希望得到…… - 用户需要……且输出格式为…… ## 工作流程 1. 第一步：……（何时调用脚本、读取哪些文件） 2. 第二步：…… 3. 第三步：…… ## 输出格式 规定最终输出的文件结构、命名规则等。 文件名格式：`output_YYYYMMDD_HHMMSS.xlsx` ## 示例 **输入**：用户说："……" **输出**：AI 执行……，生成……，并告知用户…… ## 注意事项 - 常见错误和边界情况 - 依赖缺失时的处理方式 - 数据量过大时的降级策略 写作要点：
- 用命令式语气：「调用脚本…」、「保存文件到…」
- 解释原因而非只给规则：「因为…，所以…」
- 明确指出何时读取 references/ 下的文件
四、scripts/ 目录：让脚本替你干活
脚本是技能的"执行引擎"——它把 AI 反复写的重复代码固定下来，以后直接调用，既稳定又省 token。
4.1 什么情况下写脚本？
- AI 在测试中反复生成同一段逻辑（数据处理、文件生成、API 调用）
- 任务逻辑稳定，不需要根据上下文动态改变
- 需要处理二进制文件（Excel、Word、图片等）
4.2 脚本编写规范
#!/usr/bin/env python3""" 脚本名称及简要说明 用法: python script.py input.csv output.xlsx [--option] """import argparse import sys defmain(input_file, output_file, option=False):# 核心业务逻辑passif __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() 等待 |
五、assets/ 目录：模板与静态资源
存放输出时会用到的非文本文件：Office 模板、图片、Logo、字体、配置文件等。
5.1 模板文件详细程度的选择
| 场景 | 建议 |
|---|---|
| 样式要求高（特定配色、字体、公司品牌） | 提供完整设计好的模板，脚本只负责填数据 |
| 样式简单或经常变化 | 提供最小占位模板（只有标题行），样式由脚本动态设置 |
| 完全灵活 | 不提供模板，全部由脚本动态创建（代码量增加，但最灵活） |
黄金法则：如果 AI 在多次测试中反复设置同样的样式，就把它固化成模板文件。
5.2 注意事项
- 文件不宜过大（保持在几 MB 以内），否则打包后不便分发
- 如果模板由用户自定义，可提供生成脚本（如
create_template.py）来创建初始版本
六、references/ 目录：按需加载的深度文档
存放大型参考文档，AI 只在需要时才读取，避免每次都占用上下文窗口。
适合放入的内容：API 文档、风格指南、复杂配置说明、领域知识等。
使用方式：在 SKILL.md 正文中写明触发条件：
如果用户要求使用「品牌视觉规范」，请阅读 `references/brand_style_guide.md` 了解详细的色彩和字体要求。 最佳实践：
- 文件超过 300 行时，在文件内添加目录
- 使用 Markdown 格式，便于 AI 理解结构
- 可按领域拆分为多个文件，AI 只加载当前需要的那一份
七、evals/ 目录：测试用例
用于技能开发阶段，存放测试提示和预期结果。
{"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 是否走了弯路、结果是否不一致？
第三步：收集反馈，修改迭代
根据评估结果，针对性修改：
| 发现的问题 | 修改位置 |
|---|---|
| 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。固定一次，受益无限次。
