04 Claude Code之Skills技能系统深度解析Skills 系统是 Claude Code 最强大的知识工程化机制让开发者将领域知识、团队规范和最佳实践打包成可复用的 AI 能力模块。本文深度解析 Skills 的核心哲学渐进式披露、与 CLAUDE.md 的本质区别、目录结构规范、SKILL.md 编写最佳实践含 Gotchas 编写方法和 !command 动态注入以及三级技能管理机制。掌握 Skills 系统让 AI 在特定任务中真正变成领域专家。关键字Claude Code Skills、技能系统、SKILL.md、渐进式披露、子智能体、技能触发、MCP集成、知识工程化标签Claude CodeSkills技能系统AI工程化SKILL.md提示工程知识管理开发工具写在前面在 Claude Code 的所有特性里Skills 系统是我用了最久才真正理解其价值的一个。最开始我把 Skills 理解成命令快捷方式就像 IDE 的代码片段一样。后来发现完全不对——Skills 是一套知识工程化机制让你把开发经验、团队规范、领域知识打包成可复用的 AI 能力模块在需要时按需加载不需要时不占用上下文空间。换句话说它解决的是如何让 AI 在特定任务中变成专家的问题。一、为什么需要 Skills理解 Skills 的价值要先理解 CLAUDE.md 的局限性。CLAUDE.md 是每次会话都会自动加载的项目规范文件。它很有用但有一个根本问题所有内容不管用不用都占上下文。假设你的项目有这些规范前端组件开发规范500 token后端 API 设计规范400 token数据库迁移规范300 tokenCI/CD 部署流程600 token代码审查检查清单400 token全部放在 CLAUDE.md每次会话都消耗 2200 token不管你这次要做什么。用 Skills开发前端组件时只加载前端规范500 token写数据库迁移时只加载迁移规范300 token做 code review 时只加载检查清单400 tokenSkills 的核心是渐进式披露——只在需要时提供需要的知识。二、Skills 目录结构项目根目录/ -- .claude/ -- skills/ -- code-review/ # 代码审查技能 | -- SKILL.md # 主说明文件必需 | -- checklist.md # 检查清单参考文件 | -- examples/ | | -- good-pr.md # 好的PR示例 | | -- bad-pr.md # 需要改进的示例 | -- scripts/ | -- run-checks.sh # 辅助脚本 -- deploy/ # 部署技能 | -- SKILL.md | -- staging-steps.md | -- prod-checklist.md -- migration/ # 数据库迁移技能 -- SKILL.md -- template.sql作用域与优先级作用域 位置 适用范围 企业级 托管设置配置 组织内所有用户 个人级 ~/.claude/skills/ 个人所有项目 项目级 .claude/skills/ 当前项目 插件级 plugin/skills/ 启用该插件的环境同名 Skill 按优先级覆盖项目级 个人级 企业级。三、SKILL.md 编写核心规范SKILL.md 是技能的大脑。它的 frontmatter 控制触发行为正文内容决定执行质量。Frontmatter 字段详解--- name: code-review description: 当用户请求代码审查、review PR、检查代码质量时使用。审查Python/Go/TypeScript代码关注安全性、性能、可读性和测试覆盖 user-invocable: true disable-model-invocation: false allowed-tools: Read, Grep, Bash(git diff *), Bash(git log *) context: fork agent: Explore ---字段作用实战建议descriptionClaude 决定何时自动触发的依据写何时用我而非我是什么disable-model-invocation禁止 Claude 自动触发危险操作部署设为 trueuser-invocable是否出现在/菜单内部逻辑技能设为 falseallowed-tools该技能可用的工具白名单最小权限原则context: fork在子智能体中独立运行避免污染主上下文agent指定使用的子智能体类型Explore 用于探索读取description 字段的写法是关键这是我见过最常被写错的字段# 错误写法描述技能是什么 description: 一个代码审查技能使用AI分析代码质量 # 正确写法描述什么时候触发 description: 当用户请求 review PR、code review、审查代码质量、检查安全漏洞时触发。 适用场景PR 提交前检查、代码合并审查、安全审计Claude 会用description来决定现在是不是要加载这个技能。写触发条件不写功能描述。四、完整技能示例代码审查这是我在实际项目中用的代码审查技能包含了设计思路注释--- name: code-review description: 审查代码质量当用户请求review、code review、PR审查、检查代码时触发 allowed-tools: Read, Grep, Bash(git diff *), Bash(git log --oneline *) context: fork --- # 代码审查规范 ## 审查维度按重要性排序 ### 1. 安全性必须通过 - SQL 注入检查所有数据库查询是否使用参数化 - 权限验证每个 API 端点是否有认证检查 - 敏感信息日志中不得出现密码、token、私钥 - 输入验证外部输入是否在入口处验证 ### 2. 正确性 - 边界条件空值、零值、最大值处理 - 并发安全共享状态的锁/原子操作 - 错误处理错误是否被传播或正确处理不能静默忽略 ### 3. 性能 - N1 查询循环内的数据库查询 - 不必要的重复计算缓存机会 - 大对象的复制问题 ### 4. 可读性 - 函数长度超过 50 行考虑拆分 - 命名清晰度避免 tmp、data、obj 等无意义命名 - 注释必要性复杂逻辑需要注释意图而非代码解释 ## 审查流程 1. 运行 git diff main...HEAD 查看变更范围 2. 按安全 → 正确性 → 性能 → 可读性顺序审查 3. 对每个问题标注级别[BLOCK] 必须修改 | [SUGGEST] 建议改进 | [QUESTION] 需要确认 ## 输出格式代码审查报告 必须修改 (BLOCK)[文件:行号] 问题描述 修改建议 建议改进 (SUGGEST)[文件:行号] 问题描述 修改建议 需要确认 (QUESTION)[文件:行号] 疑问描述总体评价[1-2句总结]## Gotchas高价值注意事项 - 不要评论风格问题除非项目有明确规范 - 只审查变更行不要扩展到未修改的代码 - 对于复杂的性能问题提供压测建议而非假设五、触发机制自动 vs 手动自动触发Claude 在处理你的请求时会根据description字段的语义相似性判断是否加载相关技能你: 帮我看看这个 PR 有没有问题 ↓ Claude 检查 Skills 描述 code-review: 当用户请求review、PR审查时触发 ← 匹配 deploy: 当用户要部署、上线时触发 ← 不匹配 ↓ 自动加载 code-review skill ↓ 按技能规范进行审查手动触发# 手动调用技能/code-review# 带参数调用/deploy staging v1.2.3技能的$ARGUMENTS占位符会接收斜杠命令后的所有参数$1、$2按位置访问。六、技能与 CLAUDE.md 的配合使用最有效的配置方式是分层管理CLAUDE.md永久加载保持精简 -- 项目技术栈说明2-3行 -- 代码规范关键点5-10行 -- 常用命令3-5行 Skills按需加载可以详细 -- code-review/ 详细审查标准 -- deploy/ 完整部署流程 -- migration/ 数据库迁移步骤 -- debug/ 调试方法论这样 CLAUDE.md 保持在 50 行以内不会每次消耗大量上下文详细规范在技能文件里按需提供。总结Skills 系统的核心价值把知识工程化让 AI 在特定任务上变成专家。三个关键实践description写触发条件不写功能描述用context: fork隔离复杂任务保护主上下文CLAUDE.md 保精简技能文件存详细规范掌握 Skills 系统是从会用 Claude Code到用好 Claude Code的重要分水岭。