Claude Code Skills 完全指南:从安装体验到自定义创作,再到内部机制原理(easy-vibe Stage 3 实战)
Claude Code Skills 完全指南:从安装体验到自定义创作,再到内部机制原理(easy-vibe Stage 3 实战)
导读
本文是 Datawhale easy-vibe 项目 Stage 3「核心技能」体系中的 Claude Code Skills 实战指南,系统讲解 Skills 的安装、搜索、使用、自定义创建与底层工作机制。读完本文,你将掌握通过 find-skills 一键发现并安装技能包、用自然语言驱动 Claude 制作视频/美化前端/生成 PPT,并能独立编写 SKILL.md 打造属于自己的团队技能库,同时理解其"提示词动态注入"的设计原理。
Skills 简介:把专业知识打包成可复用的技能
Claude Code Skills 是一种将专业知识、工作流程和最佳实践打包成"可复用技能包"的功能。可以把 Skills 想象成给 Claude 配备的"技能书"——当你需要它完成特定任务时,它不再需要你一遍遍解释要求,而是直接按照预先定义好的技能标准执行工作。
在没有 Skills 之前,使用 Claude Code 存在几个明显问题:
- 重复指令:每次都要解释"代码要符合什么风格""提交信息要怎么写"
- 知识无法沉淀:团队成员各自的使用经验无法共享
- 标准不统一:不同的人用 Claude,结果可能完全不同
- 效率低下:常见任务每次都要从头解释
Skills 恰好解决这些问题,让 Claude 变成一个"有经验的团队成员"——它知道你的项目规范、工作流程和最佳实践。
为什么现在要学 Skills
Skills 正在成为 AI 工程师的必备技能,主要体现在几个方面:
- 社区热度高:GitHub 上相关仓库星标快速增长,例如 OpenSkills 项目已收获 7.2k stars,Obsidian Skills 9 天暴涨 6.6k stars(数据来自本教程编写时记录的社区公开信息)
- 官方支持:Anthropic 官方维护 Skills 仓库,Vercel 推出 Agent Skills 和
find-skills工具 - 实用性强:从代码审查、Git 操作到视频制作、PPT 生成,覆盖多种场景
- 效率提升:一次配置,反复使用,让 Claude 真正成为你的"数字员工"
- 开发者认可:多个技术社区推荐,被广泛认为是提升 AI 编程效率的关键工具
在 easy-vibe 的 Stage 3 课程体系中,Skills 与 MCP、Agent Teams、Superpowers、Spec Coding 等共同构成"核心技能"章节(见 skills 目录,简体中文版),是进阶 AI 编程的必修模块。
快速开始:安装 find-skills 并上手第一个 Skill
理解了 Skills 的价值后,让我们马上动手体验:安装第一个 Skill,并完成几个有趣的实战任务,快速建立直观认识。
第一步:安装 find-skills(强烈推荐必装)
在开始使用 Skills 之前,强烈推荐先安装 find-skills——这是 AI Agent 领域的"技能搜索神器"。简单来说,find-skills 就像 AI Agent 的"应用商店搜索器":当你需要完成某个任务但本地没有对应 Skill 时,它会自动帮你搜索并推荐最合适的。
安装命令:
npx skills add vercel-labs/skills@find-skills -g -y
安装完成后,可以直接告诉 Claude 你的需求,它会通过 find-skills 自动搜索相关技能。例如:
我需要做一个 React 组件的性能优化,帮我找找有什么技能可以用
Claude 会通过 find-skills 搜索,然后告诉你找到了哪些相关技能,供你选择安装。
为什么先装 find-skills?
| 安装前 | 安装后 |
|---|---|
| 手动在 GitHub 搜索相关技能 | 一句话描述需求 |
| 逐个复制、安装、配置 | AI 自动搜索最匹配的技能 |
| 反复调试适配 | 一键安装,立即可用 |
Windows 用户注意:官方版本对 Windows 支持有限,社区制作了 Windows 适配版本,支持 CMD 和 PowerShell,并增加了中文搜索功能。安装步骤为:下载 Windows 版本的 SKILL.md → 替换 C:/Users/你的用户名/.agents/skills/find-skills 目录下的文件 → 重启 Claude Code 生效。
安装并体验第一个 Skill:Remotion 视频制作
用 find-skills 搜索并安装第一个好玩的 Skill——Remotion 视频制作工具:
- 搜索 Remotion:在 Claude Code 中输入
帮我找找 Remotion 相关的技能,我想做视频,Claude 会推荐remotion-dev/skills - 安装:
npx skills add remotion-dev/skills -g
- 用它做点好玩的:Remotion 是一个用 React 代码制作视频的框架,安装后可让 Claude 用自然语言帮你写视频代码。
任务 1:炫酷的文字动画视频
用 Remotion 做一个视频:
- 1920x1080,5 秒
- 一行文字 "Hello World" 从左边飞进来
- 同时带旋转和缩放效果
- 背景是渐变色
任务 2:数据可视化视频
做一个 10 秒的视频,展示数据增长:
- 开始是一个柱状图
- 柱子逐个长高(带动画)
- 数字滚动增加
- 最后显示 "增长 300%" 的大字
任务 3:多场景演示视频
做一个产品演示视频,三个场景:
场景 1:Logo 淡入显示,2 秒
场景 2:产品特性列表逐个出现,3 秒
场景 3:CTA 按钮弹出,2 秒
每个场景之间有平滑过渡
运行代码:Claude 生成的是完整 Remotion 项目,可执行:
npx create-video my-video # 创建新项目
npm start # 运行预览
npm run build # 渲染视频
把 Claude 生成的代码复制进项目即可(npm start 预览、npm run build 渲染成片)。
第二个 Skill:用 find-skills 解决"前端又丑又卡"
用自然语言描述问题
直接告诉 Claude 你的抽象需求:
我的网页看起来很土,而且加载很慢,帮我找找有什么技能可以用
或更具体一点:
我想让前端变好看,然后别那么卡
Claude 用 find-skills 搜索
Claude 会通过 find-skills 搜索技能库并推荐相关技能。对于"变好看 + 不卡"的需求,会推荐 anthropics/skills/frontend-design(官方技能)。这个技能专门解决 AI 生成的界面"看起来很土"的问题,让 Claude 设计出:
- 独特的视觉风格(避开千篇一律的"AI 模板感")
- 专业的配色和字体
- 流畅的动画效果
- 生产级别的代码质量(代码干净,性能自然好)
安装并使用
npx skills add anthropics/skills/frontend-design -g
安装后可以用它完成的任务示例:
帮我重新设计这个页面,要看起来很专业,别像 AI 生成的
这个 UI 太丑了,用更现代的设计风格重写
做一个暗色主题的 Dashboard,要有科技感
Claude 会根据技能规范帮你设计:独特的视觉方向(极简主义、复古未来主义、野兽派等)、精心挑选的配色和字体、合理的间距和布局、流畅的交互动画。
两个 Skills 的对比
| Skills | 解决什么问题 | 好玩程度 |
|---|---|---|
| remotion-dev/skills | 用代码做视频 | ⭐⭐⭐⭐⭐ |
| anthropics/skills/frontend-design | 让前端变好看 | ⭐⭐⭐⭐ |
第三个 Skill:用 frontend-slides 快速制作精美 PPT
frontend-slides 是一个让你用自然语言创建精美 HTML 演示文稿的 Skill——即使你不懂任何 CSS 或 JavaScript。它的核心特点是"展示而非讲述":当你描述不出想要的设计风格时,它会生成 3 个视觉预览让你选择,而不是让你用语言描述"蓝色背景、大字体"这种抽象需求。
安装 frontend-slides
方式一:手动安装
# 创建 skill 目录
mkdir -p ~/.claude/skills/frontend-slides
# 下载 SKILL.md 和 STYLE_PRESETS.md
# 放到 ~/.claude/skills/frontend-slides/ 目录
方式二:使用 find-skills 安装
帮我找找做 PPT 演示文稿相关的技能
Claude 会通过 find-skills 搜索并推荐 frontend-slides。
使用场景
场景 1:从零创建演示文稿
/frontend-slides
我想创建一个 AI 创业项目的融资路演 PPT,大概 10 页
Claude 会引导你:询问每页内容(标题、要点、图片)→ 询问想要的风格感觉(惊艳?专业?温馨?)→ 生成 3 个视觉风格预览供选择 → 创建完整 HTML 演示文稿 → 在浏览器中打开预览。
场景 2:转换 PowerPoint 文件
/frontend-slides
把我的 presentation.pptx 转成网页版演示
Claude 会:提取 PPT 中的所有文本、图片和备注 → 显示提取内容供确认 → 让你选择视觉风格 → 生成保留所有原始内容的 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>
为什么推荐?
- 零依赖:单个 HTML 文件,10 年后还能打开
- 视觉发现:不用描述设计,直接选择喜欢的
- PPT 转换:保留现有内容,换上更好的皮肤
- 生产级代码:可访问性好、注释清晰、易于定制
三个 Skills 的对比
| Skills | 解决什么问题 | 好玩程度 | 实用程度 |
|---|---|---|---|
| remotion-dev/skills | 用代码做视频 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| anthropics/skills/frontend-design | 让前端变好看 | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
| frontend-slides | 快速制作精美 PPT | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ |
安装后如何使用
安装完成后不需要任何额外配置。当你向 Claude 提出相关任务时,它会自动调用对应的 Skill。查看已安装的 Skills:
npx skills list
Skills 是什么:核心概念与工作原理
核心概念
Skills 是存储在文件系统中的"技能包",包含:
- SKILL.md:技能的定义文件(必需)
- scripts/:辅助脚本(可选)
- templates/:输出模板(可选)
- references/:参考文档(可选)
Skills vs 提示词
| 提示词 | Skills |
|---|---|
| 临时性的,每次都要重复说 | 持久化的,写一次反复用 |
| 存在对话历史中,占用 Token | 按需加载,节省 Token |
| 无法在会话间共享 | 可以在团队中共享 |
| 难以版本控制 | 可以用 Git 管理 |
Skills 的两种类型
全局 Skills(个人):
- 存放位置:
~/.claude/skills/ - 作用范围:所有项目
- 适用场景:个人通用技能
项目 Skills(团队):
- 存放位置:
项目目录/.claude/skills/ - 作用范围:当前项目
- 适用场景:团队共享、项目特定规范
Skills 如何工作
当 Claude Code 启动时,它会:扫描 Skills 目录 → 解析每个 SKILL.md 文件 → 提取 YAML frontmatter 元数据 → 将技能内容加入"知识库" → 根据 description 自动匹配触发。
SKILL.md 文件结构
基本结构
一个完整的 Skill 目录结构如下:
my-skill/
├── SKILL.md # 必需:技能定义文件
├── scripts/ # 可选:辅助脚本
├── templates/ # 可选:输出模板
├── references/ # 可选:参考文档
└── examples/ # 可选:示例文件
SKILL.md 模板
SKILL.md 文件分为两部分。
第一部分:YAML Frontmatter(元数据)
---
name: skill-name # 技能名称,会变成 /skill-name 命令
description: 简短描述 # 用于 Claude 自动匹配触发
category: development # 分类
tags: # 标签
- code
- automation
---
第二部分:Markdown 内容(指令)
# 技能标题
## 使用场景
什么时候用这个技能
## 执行步骤
1. 第一步
2. 第二步
## 注意事项
- 注意点 1
- 注意点 2
关键字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
name |
是 | 技能名称,只能用小写字母、数字、连字符 |
description |
是 | 技能描述,越具体越容易被 Claude 自动匹配 |
category |
否 | 分类标签 |
tags |
否 | 更多分类标签 |
allowed-tools |
否 | 允许使用的工具,无需权限即可用 |
Skills vs MCP:有什么区别?
很多初学者会混淆 Skills 和 MCP,它们是两个完全不同的东西。
核心区别
| 维度 | Skills | MCP |
|---|---|---|
| 本质 | 知识和流程 | 工具和接口 |
| 提供什么 | 告诉 AI "怎么做" | 给 AI "能用什么" |
| 存储位置 | skills/ 目录 |
MCP 服务器 |
| 配置方式 | Markdown 文件 | JSON 配置文件 |
| 触发方式 | /skill-name 或自动识别 |
通过配置自动加载 |
本仓库中的 MCP 配置示例 就是 JSON 配置格式的典型代表,其中通过 mcpServers 字段声明了 MCP 服务器的启动命令与参数;而 Skills 只需要在 skills/ 目录里放一个 Markdown 文件。这也是两者配置方式差异的直观印证(更多 MCP 内容见 MCP 专题章节)。
形象比喻
如果把 Claude 比作一个"工作人员":
- MCP 是给这个工作人员配备的"工具"(扳手、电脑、访问权限)
- Skills 是给这个工作人员的"操作手册"(怎么做代码审查、怎么提交代码)
它们的关系
Skills 和 MCP 不是竞争关系,而是互补关系:
用户任务 → Claude 识别需求
↓
加载相关 Skills(知道怎么做)
↓
通过 MCP 调用工具(有工具可用)
↓
完成任务
举例说明:代码审查场景
- Skills 定义:审查步骤、检查清单、输出格式
- MCP 提供:访问 GitHub PR、获取代码 diff 的能力
两者配合:Skills 告诉 Claude "怎么审查",MCP 给 Claude "访问代码的能力"。
选择建议
| 你的需求 | 推荐方案 |
|---|---|
| 需要定义工作流程 | 用 Skills |
| 需要访问外部数据 | 用 MCP |
| 需要两者都有 | 配合使用 |
常用 Skills 获取资源
官方资源
- Anthropic 官方 Skills 仓库(
anthropics/skills):官方维护的技能集合 - Claude Code 官方文档 Skills 章节:官方文档
社区资源
| 仓库 | 说明 |
|---|---|
shanraisshan/claude-code-best-practice |
社区维护的资源集合,包含 Skills、Agents、Hooks 等 |
affaan-m/everything-claude-code |
综合工具包,包含预配置 Skills |
JackyST0/awesome-agent-skills |
精选 Skills 资源列表 |
jeffallan/claude-skills |
66 个专业技能,300+ 参考文档 |
ComposioHQ/awesome-claude-skills |
精选 Skills 资源列表 |
obra/superpowers |
软件开发自动化工作流 Skills 集合 |
如何安装社区 Skills
使用 find-skills,只需要告诉 Claude 你需要什么,它会自动搜索并推荐:
帮我找找有什么 React 性能优化相关的技能
Claude 会通过 find-skills 搜索技能库,列出最相关的技能,你选择安装即可。
搜索技巧:
- 使用具体关键词:"react testing" 优于 "testing"
- 组合「领域 + 动作」:"nextjs deploy"、"typescript lint"
- 优先选择高安装量的技能(10K+ 说明经过实战检验)
- 关注 Trending 榜单发现新兴技能
如何创建自己的 Skills
创建 Skills 有两种方法:直接让 Claude 帮你创建,或使用专门的 skill-creator 工具。
方法一:直接让 Claude 帮你创建
这是最简单的方式,直接用自然语言告诉 Claude 你的需求。例如:
请帮我创建一个名为 "format-code" 的 skill,功能是自动格式化代码。
要求:
1. 自动检测编程语言类型
2. 应用对应的格式化规则
3. 返回格式化前后的 diff
Claude 会自动:创建目录结构 → 生成 SKILL.md 文件 → 填写 YAML frontmatter → 编写技能内容。
适用场景:快速创建简单技能;你知道要什么但不熟悉 SKILL.md 格式;想要快速迭代和修改。
方法二:使用 skill-creator
skill-creator 是专门用来创建 Skills 的工具,会引导你一步步完成。
安装:
npx skills add anthropics/skills@skill-creator -g
或安装整个官方 skills 仓库:
npx skills add anthropics/skills -g
使用:
/skill-creator
然后按提示填写:技能名称、功能描述、使用场景、执行步骤。skill-creator 会:引导你明确技能用途 → 生成 SKILL.md 草稿 → 创建测试用例 → 运行评估并优化。
适用场景:创建复杂技能;需要规范的创建流程;想要测试和验证技能。
两种方法对比
| 方法一:直接创建 | 方法二:skill-creator |
|---|---|
| 快速简单 | 步骤引导 |
| 适合简单技能 | 适合复杂技能 |
| 直接对话完成 | 规范流程 |
| 灵活修改 | 有测试验证 |
技巧:如何写好需求
好的需求描述:
创建一个 "git-commit" skill,功能是自动提交代码。
执行步骤:
1. 检查有哪些文件被修改
2. 生成符合 Conventional Commits 规范的提交信息
3. 执行 git commit
4. 询问是否需要 push
注意事项:
- 提交前先检查是否有敏感信息
- 不要提交 dist/node_modules/ 等目录
不好的需求描述:
帮我写一个提交代码的 skill
太模糊了,Claude 不知道具体要做什么。值得注意的是,本仓库自己的 AGENTS.md 也采用了类似的"执行步骤 + 注意事项"结构来约定 AI 的工作方式(例如提交信息遵循 Conventional Commits 风格),这正是"把规范沉淀成可复用指令"的实践体现。
常用 Skills 实例
实例 1:代码审查 Skill
mkdir -p ~/.claude/skills/review-pr
cat > ~/.claude/skills/review-pr/SKILL.md << 'EOF'
---
name: review-pr
description: 审查 Pull Request 的代码质量、安全性和测试覆盖率
---
你是一位资深的代码审查者。
## 审查流程
1. **代码风格检查**
- 代码是否符合团队规范
- 命名是否清晰
- 注释是否充分
2. **安全性检查**
- 是否有安全漏洞
- 敏感信息是否暴露
- 输入验证是否完善
3. **测试检查**
- 是否有足够的测试
- 测试用例是否覆盖边界情况
- 测试是否可运行
4. **总体评价**
- 优点是什么
- 需要改进的地方
- 建议是否批准合并
## 输出格式
请以清晰的结构输出审查结果,使用列表形式。
EOF
使用方式:
/review-pr
请审查当前分支的 PR
实例 2:Git 自动提交 Skill
mkdir -p ~/.claude/skills/git-commit
cat > ~/.claude/skills/git-commit/SKILL.md << 'EOF'
---
name: git-commit
description: 自动检测修改、生成提交信息并提交代码
---
你是一位熟练的 Git 用户。
## 执行流程
1. **检查修改**
运行 `git status` 查看修改的文件
运行 `git diff` 查看具体改动
2. **生成提交信息**
分析改动的性质
生成符合 Conventional Commits 格式的提交信息
格式:`type(scope): description`
3. **安全检查**
检查是否有敏感信息(密钥、密码、token)
检查是否包含了不该提交的目录
4. **确认后执行**
显示提交信息供确认
执行 `git add` 和 `git commit`
询问是否需要 push
## 注意事项
- 不要提交 node_modules/、dist/、.next/ 等目录
- 提交前先运行测试确保代码可用
- 提交信息要清晰说明改动内容
EOF
使用方式:
/git-commit
实例 3:测试生成 Skill
mkdir -p ~/.claude/skills/gen-test
cat > ~/.claude/skills/gen-test/SKILL.md << 'EOF'
---
name: gen-test
description: 为代码自动生成单元测试,确保功能正确性
---
你是一位测试开发工程师。
## 工作流程
1. **分析代码**
- 理解函数/类的功能
- 识别输入和输出
- 找出边界情况
2. **生成测试**
- 使用合适的测试框架
- 覆盖正常情况
- 覆盖边界情况
- 覆盖异常情况
3. **验证测试**
- 确保测试可以运行
- 确保测试能检测到问题
- 不要过度模拟实现
## 测试框架
- JavaScript/TypeScript:Jest 或 Vitest
- Python:pytest
- Go:testing 包
## 输出格式
先输出测试代码,然后说明如何运行测试。
EOF
使用方式:
/gen-test
为 src/utils.ts 生成单元测试
实例 4:文档生成 Skill
mkdir -p ~/.claude/skills/gen-readme
cat > ~/.claude/skills/gen-readme/SKILL.md << 'EOF'
---
name: gen-readme
description: 为项目自动生成 README 文档
---
你是一位技术文档专家。
## 工作流程
1. **分析项目**
- 扫描项目目录结构
- 查看 package.json 或其他配置文件
- 阅读现有代码
2. **生成内容**
- 项目简介
- 安装方法
- 使用说明
- API 文档
- 开发指南
3. **格式化**
- 使用清晰的章节结构
- 添加代码示例
- 添加适当的徽章
- 添加许可证信息
## 标准 README 结构
- 项目标题和简介
- 功能特点
- 安装方法
- 快速开始
- 使用说明
- API 文档
- 开发指南
- 贡献指南
- 许可证
EOF
使用方式:
/gen-readme
为当前项目生成 README 文档
进阶技巧
Skills 与 Hooks 配合
Hooks 可以在特定事件时自动执行操作,结合 Skills 可以实现更强大的自动化。例如"代码保存后自动格式化":
// .claude/hooks.json
{
"hooks": {
"PostToolUse": [{
"matcher": {
"tool_name": "Edit"
},
"hook": {
"type": "command",
"command": "/format-code" // 调用 format-code skill
}
}]
}
}
Skills 与 Commands 配合
Commands 是简单的快捷命令,Skills 是复杂的工作流,两者可以配合使用:用 Command 快速触达入口,用 Skill 承载完整流程。
团队协作
共享项目 Skills:
- 将 Skills 放在
.claude/skills/目录 - 提交到 Git 仓库
- 团队成员克隆项目后即可使用
版本控制:
- Skills 可以像代码一样进行版本控制
- 每个 commit 都可以记录 Skills 的变更
- 可以回滚到旧版本
常见问题
Q1:Skill 没有被触发?
可能的原因:YAML frontmatter 格式错误;description 不够具体;Claude Code 没有重启。
解决方法:检查 YAML 格式是否正确;改进 description,包含具体的使用场景;重启 Claude Code。
Q2:description 怎么写才准确?
好的 description 包含:技能的具体功能、使用场景("当用户提到...")、触发关键词。
不好的例子:
description: 审查代码
好的例子:
description: 审查 Pull Request 的代码。当用户提到 PR、review、代码审查时触发。
Q3:Skills 和 Commands 的区别?
| Commands | Skills |
|---|---|
| 简单快捷命令 | 完整工作流 |
单个 .md 文件 |
目录结构(SKILL.md + 可选文件) |
| 手动触发 | 可自动触发 |
| 适合简单操作 | 适合复杂流程 |
Q4:如何调试 Skill?
- 使用
/skills查看技能是否被识别 - 直接输入技能名称手动触发
- 检查
SKILL.md文件内容是否正确 - 查看 Claude Code 日志
深入原理:Claude Skills 的内部机制
掌握使用之后,我们来深入理解 Claude Skills 的底层设计,让你不仅会用,还知道为什么这样设计。
底层原理:基于提示词的动态上下文注入
首先理解一个关键事实:Skills 不是可执行代码。它们本质上是高级指令(prompts),在需要时被"注入"到 Claude 的上下文中。这种设计被称为"基于提示词的动态上下文注入与元工具架构"(Prompt-based Dynamic Context Injection & Meta-Tool Architecture):
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ User Request│ ───> │ LLM Matches │ ───> │ Trigger Skill│
└─────────────┘ │Description │ └──────────────┘
└─────────────┘ │
▼
┌──────────────┐
│ Inject Full │
│ Instructions │
└──────────────┘
│
▼
┌──────────────┐
│ Execute Task │
└──────────────┘
三层渐进加载架构(Token 优化)
为了管理大量 Skills 而不消耗过多 Token,Claude 使用智能的三层加载机制:
| 层 | 内容 | 何时加载 | Token 成本 |
|---|---|---|---|
| 第 1 层:元数据 | YAML frontmatter(name + description) | Claude 启动时 | 约 30-50 tokens/个 |
| 第 2 层:指令 | SKILL.md 完整内容 |
技能被触发时 | 约 5,000 tokens |
| 第 3 层:资源 | scripts、templates、references | 按需从文件系统读取 | 不加入上下文 |
设计优势:假设有 100 个 Skills,启动时仅消耗约 3,000-5,000 tokens 加载元数据;只有被触发的 Skill 才加载完整内容;参考文档等资源文件永远不会整体载入上下文。
对比不使用 Skills 的情况:
Without Skills: every conversation needs 50,000+ tokens to describe all capabilities
With Skills: startup ~100 tokens/skill + 5,000 tokens loaded on demand
Savings: on average 40,000+ tokens saved per conversation
双重上下文注入机制
当一个 Skill 被激活时,系统同时做两件事:
1. 注入对话上下文
// 用户看到的(可见消息)
<command-message>The "pdf" skill is loading</command-message>
// AI 实际收到的(隐藏的 meta-message)
{
isMeta: true, // 标记为元消息,不显示在 UI 中
content: `
# PDF Analysis Expert Instructions
You are a professional PDF analysis expert. Workflow:
1. Use pdftotext to extract text
2. Analyze the document structure
3. Generate a summary report
...
` // SKILL.md 完整内容,可能数千词
}
2. 修改执行上下文:除注入指令外,Skill 还可以动态修改 Claude 的运行环境:
| 修改类型 | 示例 | 说明 |
|---|---|---|
| 工具权限 | allowed-tools: "Bash(pdftotext:*)" |
临时授予特定工具的访问权限 |
| 模型切换 | 从 Sonnet 切换到 Opus | 复杂任务需要更强的推理能力 |
| 上下文隔离 | 创建子会话空间 | 避免污染主对话上下文 |
完全基于 LLM 推理的路由机制
这是一个非常重要的设计决策:Claude Skills 不使用硬编码路由。
| 传统方案 | Claude Skills |
|---|---|
| Embedding 向量匹配 | 纯 LLM 推理 |
| 分类器 | Transformer 前向传播 |
| 正则/关键词匹配 | 自然语言理解 |
| 独立路由算法 | 统一模型决策 |
工作流程:
1. 每个 Skill 的 name 和 description 被格式化为 Skill 工具的描述
2. Claude 接收:
- 用户消息
- 可用工具列表(包含 Skill 元工具)
- Skill 列表(name + description)
3. Claude 通过自然语言理解将用户意图匹配到 Skill 描述
4. 匹配成功后,调用:command: "skill-name"
为什么这样设计? 硬编码路由需要额外维护成本、无法理解复杂语义关系、难以处理多语言、不支持模糊匹配;而纯 LLM 推理能利用 Claude 自身的语言理解能力,自动处理多语言、同义词和模糊描述,无需额外维护,路由决策更智能。
文件解析机制
SKILL.md 的完整目录结构:
my-custom-skill/
├── SKILL.md # 必需:主定义文件
├── config.json # 可选:元数据配置
├── README.md # 推荐:使用文档
├── scripts/ # 可选:可执行脚本
├── templates/ # 可选:模板目录
└── references/ # 可选:参考文档
解析流程:
┌─────────────────────────────────────────────────────────────┐
│ Claude Code 启动 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 扫描 ~/.claude/skills/ 和 .claude/skills/ 目录 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 使用 gray-matter 库解析每个 SKILL.md 的 YAML frontmatter │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 校验必填字段(name 和 description) │
│ - name:最多 64 字符,仅限小写字母、数字、连字符 │
│ - description:用于 LLM 自动匹配 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 提取元数据并构建 Skill 列表 │
│ (只加载 name + description,不加载完整正文) │
└─────────────────────────────────────────────────────────────┘
完整执行流程示例
以"分析 PDF 文件"为例看完整链路:
User: "Help me analyze this PDF file"
Step 1: LLM 决策
────────────────
Claude 在 Skill 列表中找到 "pdf" skill 的描述:
description: "Analyze PDF document content, extract text, generate a summary"
Step 2: 系统介入
────────────────
Claude Code 执行:
1. 读取 ~/.claude/skills/pdf/SKILL.md
2. 生成可见消息:"The pdf skill is loading"
3. 生成隐藏的 meta-message:SKILL.md 完整内容
4. 修改会话权限:allowed-tools = ["Bash(pdftotext:*)"]
Step 3: LLM 执行
────────────────
此时 Claude 的上下文中包含:
- 原始用户请求
- PDF 专家工作流指令
- pdftotext 工具的访问权限
Claude 执行:
1. 用 pdftotext 提取 PDF 文本
2. 分析内容结构
3. 生成摘要报告
4. 将结果呈现给用户
Step 4: 用后即焚
────────────────
任务完成后,Skill 完整内容从上下文中移除
(仅保留对话历史,不保留完整技能指令)
关键设计创新
| 创新点 | 传统方案 | Skills 方案 | 优势 |
|---|---|---|---|
| 能力来源 | 固定在模型权重中 | 动态加载的提示词 | 可扩展、可修改 |
| Token 效率 | 所有能力常驻内存 | 按需加载 | 节省 80%+ Token |
| 知识管理 | 分散在对话历史中 | 模块化文件系统 | 可版本化、可共享 |
| 生命周期 | 持续占用空间 | 用后即焚 | 上下文更干净 |
学术基础
Claude Skills 的设计借鉴了以下研究:
| 研究领域 | 代表性工作 | 在此处的应用 |
|---|---|---|
| 强化学习 | Voyager (2023) | 技能库积累的思想 |
| 认知架构 | ACT-R、Soar | 程序性记忆与陈述性记忆分离 |
| 分层策略 | Options Framework | 三层渐进加载 |
根本性视角转变:
Traditional: AI needs to remember everything
↓
Skills: AI knows where to find specialized knowledge
↓
Result: more like the thinking pattern of a human expert
与 Agent Skills 标准的关系
Claude Skills 遵循开放的 Agent Skills 标准(agentskills.io),这意味着:
- 跨平台兼容:Cursor、Windsurf、Aider 等工具同样支持
- 统一文件格式:标准化的
SKILL.md结构 - 可互操作:Skills 可以在不同工具间共享
Agent Skills standard defines:
├── Required: SKILL.md file (metadata + instructions)
├── Optional: scripts/ (executable code)
├── Optional: references/ (knowledge base documents)
└── Optional: assets/ (templates and resources)
总结:这套设计为什么出色?
- 能力与模型解耦:专业知识不再依赖模型训练,可以随时通过 Markdown 文件更新
- 极致的 Token 效率:三层加载机制保证只加载必要内容
- 善用 LLM 自身优势:路由与匹配完全依赖 Claude 的语言理解,无需额外算法
- 开发者友好:创建 Skill 只需写 Markdown,无需编程
- 可组合:Skills 可以互相引用、组合,形成复杂工作流
- 用后即焚:完成后自动清理,保持上下文新鲜
结语
Skills 是让 Claude Code 从"通用助手"进化为"团队专家"的关键。借助 Skills,你可以:标准化工作流程、复用团队知识、提升协作效率、减少重复解释。
最后记住一个判断准则:如果你发现自己把同一条指令重复说了两次,就该考虑创建一个 Skill 了。现在就去创建你的第一个 Skill 吧——无论是参考 easy-vibe 核心技能章节中给出的四个实例模板,还是直接在对话中让 Claude 帮你生成,都是从"会使用"迈向"会创作"的第一步。