身为在AI开发工具领域深耕多年的博主，下面将这篇关于Claude Code Skills的教程，用更贴近实战、更具可读性的方式重新梳理。直接开始，看看如何把“一次配置，终身复用”的玩法彻底掌握。

Claude Code Skills 使用教程

您可能已经遇到过这样的场景：每次使用Claude Code，都要将几万字的长篇审查清单从头输入一遍；团队里十位开发者有十种不同的部署脚本，彼此难以理解。Skills正是为解决这类问题而设计——它将高频操作、团队规范、专项任务打包成一个可随时调用的“技能包”。无论是通过/技能名手动触发，还是根据上下文自动匹配，都相当便捷。简单来说：一次配置，终身复用。 下面从基础概念、上手实操、高级玩法到问题排查，结合完整的代码示例，将Skills这套体系彻底讲透。

一、Skills 核心概念与价值

上手之前，先明确Skills的定位，避免与Claude Code中的其他功能（如Subagents、Plugins）混淆。

• 核心定义：Skills是一种轻量级扩展组件，专门封装可复用的指令集、工作流或领域知识。可通过/技能名手动调用，也能根据当前对话场景自动触发。
• 核心价值：省去重复输入的麻烦，团队规范可统一共享，复杂工作流一键运行。
• 与其他功能区别：Subagents相当于独立子任务环境，Plugins是功能更齐全的插件包，而Skills是最小的可复用单元。Skills可单独使用，也能组合到插件或子任务中。

关键之处：Skills完全兼容老版本的.claude/commands/目录。之前编写的自定义命令可直接迁移，还能享受更高级的参数传递、上下文隔离等能力。它遵循Agent Skills开放标准，未来可能跨工具复用。

二、快速上手：创建并使用第一个技能

以“代码可视化解释”技能（explain-code）为例，仅需三步，就能从零到一运行起来。

第一步：创建技能目录

Skills有固定的目录结构。目录位置决定技能的“管辖范围”——是只给当前项目使用，还是所有项目都能用。

# 创建个人全局技能目录（所有项目均可调用）
mkdir -p ~/.claude/skills/explain-code

# 若只想当前项目使用，执行以下命令
# mkdir -p .claude/skills/explain-code

第二步：编写 SKILL.md（核心文件）

每个技能必须有SKILL.md文件，这是它的“大脑”。结构分为两部分：开头的YAML元数据（推荐但非必须），以及后面的Markdown执行指令（必须）。 创建并编辑文件：

cd ~/.claude/skills/explain-code
vim SKILL.md

写入以下内容：

---
# 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图表：

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，在指令中调用该脚本：

---
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强烈推荐，因为它们决定技能的调用方式和自动触发时机。

---
# 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（调试）
---

一个常用配置组合——高危操作技能，如部署到生产环境：

---
name: deploy-prod
description: 部署应用到生产环境（高危操作）
disable-model-invocation: true    # 禁止AI自动触发
allowed-tools: Bash,gh            # 只允许使用Bash和GitHub CLI
argument-hint: "[branch]"         # 需传入部署分支
---

4.2 Markdown 执行指令（必需）

这部分是技能的“灵魂”，定义具体执行内容。根据用途，大致分为两种类型：

• 参考型技能：用于注入项目规范、风格指南等背景知识。无需手动调用，AI会自动参考并遵守。

  ---
  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，并返回具体错误信息

• 任务型技能：用于定义分步执行的复杂工作流，适合手动调用，如代码审查、部署。

  ---
  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）。

---
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）。

---
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）。

---
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脚本。 示例如下（“代码库可视化”技能）：

---
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脚本（简化版）如下：

# ~/.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字段限制技能能使用的工具。遵循“最小权限”原则——只赋予必要权限，避免越权。

---
# 只读技能
name: safe-reader
description: 只读查看文件内容，禁止任何修改操作
allowed-tools: Read,Grep,Glob # 没有修改或执行权限
---

---
# 部署技能
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

---
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

---
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

---
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认为多数场景都匹配。
  
解决：
    

      
精简description，将触发条件写具体。例如从“解释代码”改为“用户询问‘代码如何工作’时自动触发”。
      
添加disable-model-invocation: true，彻底关闭自动触发，仅允许手动调用。
    
  


问题3：参数$ARGUMENTS不生效


  
原因：指令中未使用该占位符，或调用传参格式有误。
  
解决：检查SKILL.md，确认有$ARGUMENTS且拼写正确。调用时参数要紧跟技能名，例如/fix-issue 123，注意不要有多余空格导致/fix-issue和123被分开解析。


问题4：技能加载不全，部分指令未执行


  
原因：SKILL.md文件总长度超过15000字符上限。
  
解决：
    

      
拆分：将大技能拆分为多个小技能，组合使用。
      
搬运：将详细的示例、参考文档移到reference.md或examples.md文件中，实现按需加载。
      
扩容：设置环境变量，临时或永久扩大字符上限。
        
# 临时
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组合使用，搭建一套更自动化的开发工作流。