Easy-Vibe 实战:Claude Code Skills 完整指南——从技能安装、手写 SKILL.md 到内部机制剖析

原创2026-09-23 11:49:572,145 阅读
文章标签:教程Vibe CodingAI 应用

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,并增加了中文搜索。安装步骤:

  1. 下载 Windows 版本的 SKILL.md(社区仓库 customize-skills);
  2. 替换 C:/Users/your-username/.agents/skills/find-skills 中的文件;
  3. 重启 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 项目,你可以:

  1. 创建新项目:npx create-video my-video
  2. 把 Claude 生成的代码复制进去
  3. 预览:npm start
  4. 渲染视频: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 启动时,它会:

  1. 扫描 Skills 目录;
  2. 解析每个 SKILL.md 文件;
  3. 提取 YAML frontmatter 元数据;
  4. 将技能内容加入其「知识库」;
  5. 基于 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:

  1. 将 Skills 放在 .claude/skills/ 下;
  2. 提交到 Git;
  3. 团队成员 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?

  1. 使用 /skills 检查技能是否被识别;
  2. 直接输入技能名手动触发;
  3. 检查 SKILL.md 内容是否正确;
  4. 查看 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)

为什么这套设计很出色?

  1. 将能力与模型解耦:专业知识不再依赖模型训练,可通过 Markdown 文件随时更新;
  2. 极致的 token 效率:三层加载机制确保只加载必要内容;
  3. 发挥 LLM 自身优势:路由和匹配完全依赖 Claude 的语言理解,无需额外算法;
  4. 对开发者友好:创建 Skill 只需写 Markdown,无需编程;
  5. 可组合:Skills 可以互相引用和组合,形成复杂工作流;
  6. 用完即弃:完成后自动清理,保持上下文新鲜。

十二、在 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 吧。

登录后查看全文
easy-vibe