作为一名专注于AI开发工具超过15年的技术专家，我将从实战角度重构这篇Claude Code Skills教程，为你拆解“一次配置，终身复用”的真正落地方法。直接进入正题。

Claude Code Skills 深度使用指南

你大概率经历过这样的场景：每次启动Claude Code都得手动粘贴一份万字审查清单；团队里十个成员用十种不同的部署脚本，相互之间毫无可读性。Skills正是为了终结这种混乱——它将高频操作、团队规范、专项任务打包成可随时调用的“技能单元”。无论是通过`/技能名`手动触发，还是依赖上下文自动匹配，都能让工作流标准化。核心逻辑一句话：**一次配置，跨项目复用**。 接下来，我从基础概念、快速起步、高级技巧到故障排除，搭配完整代码实例，彻底讲透Skills。 ### 一、Skills 核心概念与价值 在动手之前，先厘清Skills在Claude Code生态系统中的定位，避免与Subagents、Plugins等概念混淆。 - **核心定义**：Skills是一种轻量化扩展组件，专门封装可复用的指令集、工作流或领域知识。通过`/技能名`手动触发，或根据当前对话语义自动激活。 - **核心价值**：消除重复输入，统一团队规范，一键启动复杂工作流。 - **与其他功能区别**：Subagents提供独立子任务环境，Plugins是功能完备的插件包，而Skills是最小可复用单元。它虽精简，但能独立使用，也能嵌入到插件或子任务中。 重点：Skills完全向下兼容老版本`.claude/commands/`目录。你已有的自定义命令可以直接迁移，并额外获得高级参数传递、上下文隔离等能力。它遵循Agent Skills开放标准，未来可在不同工具间复用。 ### 二、快速上手：创建并使用第一个技能 以“代码可视化解释”技能（`explain-code`）为例，三步即可投入使用。 #### 第一步：创建技能目录 Skills有固定的目录结构。存放位置决定技能的“管辖范围”——当前项目独占，还是全局可用。 ```bash # 创建个人全局技能目录（所有项目可调用） mkdir -p ~/.claude/skills/explain-code # 若仅用于当前项目，执行以下命令 # mkdir -p .claude/skills/explain-code ``` #### 第二步：编写 SKILL.md（核心文件） 每个技能必须包含`SKILL.md`文件，这是它的“大脑”。结构分为两部分：开头的YAML元数据（推荐但非强制），以及后面的Markdown执行指令（必须）。 创建并编辑文件： ```bash cd ~/.claude/skills/explain-code vim SKILL.md ``` 写入以下内容： ```markdown --- # YAML 前置元数据 name: explain-code # 技能名，对应斜杠命令（小写字母、数字、连字符） description: 使用日常类比+ASCII图表解释代码逻辑，用户询问“代码如何工作”时自动触发 argument-hint: "[file-path]" # 提示用户调用时需传入文件路径 --- # Markdown 执行指令（技能的核心逻辑） 1. 先用1个日常类比，通俗说明代码核心功能（避免堆砌技术术语） 2. 用ASCII图表绘制代码执行流程或数据结构（要求清晰直观） 3. 逐行拆解关键代码，说明每一步的作用 4. 指出代码中常见的使用误区与踩坑点 5. 最终输出简洁总结，便于快速理解 ``` #### 第三步：测试调用技能 配置完成无需重启，在Claude Code中直接唤起。 - **自动调用**：当提问匹配`description`中的关键词时，技能自动激活。 ``` > 这段代码是如何工作的？ ``` - **手动调用**：输入`/技能名`，并可选传入参数（如文件路径）。 ``` > /explain-code src/auth/login.ts ``` 调用成功后，Claude会严格遵循`SKILL.md`中定义的规则，输出带类比和ASCII图表的代码解释。 ### 三、技能存储路径与标准目录结构 创建第一个技能后，需要了解技能存放位置的决定性因素—路径影响适用范围，也决定了能否通过Git共享给队友。 #### 3.1 技能存储路径与适用范围 | 技能类型 | 存储路径 | 适用范围 | 共享方式 | | :--- | :--- | :--- | :--- | | 个人技能 | `~/.claude/skills//SKILL.md` | 当前用户所有项目 | 仅自己可见 | | 项目技能 | `.claude/skills//SKILL.md` | 仅当前项目 | 可提交Git，团队共享 | | 插件技能 | `/skills/...` | 启用该插件的所有项目 | 随插件安装统一分发 | | 企业技能 | 企业托管设置 | 组织内全员、全项目 | 管理员统一配置 | 补充：在Monorepo（多子包）结构中，支持嵌套目录自动发现。子包可以在自己的目录下创建`.claude/skills/`，维护专属技能，不影响主项目。 #### 3.2 技能标准目录结构 除`SKILL.md`外，技能还可以携带可选附件： ``` my-skill/ # 技能根目录，建议与技能名一致 ├── SKILL.md # 必需：核心配置与执行指令 ├── reference.md # 可选：详细参考文档（按需加载，不占上下文） ├── examples.md # 可选：技能输出示例 └── scripts/ # 可选：辅助执行脚本 └── helper.sh # 可选：调用脚本，提升复杂度 ``` 例如，为`explain-code`技能添加辅助脚本，生成更精致的ASCII图表： ```bash mkdir -p ~/.claude/skills/explain-code/scripts echo '#!/bin/bash echo "┌───────────┐读取代码┌───────────┐" echo "│用户传入文件├─────────>│解析代码逻辑│" echo "└───────────┘ └───────────┘" echo "│" echo "▼" echo "┌───────────┐输出解释┌───────────┐" echo "│生成类比+图表<─────────┤逐行拆解代码│" echo "└───────────┘ └───────────┘"' > ~/.claude/skills/explain-code/scripts/helper.sh chmod +x ~/.claude/skills/explain-code/scripts/helper.sh ``` 然后修改`SKILL.md`，在指令中调用这个脚本： ```markdown --- name: explain-code description: 使用日常类比+ASCII图表解释代码逻辑 argument-hint: "[file-path]" allowed-tools: Bash # 允许技能调用Bash工具 --- # 代码解释规则 1. 执行辅助脚本，生成代码流程ASCII图表 ```bash ~/.claude/skills/explain-code/scripts/helper.sh ``` 2. 先用日常类比说明核心逻辑 3. 逐行拆解执行步骤 4. 指出常见误区与坑点 ``` ### 四、SKILL.md 配置完全解析 路径和结构清晰后，深挖`SKILL.md`的核心配置细节。 #### 4.1 YAML 前置元数据（可选，但推荐） 用`---`包围放在文件头部，所有字段均可选。但`name`和`description`强烈推荐，因为它们决定技能的调用方式和自动触发时机。 ```markdown --- # 1. 核心基础配置 name: skill-name # 技能名，斜杠命令的名字（小写、数字、连字符，如 code-review） description: 技能功能说明 # 关键！用于AI判断是否自动触发，应包含触发关键词 # 2. 调用控制配置 disable-model-invocation: true # 禁止AI自动调用，仅限手动（适合部署等高危操作） user-invocable: false # 隐藏斜杠命令，仅限AI自动使用（适合背景知识注入） argument-hint: "[file] [option]" # 调用提示，告诉用户传参格式 # 3. 权限与环境配置 allowed-tools: Read,Grep,Bash # 技能运行时，允许免授权使用的工具（最小权限原则） model: sonnet-4.6 # 指定技能运行的模型（默认随主会话） context: fork # 在独立隔离环境中运行，不污染主会话 agent: Explore # 指定子任务类型，如Explore（调研）、Debug（调试） --- ``` 一个常用的配置组合——高危操作技能，比如部署到生产环境： ```markdown --- name: deploy-prod description: 部署应用到生产环境（高危操作） disable-model-invocation: true # 禁止AI自动触发 allowed-tools: Bash,gh # 只允许使用Bash和GitHub CLI argument-hint: "[branch]" # 需要传入部署分支 --- ``` #### 4.2 Markdown 执行指令（必需） 这部分是技能的“灵魂”，定义具体行为。按用途可分为两类： - **参考型技能**：注入项目规范、风格指南等背景知识。不需要手动调用，AI自动参考并遵守。 ```markdown --- name: api-conventions description: 项目REST API设计规范，AI处理API相关任务时自动参考 --- # 项目REST API设计规范 1. 路径命名：使用kebab-case（如 /api/user-info，禁止下划线） 2. 参数命名：JSON请求/响应使用camelCase（如 userId，禁止下划线） 3. 列表接口：必须支持分页，默认页码page=1，每页条数size=10 4. 响应格式：统一返回 { code: 数字, message: 字符串, data: 任意类型 } 5. 错误处理：异常状态码统一使用4xx、5xx，并返回具体错误信息 ``` - **任务型技能**：定义分步执行的复杂工作流，适合手动调用，如代码审查、部署。 ```markdown --- name: code-review description: 按团队规范审查代码，手动调用时执行 allowed-tools: Read,Grep argument-hint: "[file-path]" --- # 代码审查工作流 1. 读取指定文件，检查语法与ESLint规范 2. 排查潜在问题：空指针、未处理异常、变量未定义、死循环等 3. 分析性能：是否存在冗余逻辑、无效查询、频繁IO操作 4. 检查可读性：变量/函数命名是否规范、是否有必要的注释 5. 输出格式：文件路径+行号+问题类型+具体问题+修复建议 示例：src/utils/format.js:15 【冗余逻辑】多余的if判断，可简化为三元表达式 ``` ### 五、技能高级功能 基础创建只是热身，以下高级功能让技能真正灵活强大。 #### 5.1 参数传递（$ARGUMENTS 占位符） 当技能需要动态接收参数（如文件路径、Issue编号）时，使用`$ARGUMENTS`占位符。调用时传入的参数会自动替换它。 实战：创建“修复GitHub Issue”技能（`fix-issue`）。 ```markdown --- name: fix-issue description: 修复指定GitHub Issue，手动调用时执行 disable-model-invocation: true allowed-tools: Bash,gh argument-hint: "[issue-number]" --- # 修复GitHub Issue #$ARGUMENTS 工作流 1. 用gh命令查看Issue详情 gh pr view $ARGUMENTS --comments 2. 定位相关代码文件，分析问题根源 3. 实现修复代码，确保符合项目规范 4. 编写单元测试，验证修复效果 5. 提交代码，创建PR，关联该Issue（PR描述中包含 #$ARGUMENTS） ``` 调用时直接输入： ``` > /fix-issue 123 ``` 注意：参数紧跟技能名，无多余空格。多个参数用空格分隔，`$ARGUMENTS`会接收所有传入内容。 #### 5.2 动态上下文注入（!`command` 语法） 在技能指令中使用 `` !`command` `` 语法，让技能在执行时先运行一个Shell命令，并将输出注入到上下文中。实现动态数据获取。 实战：创建“PR变更总结”技能（`pr-summary`）。 ```markdown --- name: pr-summary description: 总结当前PR的变更内容，手动调用时执行 context: fork # 隔离子任务运行 allowed-tools: Bash(gh:*) # 仅允许使用gh命令 --- # PR 变更总结 ## 一、PR 基础信息 - PR 差异内容：!`gh pr diff` - PR 评论信息：!`gh pr view --comments` - 变更文件列表：!`gh pr diff --name-only` ## 二、总结规则 1. 提炼核心变更（新增/修复/重构） 2. 列出关键文件，说明每个文件的修改目的 3. 指出潜在的风险点与兼容性问题 4. 总结测试情况 ``` 调用时执行`/pr-summary`，技能将抓取PR实时信息，再按规则输出总结。 #### 5.3 子任务隔离运行（context: fork） 通过配置`context: fork`，技能在独立小环境中运行。拥有独立上下文和工具权限，与主会话完全隔离，互不污染。适合复杂调研或批量脚本执行。 实战：创建“深度代码调研”技能（`deep-research`）。 ```markdown --- name: deep-research description: 深度调研指定代码模块，输出详细总结 context: fork agent: Explore allowed-tools: Read,Grep,Glob argument-hint: "[module-path]" --- # 深度代码调研流程 彻底调研 $ARGUMENTS 模块： 1. 检索该模块下所有相关文件（使用Glob工具匹配） 2. 分析每个文件的核心逻辑、函数关系、数据流向 3. 关联项目其他模块，说明该模块的作用与依赖关系 4. 输出带文件引用的总结（标注文件路径+行号） 5. 提出优化建议（若有） ``` 使用`/deep-research src/auth/`，技能在独立环境中完成调研，只输出最终结果，不干扰主会话。 #### 5.4 辅助脚本与可视化输出 想要更复杂的功能（如生成可视化页面），需绑定Shell或Python脚本。 示例（“代码库可视化”技能）： ```markdown --- name: codebase-visualizer description: 生成项目目录结构、文件统计的交互式可视化页面 allowed-tools: Bash(python:*) --- # 代码库可视化流程 1. 执行Python辅助脚本，生成HTML可视化页面 python ~/.claude/skills/codebase-visualizer/scripts/visualize.py . 2. 脚本功能说明： - 统计不同类型文件的数量与大小 - 生成可展开/折叠的交互式目录结构 - 标注核心文件与关键代码行数 3. 输出提示：打开生成的 codebase-map.html 文件查看结果 ``` 对应的`visualize.py`脚本（简化版）： ```python # ~/.claude/skills/codebase-visualizer/scripts/visualize.py import os import json file_stats = {} for root, dirs, files in os.walk('.'): for file in files: ext = os.path.splitext(file)[1] or '无后缀' size = os.path.getsize(os.path.join(root, file)) if ext not in file_stats: file_stats[ext] = {'count': 0, 'size': 0} file_stats[ext]['count'] += 1 file_stats[ext]['size'] += size html = f"""

项目文件统计

{json.dumps(file_stats, indent=2)}

""" with open('codebase-map.html', 'w', encoding='utf-8') as f: f.write(html) print("可视化页面已生成：codebase-map.html") ``` ### 六、技能调用控制与权限管理 能力越大，责任越大。高级功能需要精细的权限管控方案。 #### 6.1 调用权限控制（YAML 配置） 通过YAML元数据的两个字段，控制技能是“谁都能调用”还是“仅限人触发”。 | 配置组合 | 用户手动调用 | AI自动触发 | 适用场景 | | :--- | :--- | :--- | :--- | | 默认（都不配置） | 是 | 是 | 通用规范和工具 | | `disable-model-invocation: true` | 是 | 否 | 部署、提交等高危操作 | | `user-invocable: false` | 否 | 是 | 背景知识、隐性规范注入 | #### 6.2 工具权限限制（allowed-tools） 用`allowed-tools`字段约束技能可调用的工具。遵循最小权限原则——只给够用的，避免越权。 ```markdown --- # 只读技能 name: safe-reader description: 只读查看文件内容，禁止任何修改操作 allowed-tools: Read,Grep,Glob # 无修改或执行权限 --- ``` ```markdown --- # 部署技能 name: deploy-dev description: 部署应用到开发环境 allowed-tools: Bash,npm,gh # 仅允许这三项 disable-model-invocation: true --- ``` #### 6.3 全局权限管控（/permissions 命令） 需要全局控制所有技能开关？使用`/permissions`命令。 ``` # 禁用所有技能 > /permissions deny Skill # 只允许指定技能 > /permissions allow Skill(code-review) > /permissions allow Skill(pr-summary:*) # 拒绝某个高危技能 > /permissions deny Skill(deploy-prod:*) # 查看当前权限 > /permissions list Skill ``` ### 七、实用技能模板（可直接复制使用） 纸上谈兵终觉浅，这里分享三个高频技能模板，可复制修改后立即生效。 #### 模板1：代码审查技能（项目级，团队共享） 路径：`.claude/skills/code-review/SKILL.md` ```markdown --- name: code-review description: 按团队ESLint规范、代码标准审查指定文件 allowed-tools: Read,Grep argument-hint: "[file-path] [review-type]" --- # 团队代码审查清单 ## 审查规则（按类型区分） 1. 语法审查（syntax）： - 符合项目ESLint配置 - 禁止var，统一用let/const - 函数、变量命名规范（camelCase） 2. 性能审查（performance）： - 避免冗余逻辑、无效循环 - 禁止频繁IO操作、重复查询 - 优化大型数组、对象的处理方式 3. 可读性审查（readability）： - 关键逻辑添加注释 - 代码缩进、换行规范（2空格缩进） - 单函数不超过80行 ## 输出要求 - 格式：文件路径+行号|问题类型|具体问题|修复建议 - 示例：src/utils/format.js:20|语法|使用var|替换为const - 无问题输出：“未发现不符合规范的问题” ``` #### 模板2：会话日志技能（个人级，记录操作） 路径：`~/.claude/skills/session-logger/SKILL.md` ```markdown --- name: session-logger description: 记录当前会话的操作日志，手动调用时执行 allowed-tools: Bash argument-hint: "[operation-description]" --- # 会话日志记录流程 1. 创建日志目录（若不存在） mkdir -p ~/.claude/session-logs 2. 写入日志（格式：时间+会话ID+操作描述） echo "$(date +'%Y-%m-%d %H:%M:%S') - 会话ID: $CLAUDE_SESSION_ID - 操作: $ARGUMENTS" >> ~/.claude/session-logs/session.log 3. 输出提示：日志已记录至 ~/.claude/session-logs/session.log ``` #### 模板3：代码批量格式化技能（个人级） 路径：`~/.claude/skills/batch-format/SKILL.md` ```markdown --- name: batch-format description: 批量格式化指定目录下的JS/TS文件，按ESLint规范 disable-model-invocation: true allowed-tools: Bash,npm argument-hint: "[dir-path]" --- # 代码批量格式化流程 1. 检查指定目录是否存在 ```bash if [ ! -d "$ARGUMENTS" ]; then echo "目录不存在：$ARGUMENTS" exit 1 fi ``` 2. 进入目录，执行ESLint格式化 cd $ARGUMENTS npm run lint -- --fix 3. 输出格式化结果，统计修改的文件数量 echo "批量格式化完成，修改文件数量：$(find . -name "*.js" -o -name "*.ts" | xargs grep -l "/* eslint-disable */" | wc -l)" ``` ### 八、常见问题排查 配置和用法均已覆盖，最后盘点实际使用中的常见陷阱。 #### 问题1：技能无响应（自动/手动均无法触发） - **排查**：路径是否正确？`~/.claude/skills/explain-code/SKILL.md`文件是否存在？在Claude Code中输入`/`查看技能列表。 - **检查**：全局权限是否禁用了该技能？执行`/permissions list Skill`。 - **解决**：路径错误则重建；权限问题则用`/permissions allow Skill(explain-code)`放行。 #### 问题2：技能误触发（不该出现时出现） - **原因**：`description`中的关键词设置过于宽泛，导致AI任意场景都匹配。 - **解决**： 1. 精简`description`，明确触发条件。例如从“解释代码”改为“用户询问‘代码如何工作’时自动触发”。 2. 添加`disable-model-invocation: true`，彻底关闭自动触发，仅允许手动调用。 #### 问题3：参数$ARGUMENTS不生效 - **原因**：指令中未出现该占位符，或调用格式错误。 - **解决**：检查`SKILL.md`确保包含`$ARGUMENTS`且拼写正确。调用时参数紧跟技能名，如`/fix-issue 123`，避免有多余空格导致解析错误。 #### 问题4：技能加载不完整，部分指令未执行 - **原因**：`SKILL.md`文件总长度超过15000字符上限。 - **解决**： 1. **拆分**：将大技能拆分为多个小技能，组合使用。 2. **搬运**：将详细示例、参考文档移至`reference.md`或`examples.md`文件，按需加载。 3. **扩容**：设置环境变量临时或永久扩大字符上限。 ```bash # 临时 export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000 # 永久 echo "export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000" >> ~/.bashrc source ~/.bashrc ``` ### 九、总结 Skills体系的核心优势在于“可复用、可共享、可扩展”。你可以从简单的参考型技能起步（如注入代码规范），逐步迭代到参数传递、动态上下文和子任务隔离等高级玩法。 实操建议：从最烦人的高频重复操作入手——比如每次必做的代码审查或文件格式化。创建简单技能，感受配置规则，再逐步解锁高级功能。团队协作时，将项目规范封装为项目技能并提交Git仓库，确保全员同步更新，操作自然统一。 接下来，尝试把团队零散的Shell脚本、部署流程都迁移为Skills，亲身体验“一次配置，终身复用”的流畅感。更进阶的玩法是研究Skills与Plugins、Subagents的组合，搭建一套高度自动化的开发工作流。

来源：互联网