15Skills 系统
L3P1五步章 · 技术章
Why · 为什么要学
把 100 个高层 workflow(填发票、生成报告、做 PDF、跑数据迁移)全塞 system prompt 会让 context 爆炸,且模型在 100 个选项里选错率飙升。Skills 用 progressive disclosure 解决这个问题——一开始只暴露简短 description,模型决定"要用"时才注入完整 workflow。这是 harness 把"能力库"和"context 预算"解耦的核心机制。
1 ·核心要点
Skill 是可复用的任务包——把"如何完成某类任务"的知识、模板、参考代码打包,按需注入 agent 的 context。
Claude Code skill 标准目录结构:
~/.claude/skills/pdf/
├── SKILL.md # 入口:YAML frontmatter + Markdown 主体
├── examples/
│ └── create_pdf.py # 参考代码
└── templates/
└── invoice.tex # 模板文件
# SKILL.md frontmatter
---
name: pdf
description: Use this skill whenever user wants to do anything with PDFs.
Triggers include: creating PDFs, extracting text from PDFs, merging PDFs,
filling PDF forms.
---
# 操作说明主体(Markdown)
...Progressive disclosure 工作流:
启动:
harness 扫描 ~/.claude/skills/* 目录
把每个 skill 的 name + description 注入 system prompt
(~30-50 字/skill × N 个 = 几 KB,可控)
运行中:
模型读到 description,决定"这个任务该用 pdf skill"
→ 触发 trigger(关键词 / 显式调用)
harness 把 SKILL.md 主体 + 引用的文件读进 context
模型按 skill 主体里的步骤执行(可能调多个 tool)Skill vs Tool 的区别:
| Tool | Skill | |
|---|---|---|
| 粒度 | atomic 操作 | 高层 workflow |
| 触发 | 模型决定参数后调用 | 模型决定"要用此 skill" |
| 内容 | 代码 + JSON schema | SKILL.md + 资源文件 |
| 例子 | read_file、send_email | fill_invoice、generate_report |
2 ·最小代码示例
# 一个最小 skill:把 markdown 转成 PDF
# ~/.claude/skills/md_to_pdf/SKILL.md
---
name: md_to_pdf
description: Convert a markdown file to PDF with consistent styling.
Use when user asks to "export X as PDF" or "make a PDF from this".
---
# Markdown → PDF Conversion
## When to use
当用户要把 .md 文件输出为 PDF 时使用。
## Steps
1. 读取目标 .md 文件
2. 用 templates/style.css 注入样式
3. 调用 Bash tool:`pandoc input.md -o output.pdf --css=...`
4. 验证 output.pdf 生成成功(检查文件大小 > 0)
## Resources
- templates/style.css(在 skill 目录下)
- examples/sample.md(参考输入格式)3 ·工程权衡
什么场景用 Skill 而不是 Tool
- 多步 workflow——涉及多个 tool 配合 + 顺序约束(如 PDF 生成 = read + transform + write + verify)
- 需要模板/参考资源——HTML 模板、样式表、prompt 模板这类不便塞进 tool 定义的
- 需要团队/项目特定知识——"我们公司的 changelog 格式"、"内部 API 调用惯例"
- 能力数量大——50+ 个 workflow 用 progressive disclosure 才不会撑爆 context