AI Skill 编写教程

关键提示：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)

必须包含的要素：

五、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 是否走了弯路、结果是否不一致？

第三步：收集反馈，修改迭代

根据评估结果，针对性修改：

九、打包与发布

技能调试完成后，打包为 .skill 文件（本质是 zip 压缩包）：

python -m scripts.package_skill /path/to/skill-folder

生成的 .skill 文件可直接导入到 Claude Code 或其他支持技能的工具中。.skillignore 文件可控制打包时排除哪些内容（类似 .gitignore）。

十、最佳实践速览

一句话记住核心：Skill 的本质是把「AI 反复重复的事」固定下来——反复写的代码变成脚本，反复设置的样式变成模板，反复说明的流程写进 SKILL.md。固定一次，受益无限次。