【从原理到落地，一篇讲清：Skills 技能体系与使用】

qq_16060047

737人浏览 · 2026-04-24 14:16:42

qq_16060047 · 2026-04-24 14:16:42 发布

深度解析：Skills 技能体系与使用

从原理到落地，一篇讲清 Claude Skills 是什么、怎么用、怎么写。

一、Skills 到底是什么？

1.1 一句话定义

Skill（技能）是一种可被 AI 自主发现、自主加载、自主执行的"能力包"。 它把一段专业知识、一套操作流程、一组脚本工具，封装成标准化的目录结构，让大模型在合适的场景下自动调用，而不需要用户每次都重新写 Prompt。

它本质上回答了一个长期困扰 LLM 应用的问题：

“我每次都要把同一段复杂要求粘贴给模型，怎么能让模型自己记住并在需要时主动执行？”

1.2 Skills 与其他机制的区别

很多人把 Skills 和 Prompt、Agent、Function Call、RAG 混在一起。它们其实处在不同的抽象层：

机制	解决什么问题	触发方式	是否可复用
Prompt	一次性告诉模型怎么做	用户每次手动输入	低（靠复制粘贴）
System Prompt	全局设定角色和规则	会话开始注入	中（每个会话固定）
Function Call	让模型调用一个具体函数	模型根据 schema 决定	高（但粒度小）
RAG	给模型注入外部知识	检索相关文档	中（靠向量库）
Skill	把"知识 + 流程 + 工具"打包复用	模型按描述自动发现	极高（整包移植）

关键差异在于"自主性"： Skill 不是一个被动等待调用的函数，而是一个"挂在能力仓库里、等模型自己判断要不要用"的主动单元。

1.3 设计哲学：Progressive Disclosure（渐进披露）

Skills 的核心设计理念是 渐进披露：

第一层 —— 只看元数据：模型启动时只加载每个 Skill 的 name + description（通常 < 200 字），决定"这个技能可能有用"。
第二层 —— 读取 SKILL.md：模型决定使用时，才加载完整的指令说明。
第三层 —— 调用脚本/资源：按需读取 scripts/、references/、assets/ 里的具体资源。

这样的好处是：技能仓库可以无限扩展，但 Context 永远不会爆炸。你可以装 100 个 Skill，模型的系统消息里只多了 100 行描述。

二、Skills 的解剖结构

一个标准的 Claude Skill 目录长这样：

my-skill/
├── SKILL.md              # 核心文件：元数据 + 指令
├── config.json           # 运行时配置（模型、环境变量、密钥）
├── icon.png              # 技能图标（可选）
├── icon_prompt.txt       # 图标生成用的 prompt（可选）
├── scripts/              # 可执行脚本（Python/Shell 等）
│   └── generate.py
├── references/           # 长文档参考资料（按需加载）
│   └── rubric.md
├── assets/               # 静态资源（模板、图片等）
│   └── template.docx
└── outputs/              # 产出物目录（运行时生成）

2.1 SKILL.md 的 Frontmatter

这是 Skill 的"身份证"，字段决定了模型能否正确识别和触发：

---
name: 教学设计
enName: lesson-plan-design
description: >
  为教师生成结构完整的教学设计文档（docx格式）。当用户需要写教案、备课、
  生成教学设计、制作教案模板，或提到"教学设计"、"教案"、"备课"、
  "课时设计"、"教学方案"时触发。覆盖 K-12 到大学全学段全学科。
version: 1.0.0
env:
  model: Doubao-Seed-1.8
  python: ">=3.8"
  packages:
    - python-docx>=0.8.11
---

字段要点：

name：人类友好名。可以用中文。
description：最关键的字段。模型就靠它判断是否触发。必须写清楚"什么场景触发"、“包含哪些同义词/相关词”、“覆盖范围”。
version：语义化版本号，用于升级追踪。
env：运行时环境。指定模型、Python 版本、依赖包、密钥等。

2.2 `description` 是生死线

大量新手写 Skill 失败，都卡在 description 上。对比两个写法：

❌ 糟糕的写法：

description: 生成教案的工具

模型根本不知道什么时候用它。

✅ 优秀的写法：

description: >
  为教师生成结构完整的教学设计文档（docx格式）。当用户需要写教案、
  备课、生成教学设计、制作教案模板，或提到"教学设计"、"教案"、
  "备课"、"课时设计"、"教学方案"时触发。也适用于用户提供了授课主题、
  学段、学科等信息并希望快速生成教案框架的场景。覆盖 K-12 到大学全
  学段全学科。即使用户只是简单提到某节课需要教案或教学设计，也应触发。

这段文字真正做到了三件事：

说清输入场景（“需要写教案”、“提供了主题”）
列出触发关键词（教案/备课/课时设计…）
明确覆盖边界（K-12 到大学）

2.3 SKILL.md 的主体

Frontmatter 之后是真正的"指令手册"，结构通常包括：

必填参数 —— 哪些信息是启动前必须从用户处获取的
可选参数 —— 不给就用默认值的字段
输出格式约定 —— Markdown/JSON/LaTeX 禁用等硬约束
模板结构 —— 输出的完整骨架
调用脚本的时机 —— 什么时候跑 scripts/xxx.py

一个经验法则：SKILL.md 应该让"没见过这个技能的模型"能完全按它执行。

三、Skills 是怎么被触发的？

3.1 三种触发路径

自动触发（最常见）
用户说话 → 模型匹配 description → 自主调用 Skill。
例：用户说"帮我写一份高一数学的教案"，模型扫描技能库，匹配到 lesson-plan-design，自动加载执行。
显式触发
用户直接 /skill-name 或 “用 XX 技能”。这在 Claude Code 里是 Skill 工具 + skill name。
链式触发
一个 Skill 在执行过程中调用另一个 Skill。例如 brainstorming（头脑风暴）结束后跳到 writing-plans（编写计划）。

3.2 触发机制背后的"匹配引擎"

模型不是做字符串匹配，而是做语义匹配 + 意图推理。所以：

description 写得越具体、关键词越多 → 召回率越高
但也不能太宽泛，否则会在不该触发的场景误触发（精确率下降）

一个不错的类比：description 是 Skill 的 SEO 关键词 + 使用说明书的混合体。

3.3 什么时候不会触发？

description 模糊，没有明确场景
多个 Skill 的 description 高度重叠，模型无法决策
用户的请求不涉及该 Skill 的任何语义信号
被更高优先级的指令（如 CLAUDE.md 里的禁令）覆盖

四、如何使用 Skills？

4.1 使用已有 Skill 的三步法

Step 1 —— 安装 / 放置到技能目录

在 Claude Code 里，Skill 目录通常是：

用户级：~/.claude/skills/
项目级：<project>/.claude/skills/
插件级：随插件分发

Step 2 —— 让模型知道它存在

这步通常由框架自动完成。启动会话时，Claude 会扫描 skills 目录，把所有 SKILL.md 的 frontmatter 注入到系统消息。

Step 3 —— 直接用自然语言表达需求

不需要记住 Skill 名字，直接说"帮我出一份教案"，模型会自己匹配。

4.2 四条最佳使用实践

信任模型的判断，但给它足够的上下文
你说"写教案"它匹配 lesson-plan-design；你说"给学生出题"它可能匹配 classroom-evaluation。语义越清晰，匹配越准。
遇到没匹配上的情况，检查 description
多半是关键词覆盖不全。加一个"包含’XXX’等场景时触发"即可。
一个复杂任务可以串联多个 Skill
教学闭环：lesson-plan-design（备课）→ classroom-knowledge（课堂讲解）→ classroom-evaluation（课堂评估）→ art-evaluation（作业评价）。让模型一步步走完。
验证输出前不要相信 Skill 说"完成了"
Skill 里有脚本调用时，建议加上 verification-before-completion 类的检查环节，保证产物真实可用。

4.3 跨平台使用差异

平台	调用方式	注意事项
Claude Code	内置 `Skill` 工具 + 自动发现	最原生的体验
Copilot CLI	`skill` 工具，从插件目录发现	工具名可能不同，看 `references/copilot-tools.md`
Gemini CLI	`activate_skill` 工具，先加载 metadata，按需展开	需要 `GEMINI.md` 映射
自研 Agent 框架	自己实现扫描 + 注入逻辑	参考 Anthropic 的开源实现

五、如何写一个高质量的 Skill？

5.1 写 Skill 的思维模型

把 Skill 当成"一份给新同事的工作 SOP 手册"来写：

新同事完全不了解背景 → description 必须解释清楚使用场景
新同事不能猜你的偏好 → 所有硬约束（格式、禁用项、默认值）必须明写
新同事手头有工具 → 复杂操作写成 scripts，让模型调用，而不是让模型自己"想办法"

5.2 七条硬性原则

单一职责
一个 Skill 只做一件事。做教案的不要顺便出题，做评价的不要顺便生成 PPT。拆分比合并更安全。
description 至少 3-5 句话，覆盖关键词同义词
宁可重复，不可遗漏。"教案/备课/课时设计/教学方案"四个词都写上。
参数分必填和可选，明确缺失提示语
必填参数一次性列出，不要模型追问 N 轮。
输出格式有硬约束时，顶格写明白
例：禁止 LaTeX → 数学公式必须用 Unicode。这种约束越早出现越好。
复杂产物（docx/pdf/图像）用脚本生成，不要让模型"想象"
模型擅长写 Markdown，把 Markdown → docx 的工作交给 python-docx。
提供模板骨架
给一个完整的结构示例，模型照着填比自己从零构造稳定得多。
版本化管理
每次修改 SKILL.md，更新 version。便于追踪问题和回滚。

5.3 常见陷阱

陷阱	症状	解决方式
description 太泛	误触发、不触发	补场景、补关键词
把所有逻辑塞进 SKILL.md	文件超长，模型注意力涣散	长文档拆到 `references/`，脚本化到 `scripts/`
脚本依赖没在 `env` 声明	运行时报 `ImportError`	在 `env.packages` 里声明
输出路径写死	多用户冲突	用 `OUTPUT_DIR` 环境变量
忽略"必填参数缺失"的提示	模型胡编参数	明确要求"三项全缺时一次性提示用户"
Skill 之间关键词高度重叠	模型选错	在 description 里写"与 X 的区别是…"

5.4 一个好 Skill 的自检清单

description 包含场景 + 关键词 + 边界
必填参数清单 + 缺失提示
输出格式的硬约束在开头说明
有完整的模板骨架
脚本化所有复杂产物
env 声明了所有依赖
有 version 字段
独立跑一次能得到正确产物
别的 Skill 干扰时不会错触发

六、Skills 的进阶玩法

6.1 组合与编排

多个 Skill 可以通过"Plan Skill"编排起来。例如 Superpowers 框架里：

brainstorming → 先想清楚做什么
writing-plans → 再写出实施计划
executing-plans → 再执行
verification-before-completion → 完成前验证

每一步都是独立 Skill，组合起来就是一套完整的工程方法论。

6.2 Skill + Memory（记忆系统）

把"用户偏好""领域术语"存进记忆系统，Skill 在运行时读取记忆做个性化。例如：

记忆里有 “用户偏好人教版教材” → lesson-plan-design 默认选人教版
记忆里有 “用户是小学数学老师” → 所有评价类 Skill 调整语气和难度

6.3 Skill + Hook（钩子）

在 settings.json 里配置 hook，让 Skill 的执行前/后触发额外动作：

Skill 运行完自动把 outputs 目录打包
Skill 出错时自动发通知
Skill 调用前先做权限检查

6.4 子代理并行

对于独立的 Skill 调用，可以用 dispatching-parallel-agents 模式并行触发。例如同时跑 art-evaluation 和 music-evaluation，分别评两份作业，最后汇总。

七、常见误解澄清

误解 1：Skill 是 Prompt 模板
→ 不是。Prompt 模板是被动填空，Skill 是主动被模型发现和使用，包含知识、流程、工具。

误解 2：Skill 必须配脚本
→ 不必。纯知识型 Skill（比如"代码审查清单"）完全可以只有 SKILL.md。脚本是为复杂产物服务的。

误解 3：Skill 越多越好
→ 不对。Skill 之间语义重叠会导致模型选错。宁可少而精。

误解 4：Skill 就是 Function Call
→ 粒度完全不同。Function Call 是"调一个函数"，Skill 是"执行一套完整工作流"。Skill 内部可能包含多个 Function Call。

误解 5：description 写得越长越好
→ 长度不是关键，信息密度才是。关键词覆盖 + 边界清晰，三五句话够用。

八、结语：Skills 的本质

如果说 Prompt 让模型"会做一件事"，那么 Skills 让模型"自主决定做哪件事，以及怎么做"。

它是 LLM 从"对话助手"走向"自主 Agent"的关键拼图：

知识可复用
流程可标准化
工具可编排
能力可扩展

对开发者而言，写一个好 Skill 不是写代码，而是把一套经过验证的工作方法论，固化成 AI 可自主执行的单元。每一个 Skill，都是一次"人类专业经验"向"机器自主能力"的迁移。

这也是为什么 Skills 很可能是 AI Agent 时代最重要的一种"基础设施"。

附：快速上手脚手架

想马上动手写一个 Skill？照着这个模板填：

my-first-skill/
├── SKILL.md
└── scripts/
    └── run.py

SKILL.md：

---
name: 我的第一个技能
enName: my-first-skill
description: >
  [一句话说明这个技能做什么]。当用户提到 [关键词1]、[关键词2]、
  [关键词3]，或 [具体场景] 时触发。覆盖 [边界]。
version: 0.1.0
env:
  python: ">=3.8"
  packages: []
---

# 技能标题

## 必填参数

| 参数 | 示例 | 缺失提示语 |
|------|------|-----------|
| xxx | xxx | "请提供 xxx" |

## 输出格式约定

- [硬约束 1]
- [硬约束 2]

## 执行步骤

1. 向用户确认必填参数
2. 调用 `scripts/run.py`
3. 返回产物路径

就是这样。写完它，把目录放进 ~/.claude/skills/，下次对话，Claude 就会自己用上。

Happy Skill-Building. 把你最熟练的工作方法，交给 AI 反复复用。