【大模型】AI Skill 编写完全教程

Chandler_Song

660人浏览 · 2026-03-23 08:01:34

Chandler_Song · 2026-03-23 08:01:34 发布

📖 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

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()` 等待

五、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 理解"为什么"，而不是机械执行