Claude Code -8 Skills 实战指南：让 AI 精准执行你的工程规范

Claude Code Skills 实战指南：让 AI 精准执行你的工程规范

前言

在前面的文章里，我们聊了 Claude Code 的目录结构、记忆系统、MCP、子代理。今天这篇聚焦 .claude/skills/ --- 一个经常被忽视但实际价值极高的配置目录。

CLAUDE.md 可以约束 AI 的行为，但它只能声明"不要做什么"。而 Skills 不同，它是一个主动的任务蓝图：把"做什么""怎么做""用什么模板""怎么验证结果"打包成一个可复用单元。

换句话说，CLAUDE.md 是护栏，Skills 是导航仪。

一、基础介绍

什么是 Skill

Skill 是 Claude Code 中的结构化可复用任务包。一个完整的 Skill 包含：

触发条件：什么时候该用这个 Skill
执行流程：按什么步骤完成任务
资源文件：模板、脚本、参考文档
权限控制：允许使用哪些工具
校验规则：怎么判断结果是否符合预期

它不是一个简单的 prompt 模板，而是一个从"识别任务"到"交付结果"的完整工作流定义。

Skill 在配置体系中的位置

先回顾一下 .claude/ 下各配置角色的分工：

配置项	本质	加载方式	典型用途
CLAUDE.md	全局规则	每次对话必加载	项目背景、核心约束
skills/	可复用任务包	按触发条件加载	创建页面、代码审查
commands/	快捷命令	用户主动调用	/dev、/review
agents/	专家角色	被 Skill 调度或用户指定	前端开发专家、安全审计员

Skill 的独特价值在于：它是唯一把"规范 + 模板 + 脚本 + 参考"打包成可复用单元的机制。

CLAUDE.md 只能声明约束，commands 只是快捷入口，agents 定义角色但不自带模板和流程。只有 Skill 把这些都串起来------触发时加载规范，执行时使用模板，完成时校验结果。

Skill 解决的三个痛点

痛点一：重复任务的一致性

团队里每个人创建页面、组件的方式不同，代码风格分裂。Skill 把"怎么创建一个标准页面"固化成模板+流程，谁调用都是同一套标准。

痛点二：上下文精确控制

CLAUDE.md 里塞太多规则，每次对话都要消耗 token，而且 AI 容易在大量规则中"迷失"。Skill 只在需要时加载，不相关的时候零开销。

痛点三：经验沉淀

踩过的坑，写进 Skill 的禁止项和检查清单，AI 就不会再犯。这比口口相传或者写 Wiki 文档有效得多------因为 Wiki 人会忘看，Skill 是 AI 必须遵守的。

二、核心属性

最小配置：两个必需字段

yaml 复制代码

---
name: my-skill
description: "一句话说清这个 skill 做什么、什么时候用"
---

name 和 description 是创建 Skill 的最低门槛。但真实项目中，只靠这两个字段远远不够。

按功能分组理解属性

把属性按功能分组理解，比逐个罗列更有价值：

触发控制：决定 Skill 何时被激活

属性	作用	实战建议
`name`	全局唯一标识，kebab-case 命名	见名知意，如 `page-creator` 而非 `pc`
`description`	语义匹配的核心，AI 据此判断是否触发	写清楚"做什么 + 什么时候用"
`when_to_use`	补充触发上下文，与 description 拼接匹配	列出关键词和典型场景，250 字符内
`paths`	条件加载，仅处理匹配文件时激活	精确控制，避免无关场景误触发
`user-invocable`	是否允许用户通过斜杠命令主动调用	基础工具设 true，内部辅助 Skill 设 false

description 是最重要的属性，因为它直接决定 AI 能否在正确的时机选中你的 Skill。写法建议：

css 复制代码

当 [核心场景] 时使用此技能。触发词包括 [关键词/场景]。也适用于 [相邻场景]。不适用于 [排除场景]。

举一个实际对比：

yaml 复制代码

# 好的 description
description: "按照项目规范创建 React 页面，包含 MobX 状态管理、常量定义和样式文件。当用户要求创建页面、添加新路由、搭建页面模块时使用。不适用于创建独立组件。"

# 差的 description
description: "页面创建技能"

前者给了 AI 足够的语义信息来判断"该不该用"，后者太模糊，容易误触发或漏触发。

执行控制：决定 Skill 怎么运行

属性	作用	实战建议
`context`	fork（独立上下文）或 inline（共享主对话）	一次性任务用 fork，连续交互用 inline
`allowed-tools`	工具权限白名单	最小权限原则，只给必要权限
`model`	指定执行模型	复杂推理用高能力模型，简单任务用轻量模型
`effort`	思考深度	模板填充用 low，架构决策用 high
`disable-model-invocation`	纯脚本模式，不调用模型	确定性脚本任务设 true

context: fork 和 allowed-tools 的组合特别重要------fork 创建隔离环境，allowed-tools 在这个环境里划出权限边界。两者配合，确保 Skill 不会越权操作。

参数与高级配置

arguments + argument-hint：定义 Skill 的位置参数，在正文中通过 $1、$2 引用
agent：指定关联的 Agent，Skill 执行时自动实例化该 Agent
hooks：在特定时机自动执行命令（如 PreToolUse 时运行 linter）

一个贴近实战的配置示例

yaml 复制代码

---
name: page-creator
description: "按照项目规范创建 React 页面，包含 MobX store、常量定义和 SCSS 样式文件。当用户要求创建页面或搭建页面模块时使用。"
when_to_use: "触发词包括'创建页面'、'新建页面'、'添加路由'、'搭建页面'。"
user-invocable: true
context: fork
allowed-tools: [Read, Write, Edit, Bash]
model: claude-sonnet-4-6
effort: high
paths: ["src/pages/**/*"]
arguments: ["page-name"]
argument-hint: "要创建的页面名称（如 user-profile）"
---

这个配置的含义：当用户提到"创建页面"或正在操作 src/pages/ 下的文件时，AI 会自动识别并激活这个 Skill；在隔离环境中以高思考深度执行，只允许读写和运行命令。

三、Skills 使用方式

三种触发模式

1. 斜杠命令主动触发

用户在对话中输入 /page-creator user-profile，直接调用对应 Skill，user-profile 作为 $1 传入正文。

适合：明确的、用户知道自己要做什么的场景。

2. 语义匹配自动触发

AI 根据 description 和 when_to_use 的语义，自动判断当前任务是否匹配某个 Skill。

适合：用户可能不知道 Skill 存在，但描述的任务恰好对应某个 Skill 的场景。

3. 路径匹配条件触发

当 AI 处理的文件路径匹配 paths 中的 glob 模式时，自动激活对应 Skill。

适合：特定文件类型的操作规范，如只在 .scss 文件上激活样式规范 Skill。

三种模式可以叠加------一个 Skill 可以同时支持斜杠命令、语义触发和路径触发。

执行流程

复制代码

触发 → 解析 frontmatter → 应用权限 → 创建执行环境 → 执行正文 → 返回结果

关键环节说明：

解析 frontmatter：读取 Skill 的配置属性，确定执行参数
应用权限 ：allowed-tools 覆盖默认权限，构建安全沙箱
创建执行环境 ：context: fork 时创建隔离环境，inline 时在当前对话中继续
执行正文：按 SKILL.md 中定义的工作流运行
返回结果：fork 模式下结果回到主对话，inline 模式下直接在当前对话输出

fork vs inline：关键选择

维度	fork	inline
上下文	独立隔离，不污染主对话	共享主对话历史
Token 消耗	只加载 Skill 相关内容	包含主对话全部历史
适用场景	一次性、可闭环的任务	需要对话上下文的连续任务
结果返回	任务完成后回到主对话	直接在当前对话输出

实战建议：大多数 Skill 应该用 fork。只有当 Skill 的执行严重依赖主对话的上下文（比如根据之前的讨论做后续处理）时才用 inline。

Skill 与 Agent 的协作

当 Skill 配置了 agent 字段且 context: fork 时，执行流程会多一步：

perl 复制代码

触发 → 解析配置 → 实例化 Agent → 在 fork 环境中运行 Agent → 返回结果

Skill 是任务蓝图，Agent 是执行专家。Skill 定义"做什么"，Agent 决定"以什么角色和专业能力来做"。

例如，一个代码审查 Skill 可以指定 agent: code-reviewer，让代码审查专家在隔离环境中执行审查流程，而不是由通用 AI 凭常识审查。

这种协作关系是单向的：Skill → Agent 可以触发，但 Agent 不会反向调用特定 Skill。

四、怎么使用 AI 辅助生成 Skills 规则

这一节是整篇文章最"元"的部分：用 AI 来写给 AI 看的规则。

很多人写 Skill 的方式是：打开 SKILL.md → 凭想象写一堆规则 → 发现 AI 根本不按预期执行 → 怀疑 Skill 没用 → 放弃。

问题不在 Skill 机制，而在生成方式。正确做法是：让 AI 参与规则的生成和迭代。

核心循环：描述 → 生成 → 试用 → 修正

复制代码

自然语言描述意图 → AI 生成初稿 → 实际场景试用 → 观察偏差 → 修正规则 → 再试用 → 稳定

这不是一次性的，而是一个迭代过程。每次试用中发现的偏差，都是规则不完善的信号。

第一步：用自然语言描述意图

不要一上来就写 YAML frontmatter。先像跟同事说话一样，描述你想要的行为：

我想让 AI 在创建 React 页面时，自动生成 index.jsx、useStore.js、constant.js、index.scss 四个文件，每个文件都要遵循我们项目的规范。useStore 里要用 createShareStore + useLocalStore 的组合，constant.js 里不能放 UI 文案，SCSS 必须按 DOM 层级嵌套。

这种描述虽然不够结构化，但信息量足够让 AI 理解你的意图。结构化是后面迭代的事，不是起点。

第二步：让 AI 生成初稿

把上面的自然语言描述交给 Claude，让它生成 SKILL.md 的初版。

这一步的关键是：接受初版一定不完美。初版的作用是给出一个可执行的起点，而不是最终版本。它可能有遗漏、可能有过度约束，但它给了你一个可以试用的东西。

第三步：实际试用，观察偏差

在实际场景中使用这个 Skill，仔细观察 AI 的输出与你的预期之间的差距。

常见偏差类型：

偏差类型	表现	修正方式
遗漏	AI 跳过了某个步骤	在 Workflow 中补充该步骤
越界	AI 做了不该做的事	在 Constraints 中添加禁止项
偏离	AI 的输出格式不对	在 Output format 中给出明确模板
不稳定	有时对有时不对	添加检查清单或校验步骤

第四步：把纠正转化为规则

这是最关键的一步。每次你发现 AI 做错了，不要只是手动改结果，而是把纠正写回 Skill 规则。

举几个实际例子：

AI 把页面标题放进了 constant.js → 在 constant-js 模板的 Constraints 里加上"禁止放置页面标题、按钮文案等 UI 展示内容"
AI 在 SCSS 里手写了 vw 单位 → 在样式模板里加上"禁止手写 vw，直接写设计稿 px 值"
AI 在子组件里直接 import 了父页面的 store → 在子组件模板里加上"不建议直接引用父级 useStore，优先通过 props 传递"
AI 在 SCSS 里把父子 DOM 的 class 拍平成同级选择器 → 加上"SCSS 嵌套层级必须与 JSX DOM 层级一致，禁止父子 class 拍平"

最有价值的规则来自失败案例，而不是理想描述。 你能写出的最好的 Constraints，都是 AI 实际犯过的错。

实用技巧

1. 从简开始，逐步加规则

初版 Skill 只写最核心的流程和最关键的禁止项。不要试图一次覆盖所有边界情况------你无法预见所有边界，但可以在使用中逐步发现。

一个判断标准：如果某个规则你还没见过 AI 违反，就不需要提前写。等它违反了再补，比预判所有可能性更高效。

2. 禁止项比建议项更有价值

"应该做什么"是方向性指导，AI 有时会理解偏差。"不能做什么"是硬边界，AI 更容易遵守。

写法对比：

markdown 复制代码

# 弱约束------AI 可能理解为"尽量"
- 建议 SCSS 选择器与 DOM 层级保持一致

# 强约束------AI 知道这是红线
- SCSS 选择器嵌套层级必须与 JSX DOM 层级一致，禁止父子 DOM class 拍平成同级选择器

后者比前者有效得多。原因很简单：AI 的"创造力"在约束不清晰时会把事情带偏，明确的禁止项直接收窄了发挥空间。

3. 给判断条件，不给模糊建议

markdown 复制代码

# 模糊------AI 凭感觉决定
- 页面复杂时考虑拆分组件

# 明确------AI 有量化依据
- 当 index.jsx 超过 300 行、JSX 嵌套超过 4 层、或页面有 3 个以上独立业务区块时，必须拆分子组件

明确的阈值让 AI 有判断依据，而不是凭感觉决定。你给的阈值越具体，AI 的执行越稳定。

4. 模板 + 规则 + 检查清单 = 完整闭环

模板告诉 AI "正确长什么样"
规则告诉 AI "必须怎么做、不能怎么做"
检查清单让 AI 在完成后自检

三者缺一，都会导致执行偏差。有模板没规则，AI 可能照猫画虎但细节不对；有规则没模板，AI 知道方向但不知道起点；有模板和规则没检查清单，AI 可能遗漏关键步骤而不自知。

5. 大段规则拆到 reference/，SKILL.md 只引用

当某个方面的规则超过 10 行，就应该拆到独立的 reference 文件中。SKILL.md 只写"按 reference/naming-convention.md 执行命名规范"，需要时才加载，不需要时零开销。

这个原则的本质是按需加载------CLAUDE.md 的规则每次对话都占上下文，Skill 的 reference 只在触发时才读。把低频但重要的规则放在 reference/ 里，既保证需要时能找到，又不会在不需要时浪费 token。

常见误区

误区一：试图一次写完美 Skill

Skill 是活文档，随项目迭代。正确的做法是先跑起来，再逐步完善。写了不用等于没写。

误区二：规则越细越好

过细的规则会导致上下文爆炸，AI 反而更容易迷失。只在 AI 反复出错的点加规则，不出错的地方不用管。一个只有 5 条硬约束的 Skill，往往比一个 50 条细则的 Skill 更有效。

误区三：只写"应该做"，不写"不能做"

AI 的"创造力"有时是灾难------它可能用一种你没见过但完全不符合项目规范的方式完成任务。明确的禁止项是最高效的约束。

误区四：忽略校验环节

执行完不检查，等于把质量把关完全交给 AI。在 Workflow 最后加一步"对照检查清单验证"，能显著提高输出质量。

五、Skills 实战

实战案例一：前端页面开发模板体系

这个案例展示一个真实项目中完整的 Skill 体系------不是一个孤立的 SKILL.md，而是一组相互配合的模板 Skill，加上一个调度它们的 Agent。

体系架构

bash 复制代码

.claude/
├── skills/
│   ├── page-templates/                 # 页面开发模板体系
│   │   ├── index-jsx.md               # 页面入口组件模板
│   │   ├── use-store-js.md            # MobX 状态管理模板
│   │   ├── constant-js.md             # 常量定义模板
│   │   ├── index-scss.md              # 页面样式模板
│   │   ├── 750-design-vw-guide.md     # vw 适配规范
│   │   ├── sub-component-jsx.md       # 子组件模板
│   │   ├── component-split-guide.md   # 拆分判断指南
│   │   ├── component-hooks-guide.md   # Hooks 抽离指南
│   │   ├── component-http-request.md  # 组件请求规则
│   │   └── handle-js.md              # 业务工具函数模板
│   ├── frontend-developer-create-page.md
│   ├── frontend-developer-create-component.md
│   └── frontend-developer-lint.md
└── agents/
    └── frontend-developer.md

Agent 如何调度 Skills

frontend-developer.md 这个 Agent 文件，通过 #include: 指令把 skills、templates 全部编译进来。编译后的内容会 100% 嵌入系统提示词，AI 每次执行时都能看到。

实际的 Agent 文件结构长这样：

yaml 复制代码

---
name: frontend-developer
description: "项目专属前端开发 Agent，React + MobX 移动端 H5 开发专家"
tools: Read, Write, Edit, Glob, Grep, Bash
model: inherit
---

<!-- 第一区：本 Agent 特有 Skill -->
#include: ../skills/frontend-developer-create-component.md
#include: ../skills/frontend-developer-create-page.md
#include: ../skills/page-templates/750-design-vw-guide.md
#include: ../skills/frontend-developer-lint.md

<!-- 第二区：代码模板（Skill 之后，细节参考） -->
#include: ../skills/page-templates/index-jsx.md
#include: ../skills/page-templates/use-store-js.md
#include: ../skills/page-templates/constant-js.md
#include: ../skills/page-templates/index-scss.md
#include: ../skills/page-templates/sub-component-jsx.md
#include: ../skills/page-templates/component-split-guide.md
#include: ../skills/page-templates/component-hooks-guide.md
#include: ../skills/page-templates/handle-js.md

<!-- 第三区：Agent 定位、工作流程和自检清单 -->
---

# frontend-developer Agent

## Purpose
你是 externalChannels 项目的唯一前端开发专家。上面嵌入的所有规范和模板
是你必须遵守的底线，禁止按通用经验自由发挥。

## Mandatory Workflow
1. 匹配规范（根据任务类型选择对应 Skill 和模板）
2. 理解项目现有代码风格（读取 1-2 个相关文件）
3. 按规范编写代码（严格遵守上面嵌入的规范和模板）
4. 增量 lint 检查（只针对变更文件）

## Absolute Prohibitions
严禁执行全局 lint fix 命令，违者会导致全项目数百个文件被意外修改
...

## Completion Checklist
- [ ] 组件命名是否为大驼峰？
- [ ] 样式类名是否为小驼峰？
- [ ] 是否使用了 4 空格缩进？
- [ ] 文件头部注释是否包含功能描述和 @createDate？
（共 20+ 项检查项）

几个关键设计点：

1. #include: 是编译期嵌入，不是运行时引用。 被包含的文件内容会在编译阶段直接展开到 Agent 文件中，最终成为系统提示词的一部分。这意味着 AI 每次对话都能看到完整的规范和模板，不需要按需查找。

2. 加载顺序即优先级。 三个区的排列不是随意的------Skill 最先加载，定义执行流程和约束；代码模板在 Skill 之后，提供生成细节；Agent 定位和工作流最后加载，作为执行的总指挥。当不同层级的规范冲突时，先加载的优先。

执行时的完整流程

当用户说"创建一个用户详情页"：

AI 匹配到 frontend-developer Agent
Agent 通过 #include: 加载所有 Skill 和模板
Agent 识别任务类型为"创建页面"，匹配 create-page Skill
Skill 指定加载页面模板（index-jsx、use-store-js、constant-js、index-scss）
按模板生成四个标准文件
执行 lint Skill 做增量检查
对照 Completion Checklist 自检
返回结果

用户只说了一句话，背后是规范 + 模板 + 检查的完整闭环。

这个体系的设计智慧

模板不是代码片段，而是规范载体。

index-scss.md 不只是给 SCSS 示例，它在约束选择器结构必须跟随 DOM 层级。constant-js.md 不只是给常量示例，它在定义常量文件的职责边界------只放枚举、正则、固定参数，不放 UI 文案。component-split-guide.md 不是简单鼓励"多拆分"，而是给出拆分阈值。

给判断条件，不给模糊建议。

这个体系里每个 Skill 都遵循同一原则：用可量化的条件触发动作，而不是用"建议""考虑""可以"这类模糊词。比如：

拆分组件的触发条件：index.jsx 超 300 行、嵌套超 4 层、3 个以上独立区块
抽离 Hooks 的触发条件：单函数超 50 行、多组件共用逻辑、包含 useEffect 等副作用
不需要抽 Hooks 的条件：单函数小于 30 行、只在一处使用、无副作用的纯计算

模板之间有协作关系。

创建页面时，四个模板同时生效；样式模板依赖 vw 适配规范；子组件模板依赖拆分指南。它们不是孤立存在的，而是一个相互引用的体系。这也是为什么把它们放在同一个 page-templates/ 目录下，而不是散落在各处。

实战案例二：代码提交规范 Skill

再看一个更轻量的 Skill 示例------规范 Git 提交信息。这个 Skill 只有 SKILL.md，没有额外目录，适合作为入门实践：

yaml 复制代码

---
name: commit-guide
description: "根据暂存区变更生成符合 Conventional Commits 规范的提交信息。当用户要求提交代码、生成提交信息或执行 git commit 时使用。"
when_to_use: "触发词包括'commit'、'提交'、'提交信息'、'commit message'。"
user-invocable: true
context: inline
allowed-tools: [Bash, Read]
---

markdown 复制代码

# Commit Guide

## Overview
根据暂存区的变更内容，生成符合 Conventional Commits 规范的提交信息。

## Workflow
1. 运行 `git diff --cached` 查看暂存区变更
2. 分析变更类型（feat/fix/refactor/docs/chore/style/test）
3. 分析影响范围（scope）
4. 生成提交信息，格式：`type(scope): description`
5. 用户确认后执行 `git commit -m "..."`

## Rules
- description 使用中文，不超过 50 字
- scope 对应模块名，如 user、order、payment
- 一个 commit 只做一件事，混合变更拆分提交
- 破坏性变更使用 `!` 标记：`feat(user)!: 重构登录流程`

## Validation
- [ ] type 是否在允许列表中
- [ ] description 是否超过 50 字
- [ ] 是否混合了不相关的变更

结构简单但约束清晰------这正是大多数 Skill 应该有的样子。用 context: inline 是因为提交信息通常需要参考主对话中刚才的改动上下文；用 allowed-tools: [Bash, Read] 是因为提交只需要读文件和执行命令，不需要写文件。

经验总结

1. 从最小可用开始

第一个版本的 Skill 只需要覆盖最核心的流程。随着使用中发现偏差，逐步补充规则、模板和校验。过度设计是 Skill 的天敌------一个跑起来的简陋 Skill 比一个完美的文档强一百倍。

2. 禁止项是最有效的规则

AI 的默认行为可能不符合你的项目规范。用明确的"不能做"来收窄 AI 的发挥空间，比用"应该做"来引导更有效。每一条禁止项背后，都是一次真实的踩坑经历。

3. 检查清单是质量兜底

Workflow 的最后一步应该是验证。让 AI 在完成任务后对照检查清单自检，能捕获大部分明显问题。frontend-developer Agent 的 Completion Checklist 有 20+ 项，覆盖命名、注释、样式、目录结构等方方面面。

4. Skill 是活文档

项目在演进，规范在变化，Skill 也应该跟着迭代。把 Skill 当成代码一样维护：版本管理、定期回顾、根据实际情况调整。不要期望一次写完就永久有效。

5. 体系 > 单点

一个 Skill 解决一个问题，一组 Skill 构成体系。页面创建 Skill + 组件创建 Skill + 代码检查 Skill + 前端开发 Agent = 完整的前端开发工作流。单点 Skill 的价值有限，体系化的 Skill 才能真正改变团队的开发效率。

写在最后

Skills 是 Claude Code 配置体系中"工程化"程度最高的部分。CLAUDE.md 是共识，commands 是快捷方式，而 Skills 是可执行的标准操作流程。

写好 Skill 的关键不是一次写完美，而是：用起来 → 发现问题 → 修正规则 → 再用。这个过程本身就是把团队经验沉淀成可复用资产的过程。

当你的 Skill 体系足够成熟，新成员不需要阅读 Wiki、不需要老员工带------直接用 Skill 创建页面、组件，产出的代码天然符合规范。这才是 Skills 的终极价值：把规范从"文档"变成"执行"。