创建自定义 Skills

这节课深入 Skill 的结构规范和最佳实践，然后通过两个自定义 Skill 实战——练习题生成和时间序列分析——验证这些实践。

SKILL.md 文件结构

每个 Skill 文件由两部分组成：

  1. YAML Frontmatter — 顶部的元数据
  2. Body Content — 下方的 Markdown 指令

Frontmatter 必填字段

字段约束
name最多 64 字符；仅小写字母、数字和连字符；不能以连字符开头/结尾；必须与父目录名一致；推荐使用动名词形式（verb + ing）
description最多 1024 字符；描述 Skill 做什么 以及 什么时候使用；包含能帮助 Agent 识别任务的关键词

Name 和 description 是 Agent 发现和触发 Skill 的关键。Description 不仅要说明功能，还要说明触发条件——如果有特定关键词能触发这个 Skill，务必写进去。

Frontmatter 可选字段

字段说明
license许可证名称或引用
compatibility最多 500 字符；环境要求
metadata任意键值对（如 author、version）
allowed-tools空格分隔的预批准工具列表（实验性）

注意：标准仍在快速迭代中。你可能会遇到一些早期 Skill 不完全遵循规范，这是正常的。

Body Content 最佳实践

Body 没有格式限制，但以下实践能让 Skill 更可靠：

推荐包含的内容

  • 分步指令（Step-by-step instructions）
  • 输入格式 / 输出格式 / 示例
  • 常见边界情况处理

实用建议

  • 控制在 500 行以内 — 详细内容移到外部文件
  • 引用文件只嵌套一层（SKILL.md → references/file.md，不要 references → 再引用其他文件）
  • 术语一致，表达清晰简洁
  • 文件路径始终使用正斜杠 /，即使在 Windows 上
  • 如果某个步骤可以跳过，明确说明跳过的条件

自由度控制

创建 Skill 时，需要决定给 Agent 多少自由度：

自由度描述适用场景
高通用文本方向，多种方法都可接受创意输出、多样化风格
中包含可定制的伪代码或代码示例，有推荐模式但允许变化大多数工作流
低引用特定脚本，必须严格按顺序执行数据分析、合规流程

复杂工作流

  • 拆分为清晰的顺序步骤
  • 如果步骤过多，考虑将部分拆到独立文件中
  • 系统可以处理 100+ Skills，确保命名不混淆

可选目录

/scripts

存放需要读取和执行的代码：

  • 清晰的文档说明
  • 显式的错误处理
  • 明确标注依赖项
  • 在 SKILL.md 中说明：Claude 应该执行脚本还是仅作为参考读取

/references

存放额外的参考文档：

  • 每个文件聚焦单一主题
  • 超过 100 行的文件应在顶部包含目录，方便 Agent 快速定位

/assets

存放模板和资源文件：

  • 文档模板、配置模板
  • 图表、Logo
  • 数据文件、Schema

这些目录名遵循 Agent Skills 开放标准。早期创建的 Skill 可能使用不同的命名。

实战案例一：生成练习题

目标： 从课堂笔记自动生成多种类型的练习题。

Skill 结构

generating-practice-questions/
├── SKILL.md
├── references/
│   └── domain-examples.md
└── assets/
    ├── markdown-template.md
    └── latex-template.tex

SKILL.md 关键设计

输入处理：

  • 指定支持的格式和使用的库（如 PDF 用 pdfplumber）
  • 指定要提取的文本内容

题目结构（严格排序）：

  1. 判断题（True/False）
  2. 选择题
  3. 编程题
  4. 实际应用题

每种题型都有子指南，规定具体要求。

输出格式：

  • 根据用户请求决定格式（Markdown / LaTeX / PDF）
  • 不在 SKILL.md 中硬编码模板，而是引用 assets 中的模板文件
  • 只在需要特定格式时加载对应模板——渐进式披露

关键设计决策

  • Skill 不超过 500 行，模板放在 /assets
  • 外部参考放在 /references
  • 只在需要时加载对应格式的模板，节省 Token

实战案例二：分析时间序列数据

目标： 提供 CSV 数据，自动诊断时间序列特征并生成可视化报告。

Skill 结构

analyzing-time-series/
├── SKILL.md
├── scripts/
│   ├── visualize.py    # 绘制时间序列图、直方图、滚动统计、箱线图
│   ├── diagnose.py     # 数据质量、分布、平稳性、季节性、趋势、自相关
│   └── decompose.py    # 时间序列分解
└── references/
    └── interpretation.md

SKILL.md 关键设计

低自由度、确定性工作流：

  1. 验证输入格式（列名、数据类型）
  2. 运行 diagnose.py — 按固定顺序执行：数据质量 → 分布 → 平稳性测试 → 季节性 → 趋势 → 自相关 → 变换建议
  3. 运行可视化脚本 — 生成图表
  4. 读取 summary.txt，结合 interpretation.md 解读发现
  5. 输出固定的文件树结构

脚本依赖：

  • 明确列出 Python 依赖项
  • 确保安装后脚本能正确运行

用 Skill Creator 评估最佳实践

创建完 Skill 后，如何验证质量？用 Skill Creator Skill 来评估。

在 Claude Code 中安装 Skills

Claude Code 不自带内置 Skills，需要从 Marketplace 安装：

# 在 Claude Code 中
/skills  # 查看已安装的 Skills

安装 anthropic/skills 后，会在 .claude/settings.json 中看到 enabledPlugins。

并行评估

使用两个 Subagents 并行评估两个 Skill：

  • generating-practice-questions: 9/10 — 可以改进简洁性
  • analyzing-time-series: 10/10 — 在避免重复、Frontmatter 质量和简洁性方面表现出色

这是一种快速评估 Skill 质量的方法——利用 Skill Creator 内置的最佳实践清单自动检查。

Skill 评估：单元测试

除了最佳实践检查，还应该像软件一样为 Skill 写”单元测试”：

测试结构

{
  "skills": ["generating-practice-questions"],
  "queries": [
    "Generate practice questions and save to output.md",
    "Generate practice questions and save to output.tex",
    "Generate practice questions and save to output.pdf"
  ],
  "files": ["test-files/notes.pdf"],
  "expected_behavior": [
    "成功读取并提取输入文件",
    "PDF 输入使用 pdfplumber",
    "提取所有学习目标",
    "生成 4 种类型的题目",
    "遵循每种题型的指南",
    "使用正确的输出模板",
    "LaTeX 输出能成功编译",
    "文件保存到正确位置和格式"
  ]
}

评估建议

  • 获取人工反馈
  • 在你计划使用的所有模型上测试
  • 对于包含脚本的 Skill，先用传统单元测试验证脚本本身

课程资料