Claude Code Skills 完全指南
Skills 并不是需要编译的复杂插件或二进制软件。它本质上就是一个存放于特定目录下的 Markdown 文件（
SKILL.md）。通过本文，你将学会如何为 Claude Code 编写专属的“专家思维模型”，让 AI 在特定任务上稳定输出高质量结果。
一、Claude Code 四大扩展机制概览
在深入 Skills 之前，先理解它与其他三种机制的分工：
CLAUDE.md
↓
告诉Claude应该知道什么
Skills
↓
告诉Claude应该怎么做
Hooks
↓
控制Claude什么时候做
MCP
↓
给Claude新的能力
| 机制 | 核心职责 | 触发方式 | 是否强制 |
|---|---|---|---|
CLAUDE.md |
项目级背景、编码规范、架构说明 | 会话启动时自动加载 | 是 |
| Skills | 特定领域的“专家操作手册” | 按需加载（语义匹配或显式调用） | 否 |
| Hooks | 在工具执行前后强制运行自定义脚本 | 固定生命周期事件 | 是（百分百触发） |
| MCP | 连接外部服务器，扩展工具能力 | 手动调用或自动注册 | 否 |
Skill 到底是什么？
把 Skill 理解为给 AI 雇员准备的 “岗位标准操作说明书（SOP）” 或 “专家思维模型”。
- 你可以把资深前端架构师对组件设计的严苛规范写进 Skill，Claude 就能在生成 Vue 组件时自动遵循这些约束。
- 你可以把 Web3 安全审计专家的检查清单写进 Skill，Claude 就会按清单逐条审查智能合约。 关键点：Skill 不包含任何可执行代码（它本身只是一个 Markdown 文件），但可以引用外部的脚本、模板或参考文档。
三、Skill 的触发机制（它是怎么被加载的？）
Skill 有三种触发方式，按优先级从低到高排列：
1. 自动语义匹配（默认）
Claude Code 会分析用户当前的提问，并与每个 Skill 的 description 字段进行语义相似度计算。当匹配度超过阈值时，自动加载该 Skill 的内容到上下文。
💡 这就是为什么
description字段极其重要——它是 Skill 被“唤醒”的唯一线索。建议在描述中包含关键词、适用场景和典型任务。 示例：
用户提问：“帮我写一个符合公司规范的 Vue 3 登录组件”
如果某个 Skill 的 description 包含 “Vue 3”、“组件规范”、“Tailwind CSS”，它极有可能被自动激活。
2. 路径匹配（可选）
部分 Claude Code 实现（如 VS Code 插件）支持通过 paths 字段限制 Skill 仅在特定目录下生效。
---
name: API 设计规范
description: 用于设计和审查 RESTful API。
paths: "src/api/**"
---
同claude.md文件一样，skill可以安装在全局目录，也可以安装在项目文件里。结构如下：
当用户操作的文件路径匹配 src/api/** 时，该 Skill 会自动加载。
3. 显式调用（用户强制）
用户可以在对话中使用 @技能名 来强制加载某个 Skill，无论当前语义匹配是否触发。
text
@TailWind Component Standard 请帮我审查这个按钮组件的样式
显式调用优先级最高，适合在自动匹配失败或需要临时覆盖时使用。
四、Skill 的文件组织结构
与 CLAUDE.md 类似，Skill 可以安装在全局目录（跨项目通用）或项目目录（团队共享，纳入 Git）。
# 项目级 Skill（推荐）
你的项目/
└── .claude/
└── skills/
└── vue3-tailwind-spec/ # 技能文件夹（小写 + 短横线）
├── SKILL.md # 核心说明书（必需）
├── scripts/ # 可选：配套自动化脚本
│ ├── validate.sh
│ └── generate.py
├── templates/ # 可选：代码脚手架模板
│ └── Component.vue.tpl
└── references/ # 可选：附加参考文档
└── color-palette.md
全局 Skill 放在 ~/.claude/skills/ 下，结构相同。
命名规范：Skill 文件夹名使用小写字母和短横线，例如
vue3-tailwind-spec，不要使用空格或下划线。
五、如何编写一个合格的 Skill？
核心特质
一个优秀的 Skill 应该具备：
极高专注度：一个 Skill 只解决一个具体的、可重复的任务。切忌包罗万象。
精准的唤醒描述：
description字段控制在 200 字以内，但必须覆盖关键词和适用场景。明确的规则与红线：既要写“应该怎么做”，也要写“绝对不能做”（Anti‑patterns）。
优秀的示例示范：提供 1‑2 组输入/输出范例，AI 的输出稳定性会大幅提升。
配套的外部武器：引用脚本、模板或参考文档，让 Skill 具备真正的“落地能力”。
5.2 编写 SKILL.md 文件
文件顶部必须包含由 --- 包裹的 YAML Frontmatter，至少包含 name 和 description。
---
name: TailWind Component Standard
description: 专用于审查或生成符合 Tailwind CSS 规范的前端 Vue/React 组件。当用户需要优化、重构或编写 UI 样式时自动启用。
paths: "src/components/**" # 可选，限制生效目录
dependencies: node>=18.0.0 # 可选，声明依赖
---
正文使用 Markdown 书写，建议包含以下章节：
核心概述：一句话说明本 Skill 的目标。
适用场景：列出典型的使用时机。
核心规范：分条列出必须遵守的规则。
反面教材：给出错误的代码示例，明确“禁止怎么写”。
正确示例：给出符合规范的代码片段。
配套工具：说明如何运行附带脚本或使用模板。
六、完整示例：Tailwind 组件规范 Skill
目录结构
.claude/skills/tailwind-component-standard/
├── SKILL.md
├── scripts/
│ └── validate-tailwind.sh
└── references/
└── color-tokens.md
SKILL.md 完整内容
---
name: TailWind Component Standard
description: 专用于审查或生成符合 Tailwind CSS 规范的前端 Vue/React 组件。当用户需要优化、重构或编写 UI 样式时自动启用。
---
# Tailwind 组件规范技能
## 核心概述
确保项目中的所有 UI 组件严格遵循 Tailwind 原子化 CSS 的最佳实践，保持视觉风格统一。
## 适用场景
- 编写新的 Vue/React UI 组件
- 重构现有组件的样式
- 代码审查中检查样式是否符合规范
## 核心规范
1. **移动端优先**：编写响应式类名时，必须先写基础样式，再通过 `md:`、`lg:` 等断点覆盖。
2. **禁止内联样式**：严禁出现 `style="color: #fff"` 等硬编码，一律使用 Tailwind 工具类。
3. **颜色约束**：只能使用主题色板中的 token（如 `text-primary`、`bg-secondary`）。具体色值参考 @references/color-tokens.md。
## 反面教材 (Anti-patterns)
<!-- 错误：内联样式 + 非原子化类名 -->
<div class="box" style="margin-top: 10px;">
<p class="text-gray-500 font-bold">标题</p>
</div>
## 正确示例
<!-- 正确：纯 Tailwind 原子类 -->
<div class="mt-2.5 p-4 bg-surface md:mt-4">
<p class="text-base text-main font-bold">标题</p>
</div>
七、如何确认 Skill 是否被加载
确认一个 Skill 是否生效，可以尝试以下几种方法，建议从第一种开始：
1. 对话测试
最直接的方法就是用对话本身来验证。你可以直接向 Claude 提问，例如“列出当前可用的 Skills”。另一个方法是，在对话中输入/，查看下拉菜单中是否自动列出了你的 Skill 名称，这是它已被系统识别的直接信号。2. 文件与项目检查
如果对话中没出现，就需要快速检查一下项目文件结构：确认位置正确：检查你的
SKILL.md文件是否存放在正确的文件夹中。项目级技能应位于{项目根目录}/.claude/skills/你的技能名/SKILL.md。检查 YAML 元数据：使用文本编辑器打开
SKILL.md，确保文件顶部的name和description字段格式正确（以---包裹，使用正确的 YAML 语法），并且description足够清晰。