easy-vibe 第三阶段核心技能:Claude Code Skills 技能包完全指南——安装实操、SKILL.md 编写与动态上下文注入机制
easy-vibe 第三阶段核心技能:Claude Code Skills 技能包完全指南——安装实操、SKILL.md 编写与动态上下文注入机制
本文基于 easy-vibe 课程第三阶段(开发进阶)"核心技能"模块中的 Skills 章节(源文档:docs/ar-sa/stage-3/core-skills/skills/index.md)整理与深化,覆盖 Claude Code Skills 从概念、安装检索、SKILL.md 编写到三层渐进加载等底层机制的完整知识体系。读完后你将能够:用 find-skills 一句话检索并安装技能、从零手写可复用的 SKILL.md 技能包、理解 Skills 与 MCP 的职责边界,并解释技能"按需注入上下文"背后的 Token 经济学设计。
1. Skills 是什么,为什么需要它
Claude Code Skills 是一种将专业知识、工作流程和最佳实践打包成"可复用技能包"(Skill Packages)的功能。
可以把它想象成给 Claude 配备的一本"技能书":当你需要它完成特定任务时,不再需要一遍遍地解释要求,而是让它直接按照预先定义好的技能标准来执行工作。
1.1 它解决的四个痛点
在 Skills 出现之前,日常使用 Claude Code 存在几个反复出现的问题:
- 重复指令:每次都要解释"代码要符合什么风格"、"提交信息要怎么写";
- 知识无法沉淀:团队成员各自的使用经验无法共享;
- 标准不统一:不同的人用 Claude,结果可能完全不同;
- 效率低下:常见任务每次都要从头解释。
Skills 把上述经验从"聊天记录"固化为"文件",让 Claude 变成一个"有经验的团队成员"——它知道你的项目规范、工作流程和最佳实践。
1.2 为什么现在要学
课程文档给出的理由是 Skills 正在成为 AI 工程师的必备能力:
- 社区热度高:文档提到 GitHub 上相关仓库星标快速增长,例如 OpenSkills 项目已收获 7.2k stars,Obsidian Skills 9 天暴涨 6.6k stars(此处为文档原文引用数据,反映课程编写时的社区状态);
- 官方支持:Anthropic 官方维护 Skills 仓库,Vercel 推出 Agent Skills 与 find-skills 工具;
- 实用性强:从代码审查、Git 操作到视频制作、PPT 生成均有覆盖,文档提到 skills.sh 平台已有 60K+ 订阅量的热门技能;
- 效率提升:一次配置、反复使用,让 Claude 真正成为你的"数字员工"。
2. 快速开始:安装并使用你的第一个技能
2.1 先装 find-skills(强烈推荐)
在开始使用 Skills 之前,建议先安装 find-skills——它是 AI Agent 领域的"技能搜索神器"。安装命令:
npx skills add vercel-labs/skills@find-skills -g -y
find-skills 就像 AI Agent 的"应用商店搜索器":当你需要完成某个任务但本地没有对应技能时,它会自动搜索并推荐最合适的技能。安装后直接告诉 Claude 你的需求即可,例如:
我需要做一个 React 组件的性能优化,帮我找找有什么技能可以用
Claude 会通过 find-skills 搜索,然后列出找到的相关技能供你选择安装。
装与不装的差别:
| 没有 find-skills | 有了 find-skills |
|---|---|
| 手动在代码托管平台搜索相关技能 | 一句话描述需求 |
| 逐个复制、安装、配置 | AI 自动搜索最匹配的技能 |
| 反复调试适配 | 一键安装,立即可用 |
Windows 用户注意:官方版本对 Windows 支持有限。社区制作了 Windows 适配版本(customize-skills 仓库),支持 CMD 和 PowerShell,并增加了中文搜索功能。安装步骤:
- 获取 Windows 版本的
SKILL.md文件; - 替换
C:/Users/你的用户名/.agents/skills/find-skills目录下的文件; - 重启 Claude Code 即生效。
2.2 实战一:安装 Remotion 视频制作技能
装好 find-skills 后,用它检索并安装第一门技能——Remotion 视频生成工具。
第 1 步,在 Claude Code 中输入:
帮我找一下和 Remotion 相关的技能,我想制作视频
Claude 会搜索并推荐 remotion-dev/skills。
第 2 步,安装:
npx skills add remotion-dev/skills -g
第 3 步,用它做点有意思的东西。Remotion 是一个用 React 代码制作视频的工作流,安装后你可以用自然语言描述需求:
任务 1:制作动态文字视频
用 Remotion 制作一个视频:
- 1920x1080,5 秒
- 一行 "Hello World" 文字从左侧飞入
- 同时带有旋转和缩放效果
- 渐变背景
任务 2:制作数据可视化视频
制作一个 10 秒的视频展示数据增长:
- 从柱状图开始
- 柱子逐个动画生长
- 数字递增计数
- 结尾显示大字 "增长300%"
任务 3:制作多场景产品展示视频
制作一个 3 场景的产品展示视频:
场景1:logo 淡入,2秒
场景2:产品特性逐条出现,3秒
场景3:CTA 按钮弹出,2秒
每个场景之间用平滑过渡
Claude 会生成完整的 Remotion 代码。运行方式:
- 新建项目:
npx create-video my-video - 把 Claude 生成的代码复制进去
- 启动预览:
npm start - 构建视频:
npm run build
2.3 实战二:frontend-design 解决"前端又丑又慢"
直接描述问题:
我的网站看起来很老式,加载也很慢。帮我找一下能用的技能
对于"美化 + 提速"这类需求,find-skills 会推荐 anthropics/skills/frontend-design(官方技能)。它专门解决"AI 生成的界面看起来平庸且千篇一律"的问题,帮助 Claude 设计:
- 避免"AI 模板感"的独特视觉风格;
- 专业的配色与字体体系;
- 流畅的动画效果;
- 生产级别的代码质量。
安装并使用:
npx skills add anthropics/skills/frontend-design -g
可交给它完成的任务示例:
帮我重新设计这个页面,让它看起来非常专业,不像 AI 生成的
这个界面太丑了,用更现代的设计语言重写
创建一个深色风格、科技感十足的仪表盘
Claude 会遵循该技能的约定:选择独特视觉方向(极简、复古未来、新粗野主义等)、精心挑选色彩与字体、合理的间距与布局、平滑的交互动画。
2.4 实战三:frontend-slides 快速生成漂亮 PPT
frontend-slides 让你用自然语言创建精美的 HTML 演示文稿——即使你完全不懂 CSS 和 JavaScript。它的核心理念是"展示而非描述":如果你说不清想要什么样的设计风格,它会生成 3 个视觉预览供你选择,而不是逼你描述"蓝色背景、大字体"这类抽象需求。
安装方式 1(手动):
# 创建技能目录
mkdir -p ~/.claude/skills/frontend-slides
# 1. 从 zarazhangrui/frontend-slides 仓库获取
# SKILL.md 和 STYLE_PRESETS.md 两个文件
# 2. 放入 ~/.claude/skills/frontend-slides/
安装方式 2(用 find-skills 检索):
帮我找一个能做 PPT 的技能
Claude 会通过 find-skills 检索并推荐 frontend-slides。
三个典型使用场景:
场景 1:从零创建演示文稿
/frontend-slides
我要做一个 AI 创业公司的融资演示文稿,大约 10 页
Claude 会引导你完成:1. 填写每页内容(标题、要点、图片);2. 描述想要的感觉(震撼、专业、温暖);3. 从 3 个视觉风格预览中选择;4. 生成完整 HTML 演示文稿;5. 在浏览器中打开预览。
场景 2:转换 PowerPoint 文件
/frontend-slides
把我的 presentation.pptx 转换成网页演示文稿
Claude 会:1. 提取 PPT 中所有文字、图片和备注;2. 展示提取内容供确认;3. 让你选择视觉风格;4. 生成保留全部原始内容的 HTML 演示文稿。
场景 3:快速生成风格预览
/frontend-slides
我想做一个技术分享 PPT,先给我看看有哪些视觉风格
Claude 会直接生成 3 个不同风格的预览页面:
- 暗色风格:Neon Cyber、Terminal Green、Deep Space;
- 亮色风格:Paper & Ink、Swiss Modern、Soft Pastel;
- 特殊风格:Brutalist、Gradient Wave。
内置视觉风格一览:
| 风格名称 | 特点 | 适用场景 |
|---|---|---|
| Neon Cyber | 未来科技感,粒子效果 | 技术演讲、AI 产品 |
| Midnight Executive | 高端商务,可信赖 | 商业报告、融资路演 |
| Paper & Ink | 编辑风格,文艺气息 | 内容创作、教学分享 |
| Swiss Modern | 简洁几何,包豪斯风格 | 设计展示、极简主义 |
| Brutalist | 原始、大胆、引人注目 | 艺术展示、个性表达 |
输出物特征:生成的演示文稿是一个单文件 HTML,内嵌全部样式与交互代码,无外部依赖,支持键盘方向键/空格翻页、触控滑动手势、鼠标滚轮翻页、进度条与导航点、滚动触发动画和响应式布局:
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<!-- 所有样式内联,零依赖 -->
</head>
<body>
<section class="slide title-slide">
<h1 class="reveal">你的标题</h1>
</section>
<!-- 更多幻灯片... -->
</body>
</html>
课程文档推荐它的理由:1. 零依赖——单个 HTML 文件,10 年后依然能打开;2. 视觉发现——不需要描述设计,选一个喜欢的即可;3. PPT 转换——保留现有内容,套上更好的视觉外壳;4. 生产级代码——无障碍、注释清晰、易于定制。文档提到该仓库星标数在 6.1k+(文档原文引用数据)。
2.5 三个技能对比与查看已装技能
| 技能 | 解决的问题 | 趣味性 | 实用性 |
|---|---|---|---|
| remotion-dev/skills | 用代码制作视频 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| anthropics/skills/frontend-design | 美化前端界面 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| frontend-slides | 快速创建漂亮 PPT | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
安装完成后无需额外配置,当你让 Claude 做相关任务时它会自动调用相应技能。查看已安装技能:
npx skills list
3. Skills 概念解析与目录体系
3.1 技能包的基本构成
技能是存储于文件系统中的"能力包",一个完整的技能目录包含:
- SKILL.md:技能描述文件,必需;
- scripts/:辅助脚本,可选;
- templates/:输出模板,可选;
- references/:参考文档,可选;
- examples/:示例文件,可选。
3.2 Skills 与直接写 Prompt 的区别
一个自然的疑问:技能和直接把指令发给 Claude 有什么区别?
| Prompt | Skills |
|---|---|
| 临时的,每次都要重复 | 永久的,写一次用多次 |
| 存在于聊天记录中,消耗 token | 按需加载,节省 token |
| 无法跨会话共享 | 可在团队间共享 |
| 难以做版本管理 | 可以用 Git 管理 |
3.3 两种技能:个人技能与项目技能
个人技能(通用):
- 存放位置:
~/.claude/skills/ - 作用范围:所有项目
- 适用场景:个人通用的能力
项目技能(团队):
- 存放位置:
project-directory/.claude/skills/ - 作用范围:当前项目
- 适用场景:团队共享与项目特定的约定
3.4 启动时发生了什么
Claude Code 启动时会执行一条固定的扫描链路:
- 扫描技能目录;
- 解析每个
SKILL.md文件; - 提取 YAML frontmatter 元数据;
- 将技能描述加入其"知识库";
- 后续根据描述自动匹配触发。
4. SKILL.md 文件结构详解
4.1 目录结构与两部分组成
一个完整的技能指南目录长这样:
my-skill/
├── SKILL.md # 必需:技能描述文件
├── scripts/ # 可选:辅助脚本
├── templates/ # 可选:输出模板
├── references/ # 可选:参考文档
└── examples/ # 可选:示例文件
SKILL.md 文件由两部分组成。
第 1 部分:YAML Frontmatter(元数据)
---
name: skill-name # 技能名,将成为 /skill-name 命令
description: short description # 用于 Claude 的自动触发匹配
category: development # 分类
tags: # 标签
- code
- automation
---
第 2 部分:Markdown 正文(指令)
# 技能标题
## 使用场景
什么时候使用这个技能
## 执行步骤
1. 第一步
2. 第二步
## 注意事项
- 注意点1
- 注意点2
4.2 关键字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 技能名称,只允许小写字母、数字和连字符 |
description |
是 | 技能描述,越具体越有利于 Claude 自动匹配 |
category |
否 | 分类 |
tags |
否 | 附加标签 |
allowed-tools |
否 | 无需额外授权即可使用的工具 |
更严格的解析约束见第 11 节:name 最长 64 个字符,description 直接决定 LLM 自动匹配的成败。
5. Skills 与 MCP:到底差在哪
很多初学者会把 Skills 和 MCP(Model Context Protocol,配套章节见 docs/ar-sa/stage-3/core-skills/mcp/index.md)混为一谈,但两者完全是两回事。
5.1 核心差异
| 维度 | Skills | MCP |
|---|---|---|
| 本质 | 知识与工作流 | 工具与接口 |
| 提供什么 | 告诉 AI"怎么做" | 给 AI"能用什么" |
| 存放位置 | skills/ 目录 |
MCP 服务器 |
| 配置形式 | Markdown 文件 | JSON 配置文件 |
| 激活方式 | /skill-name 或自动识别 |
配置后自动加载 |
一个直观的类比:如果 Claude 是个"工人"——MCP 是给他的"工具"(扳手、电脑、访问权限);Skills 是给他的"操作手册"(怎么做代码评审、怎么提交代码)。
5.2 二者是互补关系
它们不互相竞争,而是一个任务中的上下游:
用户需求 -> Claude 识别任务
↓
加载相关技能(知道怎么做)
↓
通过 MCP 调用工具(有可用工具)
↓
完成任务
以"代码审查"场景为例:技能定义了审查步骤、检查清单和输出格式;MCP 提供访问 GitHub Pull Request、拉取代码 diff 的能力。技能告诉 Claude"怎么审",MCP 给 Claude"能拿到代码"的能力。
这个分工在当前仓库的配置中可以得到印证:仓库根目录下的 config/mcporter.json 就是一份真实的 MCP 服务器配置——它注册了一个名为 autoglm-browser-agent 的本地 MCP 服务(一个浏览器自动化服务器,带窗口尺寸、步数上限等启动参数)。注意两点:其一,它配置的是"工具能力"(能控制浏览器)而非"操作知识"(怎么操作),正是 5.1 表格中 MCP 那一列的定义;其二,命令路径指向 ~/.agents/skills/autoglm-browser-agent/ 目录——从源码结构看,这正是 Skills 生态把技能包安装到用户级 .agents/skills/ 目录下的实际形态,与 2.1 节 Windows 适配版要求替换的 C:/Users/你的用户名/.agents/skills/find-skills 路径互为印证。
5.3 选型建议
| 你的需求 | 推荐方案 |
|---|---|
| 需要定义工作流 | 用 Skills |
| 需要访问外部数据 | 用 MCP |
| 两者都需要 | 一起用 |
6. 技能资源与检索技巧
官方资源:Anthropic 官方 Skills 仓库(anthropics/skills,含 skill-creator、mcp-builder、slack-gif-creator 等官方示例技能)与 Claude Code 官方文档的 Skills 配置章节。
社区资源(课程文档列举的仓库名称,可在代码托管平台直接搜索):
| 仓库 | 说明 |
|---|---|
| shanraisshan/claude-code-best-practice | 由 Claude Code 负责人 Boris Cherny 参与维护,含技能、Agent、Hooks 等最佳实践 |
| affaan-m/everything-claude-code | 包含预配置技能的全家桶 |
| JackyST0/awesome-agent-skills | 精选技能资源列表 |
| jeffallan/claude-skills | 66 个专业技能 + 300+ 参考文档 |
| vercel-labs/agent-skills | Vercel Labs 官方 Agent Skills 集合,含 find-skills |
检索技巧:
- 使用具体关键词:"react testing" 优于笼统的 "testing";
- 组合"领域 + 动作":"nextjs deploy"、"typescript lint";
- 优先选择安装量高的技能,10K+ 通常意味着经过充分验证;
- 关注趋势榜发现新兴技能。
7. 创建你自己的技能
有两条路:直接让 Claude 帮你写,或使用 skill-creator 工具。
7.1 方式一:直接让 Claude 帮你创建
最简单的方式,直接用自然语言描述需求:
帮我创建一个叫 "format-code" 的技能,用于自动格式化代码。
需求:
1. 自动检测编程语言
2. 应用相应的格式化规则
3. 返回格式化前后的差异
Claude 会自动完成:1. 创建目录结构;2. 生成 SKILL.md 文件;3. 填写 YAML frontmatter;4. 写入技能内容。
适用场景:快速创建简单技能;知道自己要什么但不熟 SKILL.md 格式;想快速迭代修改。
7.2 方式二:使用 skill-creator
skill-creator 是官方的技能创建工具,会一步步引导你完成流程。安装:
npx skills add anthropics/skills@skill-creator -g
或者安装整个官方技能仓库:
npx skills add anthropics/skills -g
使用:输入 /skill-creator,然后按提示填写技能名称、功能描述、使用场景、执行步骤。它的工作流是:1. 引导你明确技能目的;2. 生成 SKILL.md 草稿;3. 创建测试用例;4. 运行评估与优化。
适用场景:创建复杂技能;需要更规范的创建流程;希望对技能做测试和验证。
7.3 两种方式对比
| 方式一:直接创建 | 方式二:skill-creator |
|---|---|
| 快速简单 | 引导式步骤 |
| 适合简单技能 | 适合复杂技能 |
| 对话中直接完成 | 流程规范化 |
| 修改灵活 | 包含测试和验证 |
7.4 如何写好需求描述
好的需求描述:
创建一个 "git-commit" 技能,自动提交代码。
执行步骤:
1. 检查修改的文件
2. 生成符合 Conventional Commits 规范的提交信息
3. 执行 git commit
4. 询问是否需要 push
注意事项:
- 提交前检查敏感信息
- 不要提交 dist/、node_modules/ 等目录
差的需求描述:
帮我写一个提交代码的技能
后者太模糊,Claude 不知道具体该做什么。
8. 四个完整技能示例
以下四个示例是课程文档的完整原文示例,可直接复制到自己机器的 ~/.claude/skills/ 下使用。
8.1 示例一:代码审查技能(review-pr)
创建目录:
mkdir -p ~/.claude/skills/review-pr
写入技能文件:
cat > ~/.claude/skills/review-pr/SKILL.md << 'EOF'
---
name: review-pr
description: Review Pull Requests for code quality, security, and test coverage
---
You are a senior code reviewer.
## Review workflow
1. **Code style check**
- Does the code follow team conventions?
- Are names clear?
- Are comments sufficient?
2. **Security check**
- Are there security vulnerabilities?
- Is sensitive information exposed?
- Is input validation complete?
3. **Testing check**
- Are there enough tests?
- Do test cases cover edge conditions?
- Are the tests runnable?
4. **Overall evaluation**
- What are the strengths?
- What needs improvement?
- Do you recommend approving the merge?
## Output format
Please output the review results in a clear structure using a list format.
EOF
使用方式:
/review-pr
请审查当前分支的 Pull Request
8.2 示例二:Git 自动提交技能(git-commit)
mkdir -p ~/.claude/skills/git-commit
cat > ~/.claude/skills/git-commit/SKILL.md << 'EOF'
---
name: git-commit
description: Automatically detect changes, generate a commit message, and commit the code
---
You are a skilled Git user.
## Execution workflow
1. **Check changes**
Run `git status` to view modified files
Run `git diff` to view detailed changes
2. **Generate commit message**
Analyze the nature of the changes
Generate a commit message that follows Conventional Commits
Format: `type(scope): description`
3. **Security check**
Check whether there is sensitive information such as keys, passwords, or tokens
Check whether directories that should not be committed are included
4. **Execute after confirmation**
Show the commit message for confirmation
Run `git add` and `git commit`
Ask whether a push is needed
## Notes
- Do not commit directories such as node_modules/, dist/, or .next/
- Run tests before committing to ensure the code works
- The commit message should clearly explain the change
EOF
使用方式:输入 /git-commit 即可。
8.3 示例三:测试生成技能(gen-test)
mkdir -p ~/.claude/skills/gen-test
cat > ~/.claude/skills/gen-test/SKILL.md << 'EOF'
---
name: gen-test
description: Automatically generate unit tests for code to ensure correctness
---
You are a test engineer.
## Workflow
1. **Analyze the code**
- Understand the function or class
- Identify inputs and outputs
- Find edge cases
2. **Generate tests**
- Use an appropriate test framework
- Cover normal cases
- Cover edge cases
- Cover exceptional cases
3. **Validate the tests**
- Make sure the tests can run
- Make sure the tests can catch problems
- Do not over-mock the implementation
## Test frameworks
- JavaScript/TypeScript: Jest or Vitest
- Python: pytest
- Go: testing package
## Output format
Output the test code first, then explain how to run the tests.
EOF
使用方式:
/gen-test
为 src/utils.ts 生成单元测试
8.4 示例四:文档生成技能(gen-readme)
mkdir -p ~/.claude/skills/gen-readme
cat > ~/.claude/skills/gen-readme/SKILL.md << 'EOF'
---
name: gen-readme
description: Automatically generate a README document for a project
---
You are a technical documentation expert.
## Workflow
1. **Analyze the project**
- Scan the project directory structure
- Check package.json or other configuration files
- Read the existing code
2. **Generate content**
- Project introduction
- Installation steps
- Usage instructions
- API documentation
- Development guide
3. **Formatting**
- Use a clear section structure
- Add code examples
- Add appropriate badges
- Add license information
## Standard README structure
- Project title and introduction
- Features
- Installation
- Quick start
- Usage instructions
- API documentation
- Development guide
- Contribution guide
- License
EOF
使用方式:
/gen-readme
为当前项目生成 README 文档
9. 进阶技巧
9.1 与 Hooks(钩子)结合
Hooks 能在特定事件发生时自动执行动作。把它和 Skills 结合,可以实现更强的自动化。例如"保存后自动格式化代码":
{
"hooks": {
"PostToolUse": [{
"matcher": {
"tool_name": "Edit"
},
"hook": {
"type": "command",
"command": "/format-code"
}
}]
}
}
该配置保存在 .claude/hooks.json 中,含义是:当 Claude 使用 Edit 工具编辑文件后(PostToolUse 事件),自动调用 format-code 技能完成格式化。
9.2 与 Commands(命令)结合
命令是简单的快捷指令,技能是复杂的工作流,两者可以配合使用——简单的动作用命令,复杂的流程沉淀为技能。
9.3 团队协作与版本控制
共享项目技能:
- 把技能放到项目下的
.claude/skills/目录; - 用 Git 提交;
- 团队成员克隆项目后即可使用。
版本控制能力:
- 技能可以像代码一样做版本管理;
- 每次提交都记录了技能的变更;
- 可以回滚到旧版本。
10. 常见问题(FAQ)
Q1:技能为什么没有生效?
可能原因:YAML frontmatter 格式错误;描述不够具体;没有重启 Claude Code。排查方法:检查 YAML 格式是否正确;改进描述,加入具体的使用场景关键词;重启 Claude Code。
Q2:如何写出精准的 description?
好的描述应包含:技能的具体功能、使用场景("当用户提到……时")、触发关键词。
差的例子:
description: Review code
好的例子:
description: Review Pull Request code. Trigger when the user mentions PR, review, or code review.
Q3:技能和命令有什么区别?
| 命令 | 技能 |
|---|---|
| 简单的快捷指令 | 完整的工作流 |
单个 .md 文件 |
目录结构(SKILL.md + 可选文件) |
| 手动触发 | 可自动触发 |
| 适合简单操作 | 适合复杂操作 |
Q4:如何调试技能?
- 使用
/skills检查技能是否被识别; - 直接输入技能名手动触发;
- 检查
SKILL.md内容是否正确; - 查看 Claude Code 的日志。
11. 深入阅读:Skills 的底层工作机制
这一节回答"为什么 Skills 要这样设计"。
11.1 核心事实:技能不是可执行代码
Skills 本质上是被"注入"进 Claude 上下文的高级指令(Prompt)。这个设计可称为"基于提示词的动态上下文注入与元工具架构"(Prompt-based Dynamic Context Injection & Meta-Tool Architecture):
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ 用户请求 │ ───> │ LLM 匹配 │ ───> │ 触发技能 │
└─────────────┘ │ 描述文字 │ └──────────────┘
└─────────────┘ │
▼
┌──────────────┐
│ 注入完整指令 │
└──────────────┘
│
▼
┌──────────────┐
│ 执行任务 │
└──────────────┘
11.2 三层渐进式加载(Token 经济学)
为了在拥有大量技能时不消耗过多 token,Claude 使用三层渐进加载机制:
| 层 | 内容 | 加载时机 | Token 成本 |
|---|---|---|---|
| 第 1 层:元数据 | YAML frontmatter(name + description) | Claude 启动时 | 每技能约 30–50 token |
| 第 2 层:指令 | SKILL.md 全文 |
技能被触发时 | 约 5,000 token |
| 第 3 层:资源 | 脚本、模板、参考文档 | 需要时从文件系统按需读取 | 不进入上下文 |
效果:假设你装了 100 个技能,启动时只为元数据消耗约 3,000–5,000 token;只有被触发的技能才加载完整内容;参考文档等资源文件永远不会全量载入上下文。课程文档给出的对比估算:
无技能:每轮对话需要 50,000+ token 来描述所有能力
有技能:启动时约 100 token/技能 + 触发时按需加载 5,000 token
节省:平均每轮对话节省 40,000+ token
11.3 双通道上下文注入
触发一个技能时,系统同时做两件事。
(1)注入对话上下文——用户看到一条可见消息,而模型收到一条隐藏的元消息(isMeta 标记使其不出现在界面):
// 用户看到的(可见消息)
<command-message>The "pdf" skill is loading</command-message>
// 模型实际收到的(隐藏元消息)
{
isMeta: true, // 标记为元消息,不在 UI 中显示
content: `
# PDF 分析专家指令
你是一名专业的 PDF 分析专家。工作流:
1. 使用 pdftotext 提取文本
2. 分析文档结构
3. 生成摘要报告
...
` // 完整的 SKILL.md 内容,可能数千字
}
(2)调整执行上下文——技能还可以动态修改 Claude 的运行环境:
| 调整类型 | 示例 | 说明 |
|---|---|---|
| 工具授权 | allowed-tools: "Bash(pdftotext:*)" |
临时授予特定工具的访问权限 |
| 切换模型 | 从 Sonnet 切到 Opus | 复杂任务需要更强推理能力 |
| 上下文隔离 | 创建子会话空间 | 避免污染主对话上下文 |
11.4 基于 LLM 推理的触发路由
一个关键的设计决策:Skills 不使用固定编码的路由。
| 传统方案 | Claude Skills |
|---|---|
| ❌ 嵌入向量匹配 | ✅ 纯 LLM 推理 |
| ❌ 分类器 | ✅ Transformer 前向传播 |
| ❌ 正则或关键词匹配 | ✅ 自然语言理解 |
| ❌ 独立路由算法 | ✅ 模型统一决策 |
工作流:1. 每个技能的名称与描述被组织成技能工具的描述文字;2. Claude 收到用户消息、可用工具列表(含技能工具描述)、以及 name + description 组成的技能列表;3. Claude 的自然语言理解把用户意图与技能描述做匹配;4. 匹配成功则发起 command: "skill-name" 调用。
为什么这样设计?固定编码路由需要额外的维护成本、无法理解复杂的语义关系、难以处理多语言、不支持模糊匹配;而纯 LLM 推理直接复用 Claude 自身的语言能力,自动处理多语言、同义词和模糊描述,不需要额外维护。
11.5 文件解析流程
技能目录的完整形态(比 3.1 节更详细):
my-custom-skill/
├── SKILL.md # 必需:核心描述文件
├── config.json # 可选:元数据配置
├── README.md # 推荐:使用说明文档
├── scripts/ # 可选:可执行脚本
├── templates/ # 可选:模板文件夹
└── references/ # 可选:参考文档
Claude Code 启动时的解析流水线:
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 启动 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 扫描 ~/.claude/skills/ 和 .claude/skills/ 目录 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 使用 gray-matter 库解析每个 SKILL.md 的 YAML frontmatter │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 校验必填字段(name 和 description) │
│ - name: 最长 64 字符,仅小写字母、数字、连字符 │
│ - description: 用于 LLM 自动匹配 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 提取元数据,构建技能列表 │
│ (仅加载 name + description,不加载正文) │
└─────────────────────────────────────────────────────────────┘
这也解释了 10.1 节 FAQ 中"YAML frontmatter 格式错误导致技能不生效"的底层原因:frontmatter 解析失败,该技能根本进不了技能列表。
11.6 一次完整执行流示例
以"帮我分析这个 PDF 文件"为例,完整过程分四步:
第 1 步:LLM 决策——Claude 在技能列表中看到 pdf 技能的描述("Analyze PDF document content, extract text, generate a summary"),判定匹配。
第 2 步:系统介入——Claude Code 执行:1. 读取 ~/.claude/skills/pdf/SKILL.md;2. 生成可见消息"The pdf skill is loading";3. 生成隐藏的 isMeta 元消息(完整 SKILL.md 内容);4. 修改会话授权 allowed-tools = ["Bash(pdftotext:*)"]。
第 3 步:LLM 执行——Claude 的上下文此时包含:用户原始请求、PDF 专家工作流指令、pdftotext 工具权限。它随后依次执行:用 pdftotext 提取文本 → 分析内容结构 → 生成摘要报告 → 展示给用户。
第 4 步:用完即弃——任务完成后,技能完整内容从上下文中移除(对话记录保留,但技能指令本身不再占用上下文)。
11.7 设计创新与学术渊源
| 创新点 | 传统方式 | Skills 方式 | 优势 |
|---|---|---|---|
| 能力来源 | 固定于模型权重 | 动态加载的指令 | 可扩展、可更新 |
| Token 效率 | 所有能力常驻内存 | 按需加载 | 节省 80%+ token |
| 知识管理 | 散落在聊天记录中 | 规范化文件系统 | 可版本控制、可共享 |
| 生命周期 | 持续占用 | 用完即弃 | 上下文更干净 |
课程文档指出该设计借鉴了以下研究方向:
| 研究领域 | 代表工作 | 在此的体现 |
|---|---|---|
| 强化学习 | Voyager (2023) | 技能库积累的思想 |
| 认知科学 | ACT-R、Soar | 程序性记忆与陈述性记忆的分离 |
| 分层策略 | Options Framework | 三层渐进加载 |
其背后的思维转变是:传统范式里 AI 要"记住一切",而 Skills 范式里 AI"知道去哪里找专业知识"——结果更接近人类专家的思维模式。
11.8 与 Agent Skills 开放标准的关系
Claude 技能遵循 Agent Skills 开放标准(agentskills.io 规范),意味着跨平台兼容(Cursor、Windsurf、Aider 等工具也支持)、文件格式统一、跨工具可互操作。该标准规定的结构为:
Agent Skills 标准定义:
├── 必需:SKILL.md(元数据 + 指令)
├── 可选:scripts/(可执行代码)
├── 可选:references/(知识库文档)
└── 可选:assets/(模板与资源)
11.9 小结:为什么这个设计优秀
- 能力与模型解耦:专业知识不再依赖模型训练,用 Markdown 文件随时更新;
- Token 效率极高:三层加载保证只加载必需内容;
- 借力 LLM 优势:路由与匹配完全依赖 Claude 的语言理解,无额外算法;
- 开发者友好:创建技能只需写 Markdown,不用写代码;
- 可组合:技能之间可以相互引用、组合成复杂工作流;
- 用完即弃:完成后自动清理,保持上下文清爽。
12. 结语
Skills 是把 Claude Code 从"通用助手"变成"团队专家"的钥匙。通过它,你可以统一工作流、沉淀并复用团队知识、提高协作效率、消除重复解释。记住课程文档留下的那条核心判断准则:如果你发现自己两次重复了同样的指令,就应该考虑把它做成一个技能。
本节的源文档为 docs/ar-sa/stage-3/core-skills/skills/index.md,同主题的简体中文版见 docs/zh-cn/stage-3/core-skills/skills/index.md;Skills 在课程学习路线中的位置见 docs/ar-sa/stage-3/index.md(Stage 3 核心技能模块),其前置配套章节包括 Claude Code 快速上手(basics)与 MCP 协议(mcp),进阶方向还有 Superpowers 工程化框架(superpowers)与长时任务(long-running-tasks)。