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