掌握这 5 个 Skills 高级玩法，Claude Code 效率翻倍少走 90% 弯路

好的，身为在AI开发工具领域深耕多年的博主，我这就把这篇关于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`，不要写成`/fix-issue 123`（虽然例子没写错，但要注意不要有多余空格导致`/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组合起来用，搭一整套更自动化的开发工作流。