给AI配工具箱:Skills技能实战

— 智能编码进化论 · 第 04 篇 —

导读前两篇我们搞定了两件事：用CLAUDE.md给AI写岗位说明书，用结构化任务输入让AI听懂指令。但有个问题越来越明显——CLAUDE.md越写越长。API规范、部署流程、代码审查清单、测试模板……全塞进CLAUDE.md里，每次会话不管用不用到都要加载。就像给新员工一本500页的手册让他全背下来，效率不高。Skills就是解决方案。它是按需加载的"工具箱"——用的时候拿出来，不用的时候不占地方。本章讲清楚：Skills和CLAUDE.md怎么分工、怎么从零创建一个Skill、高级玩法有哪些、踩了坑怎么排查。

CLAUDE.md放"必须知道"的，Skills放"用到才知道"的。

信号一：同一段提示词反复粘贴。你发现自己每次都要复制一段"代码审查清单"粘贴给AI——把它变成Skill。

信号二：CLAUDE.md超过200行。Anthropic在Claude Code文档中建议CLAUDE.md控制在200行以内。超出的部分，按主题拆成多个Skills。

信号三：内容只在特定场景使用。部署流程只在发版时用，数据库schema只在写查询时用——这些都不需要每次加载。

Reference Skills（参考型）

提供知识，AI在工作中参考。像一本工具书。

---name: api-conventionsdescription: API设计规范和endpoint格式参考---## API规范- URL使用kebab-case：/user-profiles- 响应格式：{ code: 0, data: {...} }- 错误码：40001=参数错误，50001=服务异常- 分页：?page=1&pageSize=20

Action Skills（动作型）

触发具体任务，像按流程操作的SOP。

---name: deploydescription: 部署应用到生产环境context: forkdisable-model-invocation: true---## 部署流程1. 运行测试套件2. 构建项目3. 推送到部署目标4. 验证部署结果

会话开始时：只加载Skill的名称和描述（description），每个Skill的描述限制1536字符。这些描述帮助AI判断什么时候该用哪个Skill。

调用时：加载完整的SKILL.md内容到对话中。

不调用时：只消耗描述的token，完整内容不加载。

终极省资源：设置disable-model-invocation: true，连描述都不加载，直到你手动/skill-name触发。上下文成本降为零。

官方建议：CLAUDE.md保持在200行以内。超出的参考内容和流程，按主题拆到Skills中。Skills的SKILL.md本身也不宜过长，社区实践建议控制在500行以内——太长的部分拆到支持文件中。

第一步：创建目录

mkdir -p ~/.claude/skills/summarize-changes

个人级目录，所有项目通用。项目级则用.claude/skills/summarize-changes。

第二步：编写SKILL.md

---description: 总结未提交的变更并标记风险点。  当用户问"改了什么""帮我写commit message"  "review一下diff"时自动触发。---## 当前变更!`git diff HEAD`## 指令总结以上变更，2-3个要点，然后列出发现的风险（缺失的错误处理、硬编码值、需要更新的测试）。如果没有未提交变更，直接说"没有未提交的变更"。

第三步：测试

启动Claude Code，做个小改动，然后：

我改了什么？

AI会自动匹配到这个Skill（因为你的问题匹配了description中的"改了什么"），加载内容并给出总结。或者直接输入：

/summarize-changes

---name: deploy                    # 显示名称，默认用目录名description: 部署到生产环境        # AI用这个判断什么时候加载when_to_use: 当用户说"发布""部署""上线"时触发argument-hint: [环境名]          # 自动补全时的参数提示arguments: env                  # 命名参数，内容中用 $env 引用disable-model-invocation: true  # 禁止AI自动触发，只能手动user-invocable: false           # 对用户隐藏，只有AI能触发allowed-tools: Read Bash Grep   # 预授权工具，执行时不弹确认model: sonnet                   # 临时切换模型effort: high                    # 临时切换努力程度context: fork                   # 在子代理中执行---

---description: 代码审查清单---## 当前分支的变更文件!`git diff --name-only HEAD`## 审查指令对以上每个文件，检查：- 是否有未处理的TODO- 是否有硬编码的配置值- 是否缺少错误处理

!`git diff HEAD`                  # 当前变更!`git log --oneline -5`           # 最近提交!`cat package.json | jq .scripts` # npm scripts!`find src -name "*.test.*" | wc -l`  # 测试文件数量!`git branch --show-current`      # 当前分支名

进阶玩法

多行命令用 ` ```! ` 语法

```!# 检查项目健康度echo "=== 测试覆盖率 ==="npm run test:coverage --silent 2>/dev/null | tail -5echo "=== 未提交文件 ==="git status --shortecho "=== 依赖安全 ==="npm audit --production 2>/dev/null | head -3```

code-review/├── SKILL.md              # 主指令（必选）├── checklist.md          # 审查清单├── examples/│   └── good-pr.md        # 优秀PR示例└── scripts/    └── validate.sh       # 校验脚本

按 [checklist.md](checklist.md) 逐项检查。参考 [good-pr.md](examples/good-pr.md) 了解优秀PR的标准。

---name: create-testdescription: 为指定文件生成测试arguments: file pattern---为 $file 生成测试文件。测试模式：$pattern重点覆盖边缘条件。遵循项目中已有测试的风格。运行测试确认通过。

/create-test src/auth/login.ts edge-cases

---name: security-auditdescription: 安全审计context: fork---对当前项目进行安全审计：1. 检查所有API端点是否有输入验证2. 检查是否有SQL注入风险3. 检查敏感信息是否硬编码4. 检查依赖是否有已知漏洞输出一份审计报告，按风险等级排序。

你不想AI自动触发的：比如/deploy——部署是严肃操作，应该由你明确触发。设disable-model-invocation: true。

你想对用户隐藏的：比如内部编码规范的参考知识，用户不需要知道它的存在，AI在相关场景自动加载。设user-invocable: false。

Skills + MCP：MCP提供外部连接，Skills定义使用方式。比如MCP连上了数据库，Skill描述了查询规范和表结构，AI就能写出高质量的SQL。

Skills + Subagent：一个Skill启动多个Subagent并行工作。比如/auditSkill同时启动安全审查、性能检查、代码风格审查三个子代理。

CLAUDE.md + Skills：CLAUDE.md放"必须遵守"的核心规则，Skills放"用到才查"的详细参考。比如CLAUDE.md写"遵循API规范"，Skill放完整的API endpoint列表。

组合示例：CLAUDE.md（永远加载）：  "使用 TypeScript strict 模式，测试覆盖率 > 80%"Skills/api-guide.md（写API时加载）：  "完整endpoint列表、请求格式、错误码对照表"Skills/deploy.md（发版时手动触发）：  "部署流程、环境配置、回滚方案"

Skill 1：API参考

.claude/skills/api-reference/SKILL.md

---description: 项目API设计参考，包含endpoint格式、认证方式、错误码---## Endpoint格式!`grep -r "router." src/routes/ --include="*.ts" | head -20`## 错误码参考 [error-codes.md](error-codes.md)

Skill 2：代码审查

.claude/skills/code-review/SKILL.md

---description: 代码审查清单disable-model-invocation: trueallowed-tools: Read Grep Bash---## 变更文件!`git diff --name-only HEAD`按 [checklist.md](checklist.md) 审查以上文件的变更。

Skill 3：测试生成

.claude/skills/create-test/SKILL.md

---description: 为指定模块生成测试arguments: module---为 $module 生成测试。参考项目中已有测试的风格：!`find src -name "*.test.ts" | head -1`

好的Skill配置就像好的工具箱——每个工具都有自己的位置，用的时候伸手就能拿到，不用的时候不碍事。

坑一：Skill写好了但AI不触发

你创建了一个Skill，问AI相关问题，但它没用那个Skill。

排查路径（按顺序检查）：

坑二：Skill触发太频繁

你问个无关的问题，AI也加载了某个Skill。

解法：把description写得更具体。从"代码审查"改成"对git diff中的变更进行代码审查，检查代码质量和潜在风险"。越具体，误触发的概率越低。

如果还是太频繁，直接设disable-model-invocation: true，改为手动触发。

坑三：Skill描述被截断

Skill的description有1536字符的限制。超出的部分会被截断，AI看不到完整描述。

解法：把最关键的信息放前面。description的第一句话就应该说明"这个Skill干什么、什么时候用"。细节放到when_to_use字段或正文中。

坑四：`!`命令执行失败

动态注入的命令报错，Skill加载失败。

常见原因：命令依赖的环境在Skill加载时不存在（比如需要特定的shell环境变量）。解法：用绝对路径，或在命令中加入错误处理。

坑五：context:fork后拿不到主会话的上下文

设了context: fork，但Skill里引用了主会话中的对话内容。

原因：`fork` 是完全隔离的子代理上下文，看不到主会话的历史。解法：所有需要的信息都在SKILL.md正文中自包含。用!语法注入实时数据，不要依赖对话历史。

Skills是按需加载的工具箱——用的时候才拿，不用的时候不占地方。

`!`语法是杀手特性——动态注入实时数据，让Skill的指令基于当前状态而非静态文本。

frontmatter控制行为——description决定触发时机，context控制执行方式，allowed-tools减少确认弹窗。

组合使用威力最大——Skills + MCP + Subagent，让AI拥有"知道怎么用工具"的超能力。

CLAUDE.md保持在200行——超出的内容按主题拆到Skills中。

下一篇，我们给AI接外线——MCP外部集成实战。如果说Skills是给AI配了内部工具箱，MCP就是给它接通了外部电话线，让它能和数据库、API、云服务直接对话。

你的项目里，哪些重复性的提示词或流程可以封装成Skill？是部署流程、代码审查清单，还是API参考文档？来评论区分享你的Skill设计思路。

下一篇预告：《给AI接外线：MCP外部集成实战》

系列文章

羲和实验室由AI训练师与智能体共同组成，致力于探索人机协作的最佳实践，让每个人都能驾驭AI，让技术为人类创造更多价值。

🚀 关注「羲和实验室」

点击下方卡片关注公众号

回复「ClaudeCode」获取系列完整资料

微信号：xihe-lab

参考资料

免责声明

本文内容仅供学习交流，所述方法需结合实际场景灵活运用。AI工具输出结果仅供参考，关键业务决策请结合人工判断。

本文由AI辅助创作，经人工审核编辑后发布。

🚀 羲和实验室 · 智能编码进化论

让每个人都能驾驭AI，让技术为人类创造更多价值