Easy-Vibe 实战:Claude Code Skills 完整指南——从技能安装、手写 SKILL.md 到内部机制剖析
Easy-Vibe 实战:Claude Code Skills 完整指南——从技能安装、手写 SKILL.md 到内部机制剖析
本文是 Easy-Vibe 项目(datawhalechina/easy-vibe)Stage-3「核心技能」模块的技术指南,对应仓库文档 docs/en/stage-3/core-skills/skills/index.md。Skills 是 Claude Code 中把专业知识、工作流与最佳实践封装成可复用「技能包」的机制。读完本文,你将能够:通过
find-skills一站式搜索安装社区技能、用三个实战 Skill(视频生成、前端美化、PPT 制作)快速上手、亲手编写规范的SKILL.md文件、并理解其「提示词动态注入 + 元工具架构」的内部原理。
一、Skills 是什么?为什么需要它?
Claude Code Skills 是 Claude Code 的一项特性,它将专业知识、工作流程和最佳实践封装为可复用的「技能包(skill packs)」。你可以把 Skills 想象成给 Claude 配备的「技能书」:当需要它完成某个特定任务时,你不再需要反复解释需求,它可以直接按照 Skill 预先定义的标准去执行工作。
在 Skills 出现之前,使用 Claude Code 存在几个突出问题:
- 指令重复:每次都要重新解释「遵循什么代码风格」「commit message 怎么写」;
- 知识无法沉淀:团队成员个人使用 Claude 的经验无法共享;
- 标准不统一:不同人使用 Claude 得到的结果可能完全不同;
- 效率低下:常见任务每次都要从头解释。
Skills 解决了这些问题,让 Claude 变成一位「经验丰富的团队成员」——它了解你的项目约定、工作流和最佳实践。
为什么现在要学 Skills?
从项目课程的设计看(见 docs/en/stage-3/index.md,其中将 Skills 定位为「把专业知识、工作流和最佳实践封装为可复用技能包」的核心能力),Skills 已成为 AI 工程师的必备能力:
- 社区关注度高:据原文档记载,相关 GitHub 仓库星标增长迅速,例如 OpenSkills 项目已达 7.2k stars,Obsidian Skills 在 9 天内获得 6.6k stars;
- 官方支持:Anthropic 维护着官方 Skills 仓库,Vercel 推出了 Agent Skills 与 find-skills 工具;
- 实用性强:从代码审查、Git 操作到视频创作、PPT 生成,Skills 覆盖大量场景,skills.sh 平台上已有订阅量 60K+ 的热门技能;
- 效率提升:配置一次、反复复用,让 Claude 真正成为你的「数字员工」;
- 开发者认可:被多个技术社区推荐,被广泛认为是提升 AI 编程效率的关键工具。
二、快速上手:从安装 find-skills 到三个实战 Skill
Step 1:安装 find-skills(强烈推荐)
在开始使用 Skills 之前,强烈建议先安装 find-skills。它是 AI Agent 世界里的「终极技能搜索工具」,订阅量已超过 60K。
find-skills 之于 AI Agent,就像「应用商店搜索引擎」:当你需要完成某任务但没有合适的本地 Skill 时,它会自动搜索并推荐最合适的技能。
安装命令:
npx skills add vercel-labs/skills@find-skills -g -y
安装完成后,你可以直接告诉 Claude 你的需求,它会自动使用 find-skills 搜索相关技能。例如:
I need to optimize the performance of a React component. Help me find what skills I can use.
Claude 会通过 find-skills 搜索,然后告诉你找到了哪些相关技能,供你选择安装。
为什么先装 find-skills?
| 安装 find-skills 之前 | 安装 find-skills 之后 |
|---|---|
| 手动在 GitHub 搜索相关 skills | 用一句话描述需求 |
| 逐个复制、安装、配置 | AI 自动搜索最佳匹配技能 |
| 反复调试适配 | 一键安装、立即可用 |
Windows 用户注意:官方版本对 Windows 支持有限,社区制作了兼容 Windows 的版本,支持 CMD 和 PowerShell,并增加了中文搜索。安装步骤:
- 下载 Windows 版本的
SKILL.md(社区仓库 customize-skills); - 替换
C:/Users/your-username/.agents/skills/find-skills中的文件; - 重启 Claude Code 即可生效。
实战 Skill 一:用 Remotion 制作视频
安装 find-skills 后,先用它搜索并安装第一个有趣的 Skill:Remotion 视频创作工具。
Step 1:在 Claude Code 中搜索:
Help me find skills related to Remotion. I want to make videos.
Step 2:安装:
npx skills add remotion-dev/skills -g
Step 3:用自然语言让 Claude 帮你写视频代码(Remotion 是用 React 代码制作视频的框架)。
任务 1——制作一个炫酷的动画文字视频:
Use Remotion to make a video:
- 1920x1080, 5 seconds
- A line of text "Hello World" flies in from the left
- With rotation and scaling effects at the same time
- The background is a gradient
任务 2——制作数据可视化视频:
Make a 10-second video showing data growth:
- Start with a bar chart
- The bars grow one by one with animation
- Numbers count upward
- At the end, show large text saying "300% growth"
任务 3——制作多场景产品演示视频:
Make a product demo video with three scenes:
Scene 1: Logo fades in, 2 seconds
Scene 2: Product features appear one by one, 3 seconds
Scene 3: CTA button pops up, 2 seconds
Use smooth transitions between each scene
运行代码:Claude 生成的是一套完整的 Remotion 项目,你可以:
- 创建新项目:
npx create-video my-video - 把 Claude 生成的代码复制进去
- 预览:
npm start - 渲染视频:
npm run build
实战 Skill 二:用 frontend-design 解决「前端又丑又卡」
Step 1:用自然语言描述你的高层需求:
My website looks outdated and loads slowly. Help me find what skills I can use.
Step 2:Claude 会通过 find-skills 检索 skills.sh 数据库并推荐相关技能。对于「更好看 + 不卡顿」这类需求,它会推荐 anthropics/skills/frontend-design(官方技能)。
这个 Skill 专门解决 AI 生成界面「千篇一律、模板感重」的问题,帮助 Claude 设计:
- 独特视觉风格,避免千篇一律的「AI 模板脸」;
- 专业的配色方案与排版;
- 流畅的动画效果;
- 生产级代码质量,代码干净、性能自然更好。
Step 3:安装并使用:
npx skills add anthropics/skills/frontend-design -g
可完成的任务示例:
Help me redesign this page. I want it to look very professional and not like it was generated by AI.
This UI is too ugly. Rewrite it in a more modern design style.
Make a dark-theme dashboard with a strong tech feel.
Claude 会遵循该 Skill 的约定,帮你确定独特视觉方向(极简、复古未来、粗野主义等)、精心挑选颜色字体、规划合理的间距布局、加入平滑的交互动画。
实战 Skill 三:用 frontend-slides 快速制作精美 PPT
frontend-slides 是一个让你用自然语言就能创建漂亮 HTML 演示文稿的 Skill——即使完全不懂 CSS 或 JavaScript 也能用。它的核心理念是「展示,而非描述(show, don't tell)」:如果你无法清晰描述想要的风格,它会先生成 3 个视觉预览供你挑选,而不是逼你描述「蓝色背景、大字号」这类抽象需求。
安装方式一:手动安装
# 创建技能目录
mkdir -p ~/.claude/skills/frontend-slides
# 下载文件(或从 GitHub 复制)
# 1. 访问 frontend-slides 仓库
# 2. 下载 SKILL.md 和 STYLE_PRESETS.md
# 3. 放入 ~/.claude/skills/frontend-slides/
安装方式二:通过 find-skills
Help me find a skill for making PPT presentations
使用场景一:从零创建演示文稿
/frontend-slides
I want to create a fundraising pitch deck for an AI startup project, around 10 slides
Claude 会引导你:1) 填写每页幻灯片的标题、要点、图片等内容;2) 描述你想要的观感(惊艳、专业、温暖等);3) 从 3 个视觉风格预览中挑选;4) 创建完整 HTML 演示文稿;5) 在浏览器中打开预览。
使用场景二:转换 PowerPoint 文件
/frontend-slides
Convert my presentation.pptx into a web presentation
Claude 会:1) 从 PPT 中提取全部文字、图片和备注;2) 展示提取内容供你确认;3) 让你选择视觉风格;4) 生成保留全部原始内容的 HTML 演示文稿。
使用场景三:快速生成风格预览
/frontend-slides
I want to make a PPT for a technical talk. Show me the available visual styles first.
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>
<!-- All styles are inlined, zero dependencies -->
</head>
<body>
<section class="slide title-slide">
<h1 class="reveal">Your Title</h1>
</section>
<!-- More slides... -->
</body>
</html>
为什么推荐它? 1) 零依赖:单 HTML 文件,十年后依然能打开;2) 视觉发现式:无需描述设计,直接挑选喜欢的效果;3) PPT 转换:保留现有内容、换上新视觉外衣;4) 生产级代码:可访问、注释清晰、易于定制。
三个实战 Skill 对比
| 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. Prompts
你可能会问:Skills 和直接给 Claude 发提示词有什么区别?
| Prompts | Skills |
|---|---|
| 临时性,每次都要重复 | 持久性,写一次多次复用 |
| 存在于对话历史中,消耗 token | 按需加载,节省 token |
| 无法跨会话共享 | 可以在团队内共享 |
| 难以版本管理 | 可以用 Git 管理 |
两种类型的 Skills
全局 Skills(个人级):
- 存储位置:
~/.claude/skills/ - 作用范围:所有项目
- 适用场景:通用型个人技能
项目 Skills(团队级):
- 存储位置:
project-directory/.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: short description # 用于 Claude 的自动触发匹配
category: development # 分类
tags: # 标签
- code
- automation
---
第二部分:Markdown 内容(指令)
# Skill Title
## Use cases
When to use this skill
## Execution steps
1. Step one
2. Step two
## Notes
- Note 1
- Note 2
关键字段说明
| 字段 | 是否必需 | 说明 |
|---|---|---|
name |
是 | 技能名,只允许小写字母、数字和连字符 |
description |
是 | 技能描述,越具体越容易被 Claude 自动匹配 |
category |
否 | 分类标签 |
tags |
否 | 额外的分类标签 |
allowed-tools |
否 | 无需额外授权即可使用的工具 |
命名细节补充:
name字段在解析时会被校验——最大 64 个字符,仅允许小写字母、数字和连字符;description则直接服务于 LLM 的自动匹配(详见下文「文件解析机制」)。
五、Skills vs. MCP:到底有什么区别?
很多初学者会把 Skills 和 MCP 混淆,但它们是两种完全不同的东西。Easy-Vibe 仓库也分别用独立文档讲解二者,MCP 的完整内容见 docs/en/stage-3/core-skills/mcp/index.md。
核心差异
| 维度 | Skills | MCP |
|---|---|---|
| 本质 | 知识与工作流 | 工具与接口 |
| 提供什么 | 告诉 AI「怎么做」 | 给 AI「有什么可用」 |
| 存储位置 | skills/ 目录 |
MCP server |
| 配置格式 | Markdown 文件 | JSON 配置文件 |
| 触发方式 | /skill-name 或自动识别 |
通过配置自动加载 |
一个直观的类比
如果把 Claude 比作「工人」:
- MCP 是发给工人的「工具」,比如扳手、电脑、访问权限;
- Skills 是发给工人的「操作手册」,比如怎么做代码审查、怎么提交代码。
两者的关系
Skills 和 MCP 不是竞争关系,而是互补关系:
User task -> Claude recognizes the requirement
↓
Load relevant Skills (know how to do it)
↓
Call tools through MCP (have tools available)
↓
Complete the task
协同示例:代码审查
- Skills 定义审查步骤、检查清单和输出格式;
- MCP 提供访问 GitHub PR、获取代码 diff 的能力。
二者协作:Skills 告诉 Claude「如何审查」,MCP 给 Claude「访问代码的能力」。
选型建议
| 你的需求 | 推荐方案 |
|---|---|
| 需要定义工作流 | 使用 Skills |
| 需要访问外部数据 | 使用 MCP |
| 两者都需要 | 组合使用 |
六、如何获取更多 Skills
官方资源
- Anthropic 官方 Skills 仓库:官方维护的技能合集;
- Claude Code 官方文档 Skills 章节:官方文档。
GitHub 社区资源
| 仓库 | 描述 |
|---|---|
| claude-code-best-practice | 社区维护合集,覆盖 Skills、Agents、Hooks 等 |
| everything-claude-code | 综合工具包,含预配置 Skills |
| awesome-agent-skills | 精选 Skills 资源清单 |
| claude-skills | 66 个专业技能 + 300+ 参考文档 |
| awesome-claude-skills | 精选开源合集 |
官方 Skill 示例
- skill-creator:用于创建新技能的 Skill;
- mcp-builder:用于构建 MCP server 的 Skill;
- slack-gif-creator:用于创建 Slack GIF 的 Skill。
如何安装社区 Skills
借助 find-skills,你只需告诉 Claude 需求,它会自动搜索并推荐:
Help me find a skill related to React performance optimization
搜索技巧:
- 使用具体关键词:「react testing」优于「testing」;
- 组合「领域 + 动作」:「nextjs deploy」、「typescript lint」;
- 优先选择安装量高的技能,10K+ 通常意味着久经考验;
- 关注 trending 榜单发现新兴技能。
七、如何创建你自己的 Skills
创建 Skills 有两种方式:直接让 Claude 帮你创建,或使用专门的 skill-creator 工具。
方法一:直接让 Claude 创建(最简单)
用自然语言告诉 Claude 你的需求即可。
示例:
Please help me create a skill named "format-code" to automatically format code.
Requirements:
1. Automatically detect the programming language
2. Apply the corresponding formatting rules
3. Return the diff before and after formatting
Claude 会自动:1) 创建目录结构;2) 生成 SKILL.md 文件;3) 填写 YAML frontmatter;4) 编写技能内容。
适用场景:快速创建简单技能、想快速迭代修改。
方法二:使用 skill-creator(标准化流程)
skill-creator 是创建 Skills 的专用工具,会一步步引导你完成。
安装:
npx skills add anthropics/skills@skill-creator -g
或安装整个官方技能仓库:
npx skills add anthropics/skills -g
使用:
/skill-creator
然后依次填写:技能名称、功能描述、使用场景、执行步骤。
skill-creator 会:1) 引导你明确技能目的;2) 生成 SKILL.md 草稿;3) 创建测试用例;4) 运行评估并优化。
适用场景:创建复杂技能、需要更规范的创建流程、希望测试验证技能。
两种方式对比
| 方法一:直接创建 | 方法二:skill-creator |
|---|---|
| 快速简单 | 引导式步骤 |
| 适合简单技能 | 适合复杂技能 |
| 对话中直接完成 | 标准化流程 |
| 灵活修改 | 包含测试与验证 |
小技巧:如何写出好的需求描述
一份好的需求描述:
Create a "git-commit" skill that automatically commits code.
Execution steps:
1. Check which files were modified
2. Generate a commit message that follows Conventional Commits
3. Run git commit
4. Ask whether to push
Notes:
- Check for sensitive information before committing
- Do not commit directories like dist/ or node_modules/
一份差的需求描述:
Help me write a skill for committing code
太模糊了,Claude 不知道具体要做什么。顺带一提,Easy-Vibe 仓库自身的协作规范 AGENTS.md 就明确要求 commit 遵循 Conventional Commits 风格(如 feat: ...、fix: ...、docs: ...),并提醒不要在 PR 中混入无关改动——这正是把「团队约定」沉淀为 Skill 的最佳实践场景。
八、四个可直接复制的 Skill 完整示例
示例 1:代码审查 Skill(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
Please review the PR for the current branch
示例 2:Git 自动提交 Skill(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
示例 3:测试生成 Skill(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
Generate unit tests for src/utils.ts
示例 4:文档生成 Skill(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
Generate a README document for the current project
九、进阶技巧:Skills 的协同与团队落地
与 Hooks 结合:事件驱动的自动化
Hooks 可以在特定事件上自动执行动作,与 Skills 结合能实现更强大的自动化。例如「保存后自动格式化代码」:
// .claude/hooks.json
{
"hooks": {
"PostToolUse": [{
"matcher": {
"tool_name": "Edit"
},
"hook": {
"type": "command",
"command": "/format-code" // 调用 format-code skill
}
}]
}
}
与 Commands 结合
Commands 是简单的快捷命令,Skills 是复杂工作流,二者可以配合使用(区别详见后文 FAQ Q3)。
团队协作
共享项目 Skills:
- 将 Skills 放在
.claude/skills/下; - 提交到 Git;
- 团队成员 clone 项目后即可使用。
版本控制:
- Skills 可以像代码一样进行版本管理;
- 每次 commit 都可以记录 Skills 的变更;
- 可以回滚到旧版本。
十、常见问题(FAQ)
Q1:为什么 Skill 没有被触发?
可能原因:
- YAML frontmatter 格式错误;
- description 不够具体;
- 没有重启 Claude Code。
解决办法:
- 检查 YAML 格式是否正确;
- 改进 description,写入具体使用场景;
- 重启 Claude Code。
Q2:如何写出准确的 description?
一个好的 description 包含:
- 技能的具体功能;
- 使用场景,如「当用户提到……时」;
- 触发关键词。
坏例子:
description: Review code
好例子:
description: Review Pull Request code. Trigger when the user mentions PR, review, or code review.
Q3:Skills 和 Commands 有什么区别?
| Commands | Skills |
|---|---|
| 简单的快捷命令 | 完整的工作流 |
单个 .md 文件 |
目录结构(SKILL.md + 可选文件) |
| 手动触发 | 可自动触发 |
| 适合简单操作 | 适合复杂流程 |
Q4:如何调试一个 Skill?
- 使用
/skills检查技能是否被识别; - 直接输入技能名手动触发;
- 检查
SKILL.md内容是否正确; - 查看 Claude Code 日志。
十一、深入原理:Claude Skills 的内部机制
掌握了「怎么用」,接下来深入理解「为什么这样设计」。
第一性原理:基于提示词的动态上下文注入
首先理解一个关键事实:Skills 不是可执行代码。
Skills 本质上是高级指令(即提示词),在需要时被「注入」到 Claude 的上下文中。这种设计被称为「基于提示词的动态上下文注入与元工具架构(Prompt-based Dynamic Context Injection & Meta-Tool Architecture)」。
┌─────────────┐ ┌─────────────┐ ┌──────────────┐
│ User Request│ ───> │ LLM Matches │ ───> │ Trigger Skill│
└─────────────┘ │Description │ └──────────────┘
└─────────────┘ │
▼
┌──────────────┐
│ Inject Full │
│ Instructions │
└──────────────┘
│
▼
┌──────────────┐
│ Execute Task │
└──────────────┘
三层渐进式加载架构(token 优化)
为了在技能数量很多时仍不消耗过多 token,Claude 采用了一套巧妙的三层加载机制:
| 层级 | 内容 | 何时加载 | token 成本 |
|---|---|---|---|
| 第一层:元数据 | YAML frontmatter(name + description) |
Claude 启动时 | 每个技能约 30–50 tokens |
| 第二层:指令 | 完整的 SKILL.md 内容 |
技能被触发时 | 约 5,000 tokens |
| 第三层:资源 | 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 实际收到的内容(隐藏的元消息)
{
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 |
|---|---|
| ❌ 嵌入向量匹配 | ✅ 纯 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,不加载完整正文) │
└─────────────────────────────────────────────────────────────┘
完整执行流程示例
User: "Help me analyze this PDF file"
═══════════════════════════════════════════════════════════════
Step 1: LLM 决策
────────────────
Claude 在 Skill 列表中找到 "pdf" 技能的描述:
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. 生成隐藏元消息:完整 SKILL.md 内容
4. 修改会话权限:allowed-tools = ["Bash(pdftotext:*)"]
═══════════════════════════════════════════════════════════════
Step 3: LLM 执行
────────────────
现在 Claude 的上下文包含:
- 原始用户请求
- PDF 专家工作流指令
- pdftotext 工具的访问权限
Claude 执行:
1. 使用 pdftotext 提取 PDF 文本
2. 分析内容结构
3. 生成摘要报告
4. 向用户呈现结果
═══════════════════════════════════════════════════════════════
Step 4: 用完即弃
────────────────
任务完成后,完整 Skill 内容从上下文中移除
(只保留对话历史,不保留完整 Skill 指令)
核心设计创新
| 创新点 | 传统方案 | Skills 方案 | 优势 |
|---|---|---|---|
| 能力来源 | 固定在模型权重中 | 动态加载的提示词 | 可扩展、可更新 |
| Token 效率 | 所有能力常驻内存 | 按需加载 | 节省 80%+ tokens |
| 知识管理 | 散落在对话历史中 | 模块化文件系统 | 可版本控制、可共享 |
| 生命周期 | 持续占用空间 | 用完即弃 | 上下文更干净 |
学术基础
Claude Skills 的设计借鉴了以下研究成果:
| 研究领域 | 代表性工作 | 在本设计中的应用 |
|---|---|---|
| 强化学习 | Voyager (2023) | 技能库的积累思想 |
| 认知架构 | ACT-R、Soar | 程序性记忆与陈述性记忆的分离 |
| 分层策略 | Options Framework | 三层渐进式加载 |
核心思维转变:
传统方式:AI 需要记住一切
↓
Skills:AI 知道去哪里找专业知识
↓
结果:更像人类专家的思维模式
与 Agent Skills 标准的关系
Claude Skills 遵循 Agent Skills 开放标准,这意味着:
- ✅ 跨平台兼容: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 可以互相引用和组合,形成复杂工作流;
- 用完即弃:完成后自动清理,保持上下文新鲜。
十二、在 Easy-Vibe 课程中的定位
在 Easy-Vibe 项目「高级开发」阶段(docs/en/stage-3/index.md),Skills 是「核心技能」模块下的重要一课,与 Claude Code 快速上手(basics)、MCP 完整指南、长时任务(long-running-tasks)、Agent 团队协作、Superpowers 工程化框架等并列。本指南(docs/en/stage-3/core-skills/skills/index.md)与实践性的 Superpowers 指南(其核心就是一套用于 TDD、系统化调试、头脑风暴的 Skills 集合)相互印证:Superpowers 展示了「触发机制」在真实工程流程中的应用(关键词触发、场景触发、手动调用),而本文则系统讲解了 Skills 的定义、安装与底层机制。MCP 与 Skills 的边界区分可参见 docs/en/stage-3/core-skills/mcp/index.md。
总结
Skills 是把 Claude Code 从「通用助手」变成「团队专家」的关键。通过 Skills,你可以:
- 标准化工作流;
- 复用团队知识;
- 提高协作效率;
- 减少重复解释。
记住这条原则:如果你发现自己在重复同样的指令两次,就应该考虑创建一个 Skill。
现在,去创建你的第一个 Skill 吧。