easy-vibe 第三阶段核心技能:Claude Code Skills 技能包完全指南——安装实操、SKILL.md 编写与动态上下文注入机制

原创2026-09-16 11:26:511,986 阅读
文章标签:文档教程Vibe Coding人工智能

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

  1. 获取 Windows 版本的 SKILL.md 文件;
  2. 替换 C:/Users/你的用户名/.agents/skills/find-skills 目录下的文件;
  3. 重启 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 代码。运行方式:

  1. 新建项目:npx create-video my-video
  2. 把 Claude 生成的代码复制进去
  3. 启动预览:npm start
  4. 构建视频: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 启动时会执行一条固定的扫描链路:

  1. 扫描技能目录;
  2. 解析每个 SKILL.md 文件;
  3. 提取 YAML frontmatter 元数据;
  4. 将技能描述加入其"知识库";
  5. 后续根据描述自动匹配触发。

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 团队协作与版本控制

共享项目技能:

  1. 把技能放到项目下的 .claude/skills/ 目录;
  2. 用 Git 提交;
  3. 团队成员克隆项目后即可使用。

版本控制能力:

  • 技能可以像代码一样做版本管理;
  • 每次提交都记录了技能的变更;
  • 可以回滚到旧版本。

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:如何调试技能?

  1. 使用 /skills 检查技能是否被识别;
  2. 直接输入技能名手动触发;
  3. 检查 SKILL.md 内容是否正确;
  4. 查看 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 小结:为什么这个设计优秀

  1. 能力与模型解耦:专业知识不再依赖模型训练,用 Markdown 文件随时更新;
  2. Token 效率极高:三层加载保证只加载必需内容;
  3. 借力 LLM 优势:路由与匹配完全依赖 Claude 的语言理解,无额外算法;
  4. 开发者友好:创建技能只需写 Markdown,不用写代码;
  5. 可组合:技能之间可以相互引用、组合成复杂工作流;
  6. 用完即弃:完成后自动清理,保持上下文清爽。

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)。

登录后查看全文
easy-vibe