本文基于《Claude Code Skills 完全指南》课程资料整理，深入解析 Skills 的核心机制、工程实现与最佳实践。
一、为什么需要 Skills？
使用 Claude Code 一段时间后，你一定遇到过这样的困境：
- • 每次新建会话，都要重新告诉 AI "我们项目用 TypeScript，测试用 Vitest，提交风格用 Conventional Commits"；
- • 某个复杂的代码审查流程，你用提示词调试了很久，下次开新会话又得从头来；
- • 团队里每个人和 AI 的交互方式不一样，输出质量参差不齐。
这些问题的本质是：AI 没有持久化的"工作方式"。
Claude Code Skills 正是为此而生。它不是一个新模型，也不是一个插件，而是一套将领域知识、工作流程、行为规范打包成可复用单元的机制。一旦安装，AI 就能像有经验的同事一样，在特定场景下自动应用正确的做法。
二、Skills 核心概念
2.1 什么是 Skill？
Skill 是一个可复用的技能包（Reusable Capability Package），本质上是一个结构化的 Markdown 文件（SKILL.md），包含：
- • 元数据：技能的名称、描述、触发条件、允许使用的工具
- • 指令内容：具体的行为规范、工作流步骤、代码模板
- • 辅助资源：scripts、templates、references 等
my-skill/├── SKILL.md # 核心文件：元数据 + 指令├── scripts/ # 可执行脚本├── templates/ # 代码/文档模板└── references/ # 参考文档、示例
2.2 Skills 的三大价值
| 价值 | 说明 |
|---|---|
| 沉淀知识 | 把团队积累的最佳实践固化下来，不随人员流动而流失 |
| 统一标准 | 所有人使用同一套 Skill，AI 输出质量一致 |
| 提升效率 | 复杂工作流一次定义，反复调用，无需重复描述 |
三、SKILL.md 文件结构详解
一个完整的 SKILL.md 由两部分组成：YAML 前置元数据 和 Markdown 指令正文。
3.1 YAML 元数据
---name: code-reviewdescription: 对 PR 进行全面的代码审查，检查安全性、性能和代码质量tags: [review, quality, security]metadata: filePattern: "**/*.{ts,tsx,js,jsx,py}" # 触发文件匹配模式（glob） bashPattern: "git (diff|log|show)" # 触发命令匹配模式（regex） priority: 80 # 优先级（数值越大越优先注入）allowed-tools: - Read - Grep - Bash---
关键字段说明：
- •
filePattern：当用户的Read / Edit / Write工具操作匹配该 glob 模式的文件时，自动注入此 Skill 的上下文。 - •
bashPattern：当Bash工具执行的命令匹配该正则时，自动注入。 - •
priority：数值越高，在多 Skill 竞争时越优先被选中（系统默认最多同时注入 3 个 Skill，并有 18KB 字节上限）。 - •
allowed-tools：该 Skill 允许 AI 使用的工具白名单，控制权限边界。
3.2 Markdown 指令正文
正文是给 AI 的"操作手册"，可以包含：
## 代码审查流程**执行步骤：**1. 先用 `Grep` 搜索所有 TODO / FIXME / HACK 注释2. 检查是否有硬编码的密钥或敏感信息3. 验证所有公开 API 端点的输入校验4. 检查异步函数的错误处理是否完整5. 生成结构化的审查报告**输出格式：**| 等级 | 标记 | 含义 ||------|------|------|| Critical | 🔴 | 必须修复，阻塞合并 || Warning | 🟡 | 建议修复 || Info | 🔵 | 可选优化 |
四、内部机制：第一性原理
理解 Skills 的工作方式，需要从底层机制入手。
4.1 动态上下文注入（Context Injection）
Skills 不是在你调用时才生效的命令，而是通过 Hook 系统在 AI 操作文件或执行命令时自动注入上下文。
整个流程如下：
用户操作 → 触发 PreToolUse Hook → 模式匹配 ↓匹配成功 → 将对应 SKILL.md 内容注入为 additionalContext ↓AI 收到上下文 → 按 Skill 指令执行 → 输出符合规范的结果
以 Vercel 插件为例，其 pretooluse-skill-inject.mjs Hook 的匹配逻辑：
- • 文件工具（Read/Edit/Write）：将
file_path与每个 Skill 的pathPatterns做 glob 匹配，依次尝试完整路径 → basename → 后缀渐进匹配。 - • Bash 工具：将
command字符串与每个 Skill 的bashPatterns做正则匹配。
4.2 三层渐进式加载（Token 优化）
为了避免把所有 Skill 内容都塞进上下文（Token 爆炸），系统采用三层策略：
第一层：MEMORY.md 索引（每次会话载入，极小） ↓第二层：Skill 元数据摘要（PreToolUse 时按需加载） ↓第三层：完整 SKILL.md 内容（命中匹配时才注入）
同时有两个关键限制：
- • MAX_SKILLS = 3：每次 Hook 触发最多注入 3 个 Skill
- • 18KB 字节预算：超出预算的低优先级 Skill 被丢弃
- • Session 去重：同一个 Skill 在一次会话中只注入一次，避免重复消耗 Token
4.3 纯 LLM 推理路由
Skills 没有复杂的规则引擎，路由逻辑本质上依赖 LLM 的推理能力。AI 读到 Skill 的 description 和 name，结合当前任务的上下文，自主判断是否调用对应技能。这意味着：
- • description 写得越精准，触发越准确
- • 模糊的描述会导致 AI 在不该调用时调用，或该调用时忽略
- • 遵循 Agent Skills 开放标准[1]，与其他 AI 工具生态兼容
五、Skills vs 其他方案的本质区别
5.1 Skills vs 提示词（Prompts）
| 维度 | 提示词 | Skills |
|---|---|---|
| 持久化 | ❌ 会话结束即消失 | ✅ 文件化，永久保存 |
| Token 消耗 | 每次都要重新输入 | 按需注入，节省 Token |
| 团队协作 | ❌ 个人私有，难以共享 | ✅ 版本控制，团队共用 |
| 维护成本 | 高（散落在各处） | 低（集中管理） |
5.2 Skills vs MCP（Model Context Protocol）
Skills 是操作手册，MCP 是工具接口
MCP 解决的是"AI 能调用哪些外部能力"的问题（工具扩展），而 Skills 解决的是"AI 在特定场景下应该怎么工作"的问题（行为规范）。两者互补，不互斥：
MCP 工具（Supabase、Figma、GitHub...） +Skills（如何使用这些工具的最佳实践） =高质量、可预期的 AI 工作输出
5.3 Skills vs Commands（斜杠命令）
| 维度 | Commands（/review） | Skills |
|---|---|---|
| 触发方式 | 手动调用 | 自动感知场景 |
| 适用场景 | 简单、单步操作 | 复杂工作流 |
| 上下文感知 | 弱 | 强（基于文件/命令模式匹配） |
实践建议：简单操作用 Commands，复杂流程用 Skills，两者可以配合使用——Command 触发 Skill 的执行入口。
六、快速上手
6.1 安装 find-skills 工具
find-skills 是官方提供的 Skill 发现工具，帮助你搜索和安装社区 Skill：
# 搜索可用的 Skillbun x find-skills search "code review"# 安装到全局bun x find-skills install code-review --global# 安装到项目bun x find-skills install code-review
注意：根据项目规范，始终用
bun替代npx执行脚本。
6.2 三个值得立即尝试的热门 Skill
1. Frontend Design Skill 自动为前端组件应用 shadcn/ui + Tailwind CSS 设计规范，告别风格混乱的界面输出。
# 触发条件：编辑 .tsx/.jsx 文件时自动激活filePattern: "**/*.{tsx,jsx}"
2. Remotion Skill 将代码逻辑可视化为视频动画，适合技术演示和教学内容创作。
3. Frontend Slides Skill 根据内容自动生成 Slidev 格式的演示文稿，快速制作技术分享 PPT。
七、创建你的第一个 Skill
方法一：自然语言对话创建
直接告诉 Claude Code 你想要什么：
我需要一个 Git 自动提交的 Skill：- 自动分析 staged changes- 生成符合 Conventional Commits 规范的提交信息- 在提交前运行测试，失败则中止- 支持中英文混合的提交说明
Claude 会自动生成 SKILL.md 文件结构。
方法二：使用 skill-creator 工具
# 交互式创建向导bun x skill-creator create# 或指定模板bun x skill-creator create --template git-workflow
7.1 选择存储位置
| 类型 | 路径 | 适用场景 |
|---|---|---|
| 全局 Skill | ~/.claude/skills/ | 适用于所有项目的个人习惯 |
| 项目 Skill | ./.claude/skills/ | 特定项目的团队规范，纳入版本控制 |
项目级 Skill 建议加入 Git 仓库，让整个团队共享相同的 AI 工作标准：
project/├── .claude/│ └── skills/│ ├── code-review.md # 代码审查规范│ ├── git-commit.md # 提交信息规范│ └── test-gen.md # 测试生成规范└── src/
八、进阶应用场景
8.1 代码审查 Skill
---name: code-reviewdescription: 执行全面代码审查，包括安全性、性能、可维护性检查metadata: filePattern: "**/*.{ts,tsx,py,go,java}" priority: 90---## 审查维度1. **安全性**：SQL注入、XSS、硬编码密钥、不安全的依赖2. **性能**：N+1查询、内存泄漏、不必要的重渲染3. **代码质量**：圈复杂度、重复代码、命名规范4. **测试覆盖**：边界条件、错误路径、核心逻辑每个问题按 Critical / Warning / Info 分级输出。
8.2 Git 自动提交 Skill
---name: git-commitdescription: 分析 staged changes 并生成 Conventional Commits 格式的提交信息metadata: bashPattern: "git (add|stage|commit)" priority: 85---## 提交信息规范格式：`(): `type 选项：feat / fix / docs / style / refactor / test / chore- 中文 subject 优先，保持简洁（不超过 50 字）- 有 Breaking Change 时添加 `!` 并在 body 说明- 提交前自动运行 `bun test`，失败则提示用户确认
8.3 与 Hooks + Commands 组合使用
Skills 在 Hook 系统中发挥最大威力，可以构建全自动化的工作流：
PreToolUse Hook（文件匹配） ↓ 注入 code-review Skill用户: /review ↓ 触发 CommandAI 自动执行审查流程 ↓PostToolUse Hook ↓ 生成审查报告 + 通知 Slack
九、Skill 编写的五条黄金法则
-
- description 精准化：
description是路由的核心依据，要清晰描述"在什么情况下用这个技能"，而不只是"这个技能是什么"。
- description 精准化：
-
- 单一职责：一个 Skill 只做一件事。代码审查和自动提交应该是两个独立的 Skill，不要混在一起。
-
- 控制大小：Skill 内容越大，注入后消耗的 Token 越多。保持 Skill 简洁，把大型参考文档放在
references/目录，按需引用。
- 控制大小：Skill 内容越大，注入后消耗的 Token 越多。保持 Skill 简洁，把大型参考文档放在
-
- 版本控制：项目级 Skill 必须纳入 Git 管理，像对待代码一样对待它——code review、changelog、迭代记录一样不少。
-
- 测试验证：创建新 Skill 后，用
VERCEL_PLUGIN_DEBUG=1等调试模式验证触发逻辑是否正确，检查匹配模式是否按预期工作。
- 测试验证：创建新 Skill 后，用
十、总结
Claude Code Skills 的本质，是把隐性知识显性化、把一次性操作流程化、把个人经验团队化。
它不是 AI 能力的升级，而是人与 AI 协作方式的升级。当你把项目的代码规范、审查流程、部署流程都固化为 Skill，你的 AI 助手就真正成了一个了解你团队上下文的"资深同事"，而不是每次都从零开始的临时工。
从一个简单的 Git Commit Skill 开始，你会发现，这是提升 AI 编程效能投入产出比最高的一件事。
参考资料
- • Easy-Vibe：Claude Code Skills 完全指南[2]
- • Agent Skills 开放标准[1]
- • Claude Code 官方文档[3]
2026.03.25 13:39 沪 · 赵巷
📌 声明：本文由 AI 辅助完成
引用链接
[1] Agent Skills 开放标准: agentskills.dev*
[2] Easy-Vibe：Claude Code Skills 完全指南: datawhalechina.github.io/easy-vibe/z…
[3] Claude Code 官方文档: docs.anthropic.com/claude-code
