很多人用 Claude Code 的时候，会碰到两个烦心事。一个是每次都要重复说同样的话，比如告诉它用哪种代码规范。另一个是通用AI不太懂你项目的特殊情况。Claude 的 Skills 功能正好能解决这两个问题。

说白了，Skills 就是给 Claude 准备的说明书。你提前写好一份文件放在 Skills 目录里，告诉 Claude 碰到什么情况该怎么做。等真的遇到那种情况，它自己就会照着做，不用你每次都说一遍。

这篇文章从头开始讲，看完你会明白这几件事：

• Skills 怎么工作的
• SKILL.md 文件怎么写
• 技能文件放哪，优先级怎么排
• 怎么往技能里传参数
• 内置的几个技能怎么用
• 怎么把技能分享给别人

如果你刚开始用 Claude Code，可以先这样理解：Skills 就是给 Claude 定制的专项技能包。让它学会某一类知识或者工作流程，处理相关任务的时候就更专业。

打个比方。你雇了一个特别聪明的助理，但他对你的公司、项目、习惯都不了解。Skills 就是你给他准备的培训手册。告诉他你们团队用什么技术、代码怎么写、怎么部署。有了这个手册，助理马上就能上手，不用每次都从头解释。

没有 Skills 的时候，你会碰到这些麻烦。

每次开新会话都要重新告诉 Claude 用 TypeScript，遵守 Airbnb 规范。换一个项目，Claude 完全不知道这个项目的规矩。部署、审查、提交这些操作，要一步步手动提示。团队积累的经验只存在人脑子里，没法传给AI。

Skills 就是为解决这些问题做的。你把常用知识和流程写成配置文件，Claude 需要的时候自己加载用。

SKILL.md 是技能的核心文件，里面写指令和配置。可以理解成岗位说明书。

frontmatter 是 SKILL.md 顶部用三个短横线包起来的YAML配置区域，可以理解成档案封面。

斜杠命令就是用 /skill-name 这种方式调用技能，相当于快捷拨号。

自动触发是Claude自己根据情况判断要不要加载技能，相当于情景感应。

支持文件是技能目录里的额外文件，比如模板、脚本，可以理解成工具箱。

Claude Code 有几个容易搞混的概念。

CLAUDE.md 是项目级的持久记忆。Skills 是可复用的能力包，不只是记东西。

自定义命令是单个文件的斜杠命令。Skills 是命令的超集，支持目录结构，功能更多。

子代理是独立执行任务的AI实例。Skills 可以在子代理里跑，也可以单独跑。

插件是可分发扩展包。插件里面可以包含 Skills。

向后兼容要注意一下。Skills 和旧版自定义命令完全兼容。你在 .claude/commands/deploy.md 创建的命令，和在 .claude/skills/deploy/SKILL.md 创建的技能，效果一样，/deploy 命令都能用。已有的配置不用改。

了解背后的运行机制，能帮你写出更好用的技能。

Claude 启动的时候，会扫描已经安装的技能目录，把每个技能的名字和描述记下来。只有用户的问题符合某个技能的触发条件时，Claude 才会去读那个技能的 SKILL.md 文件，把内容加载进来。

如果指令里提到了别的文件，比如参考文档、示例模板，Claude 也会自己去读。如果提到要执行脚本，Claude 直接跑脚本拿结果，不会把脚本源码也加载进去。这种逐步加载的方式，让技能可以带很多参考内容，但不会一次占满整个对话窗口。

理论说够了，动手最重要。这一章我们从零开始，做一个能用的技能。

一个技能就是一个文件夹。最简单的形式只需要一个文件。

my-skill/ ├── SKILL.md # 必需，核心文件 ├── template.md # 可选，模板文件 ├── examples/ │ └── sample.md # 可选，示例 └── scripts/

└── helper.sh # 可选，脚本

SKILL.md 是唯一必需的文件。其他的看需要再加。

每个 SKILL.md 分成两部分。

最上面是两个短横线包起来的 frontmatter，用 YAML 格式，写技能的元信息。

--- 

然后下面是正文，写 Markdown 格式的指令。

当 Claude 调用这个技能的时候，就会按照正文里的指令做。

我们来做一个代码讲解技能，让 Claude 解释代码的时候总用类比和图示。

第一步，创建技能目录。个人技能放在 ~/.claude/skills/ 下面，对所有项目都有效。

mkdir -p ~/.claude/skills/explain-code

第二步，编写 SKILL.md。创建文件 ~/.claude/skills/explain-code/SKILL.md。

— name: explain-code 
description: 用类比和图示解释代码原理。当用户问这段代码是什么意思、这个函数怎么工作的时候自动触发。
 
解释代码的时候，必须包含下面四个部分。
 
   
     
     
 
      
生活类比：用日常例子打比方
 
      
ASCII 图示：用字符画结构或者流程
 
      
逐步解析：一行一行解释代码做了什么
 
      
常见误区：指出最容易搞错的地方
 
     
 
语气要通俗，适合初学者。

第三步，测试技能。技能做好以后，有两种方式触发。

自动触发：直接问 Claude 相关问题。比如在聊天里问这段 Promise 代码是什么意思。

手动触发：用斜杠命令。比如 /explain-code src/auth/login.ts

Claude 回答的时候，就会按照你的指令，必然包含类比和图示。

验证技能有没有加载成功，可以在 Claude Code 里问 What skills are available，看看你的技能在不在列表里。

放的位置不一样，作用范围也不一样。是只给自己用，还是整个项目用，还是团队一起用。

企业级，通过管理配置下发。所有组织成员都能用。适合公司统一规范和策略。

个人级，路径是 ~/.claude/skills/。你所有的项目都能用。适合个人习惯和通用工具。

项目级，路径是 .claude/skills/。只在当前项目里用。适合项目特定知识和团队协作。

插件内，路径是 /skills/。插件启用的地方就能用。适合随插件一起分发。

如果多个地方有同名的技能，优先级从高到低是：企业级高于个人级，个人级高于项目级。

插件里的技能用 plugin-name:skill-name 这种命名方式，不会和其他级别的冲突。

如果你的项目是 Monorepo 结构，Claude Code 会自动发现子目录里的技能。比如你在编辑 packages/frontend/ 里面的文件，Claude Code 会自动找 packages/frontend/.claude/skills/ 里的技能。

my-monorepo/ ├── .claude/skills/ # 根目录技能，所有子包都能用 │ └── deploy/ ├── packages/ │ ├── frontend/ │ │ └── .claude/skills/ # 前端专属技能 │ │ └── react-patterns/ │ └── backend/ │ └── .claude/skills/ # 后端专属技能 │ └── api-conventions/

用 –add-dir 参数添加额外目录的时候，这个目录下面的 .claude/skills/ 会被自动加载。这是 Skills 特有的规则，其他配置比如 subagents、commands 不会加载。

这个特性很适合共享技能库。

claude –add-dir /path/to/shared-skills-repo

而且支持热更新。在会话里改了这些技能文件，不用重启 Claude Code，修改马上生效。

Frontmatter 是控制技能行为的控制面板。掌握这些配置，才能真正用好 Skills。

name，不是必需的，默认用目录名。这是技能显示名，会生成 /name 斜杠命令。只能用小写字母、数字、连字符，最长64个字符。

description，推荐写。Claude 靠这个决定要不要自动加载。重要的关键词放前面，因为超过250个字符会被截断。

argument-hint，不是必需的。自动补全的时候显示的参数提示，比如 [filename] [format]。

disable-model-invocation，不是必需的，默认是 false。设为 true 的时候，只有你能手动触发，Claude 不会自动加载。

user-invocable，不是必需的，默认是 true。设为 false 的时候，从斜杠菜单里隐藏，只让 Claude 自己调用。

allowed-tools，不是必需的。这个技能激活的时候，Claude 可以不用问你直接用的工具列表。

model，不是必需的，继承会话的设置。这个技能激活的时候用的模型。

effort，不是必需的，继承会话的设置。努力级别，有 low、medium、high、max。

context，不是必需的，默认是内联。设为 fork 的时候，在隔离的子代理里运行。

agent，不是必需的。和 context: fork 配合，指定子代理类型。

hooks，不是必需的。技能生命周期钩子的配置。

paths，不是必需的。Glob 模式，限定技能只在特定文件类型时激活。

shell，不是必需的，默认是 bash。用于感叹号加反引号这种命令注入的 shell，可以选 powershell。

description 是整个 frontmatter 里最重要的字段。Claude 靠它判断什么时候该加载这个技能。

写好 description 有几个原则。最重要的触发关键词放最前面，因为超过250字符会被截断。要说明什么时候用，比如当用户问什么的时候使用。不要写得太宽泛，太宽泛会导致技能频繁触发，影响性能。

反面例子是帮助 React 开发，太模糊了。正面例子是 React 组件性能优化指导。当代码包含 useEffect、useMemo、useCallback，或者用户问组件卡顿、重复渲染问题的时候使用。

disable-model-invocation 和 user-invocable 这两个字段控制谁能触发技能，很多人搞混。

默认情况下，你能用斜杠调用，Claude 能自动调用，技能出现在斜杠菜单里。

如果设了 disable-model-invocation: true，你能用斜杠调用，Claude 不能自动调用，技能还出现在菜单里。

如果设了 user-invocable: false，你不能用斜杠调用，Claude 能自动调用，技能不在菜单里。

disable-model-invocation: true 适合有副作用的操作，比如部署、发消息，你不希望 Claude 自己执行。

user-invocable: false 适合背景知识型的技能，比如老系统的说明。Claude 应该知道，但这本身不是一个有意义的命令。

paths 可以让技能只在处理特定文件的时候激活，避免影响不相关的任务。

— name: react-patterns description: React **实践 paths: “/*.tsx,/*.jsx” —

这个技能只在处理 React 文件的时候，Claude 才会考虑加载。

effort 可以控制思考深度。可以为特定技能设不同的思考强度，在速度和质量之间找平衡。注意 max 级别只有 Claude Opus 4.6 能用。

— name: deep-review description: 深度代码审查 effort: max —

静态指令有时候不够用。你可能需要把用户输入的内容传给技能，或者注入实时的数据。Skills 提供了两种办法。

用户调用 /skill-name 的时候可以传参数，技能里面用变量引用。

\(ARGUMENTS 代表所有参数，合并成一个字符串。比如 /fix-bug 1234 传进来就是 1234。

\)ARGUMENTS[N] 代表第 N 个参数，从 0 开始数。\(ARGUMENTS[0] 就是第一个参数。

\)0、\(1、\)2 是 \(ARGUMENTS[N] 的简写。

\){CLAUDE_SESSION_ID} 是当前会话的ID，可以用来写日志或者给临时文件起名字。

${CLAUDE_SKILL_DIR} 是技能目录的绝对路径，引用技能自带的脚本时用。

看一个单参数的例子。

— name: fix-issue description: 修复 GitHub Issue 
disable-model-invocation: true
 
修复 GitHub Issue #$ARGUMENTS，按下面步骤做。
 
   
     
     
 
      
读 Issue 描述
 
      
分析根本原因
 
      
写修复代码
 
      
写测试
 
      
提交代码
 
     

执行 /fix-issue 42 的时候，Claude 收到的指令就变成了修复 GitHub Issue #42，按下面步骤做。

再看一个多参数的例子。

— name: migrate-component description: 把组件从一个框架迁移到另一个框架 — 
把 \(0 组件从 \)1 迁移到 $2。保留所有现有功能和测试，不要改行为。

执行 /migrate-component SearchBar React Vue 的时候，Claude 收到把 SearchBar 组件从 React 迁移到 Vue。

用感叹号加反引号这种写法，可以在技能发给 Claude 之前，先执行一段 Shell 命令，把输出注入到技能内容里。

重要区别：这不是 Claude 执行命令，而是 Claude Code 在发技能给 Claude 之前做预处理。Claude 只看到最后输出的文字，不知道有命令被执行过。

— name: pr-summary description: 总结当前 Pull Request 的变更 context: fork 
allowed-tools: Bash(gh *)
 
PR 上下文
 
   
     
     
 
      
变更差异：!gh pr diff
 
      
PR 评论：!gh pr view --comments
 
      
修改文件：!gh pr diff --name-only
 
     
 
你的任务
 
请总结这个 PR 的主要变更、影响范围和风险。

如果是多行命令，可以用三个反引号加感叹号的代码块。

 运行环境 
”`! node –version npm –version git log –oneline -5

管理员可以在设置里加 disableSkillShellExecution 为 true 来禁用这个功能，适合安全要求高的环境。被禁用的时候，注入的地方会替换成一行说明文字。

单个 SKILL.md 适合简单任务，但复杂功能需要多个文件配合。

有几个情况，单文件会遇到麻烦。详细的API文档、参考规范如果都塞进一个文件，每次触发技能都全量加载，占很多 context。代码审查报告、技术文档有固定格式，需要模板文件。生成图表、处理数据这些任务，需要 Python 或 Shell 脚本。

解决办法是把这些内容拆到独立文件里，在 SKILL.md 里引用，让 Claude 按需加载。

code-review/ ├── SKILL.md # 核心指令，控制在500行以内 ├── checklist.md # 详细清单，按需加载 ├── templates/ │ └── report.md # 报告模板 ├── examples/ │ ├── good-example.ts # 好例子 │ └── bad-example.ts # 坏例子 └── scripts/ 
└── complexity.py # 计算复杂度的脚本

在 SKILL.md 里要明确告诉 Claude 每个文件是干什么的，什么时候加载。

--- 

好的做法是把 SKILL.md 控制在500行以内，详细的参考资料放到独立文件里。Claude 真正需要的时候才会加载它们，节省 context 空间。

下面是一个完整的例子，做一个能生成 HTML 图表的技能。

目录结构：

codebase-visualizer/ ├── SKILL.md └── scripts/ 
└── visualize.py

SKILL.md 的内容：

--- 

 探索新代码库、了解项目结构的时候用。 

这会在当前目录生成 codebase-map.html 并在浏览器里打开。

 注意 \){CLAUDE_SKILL_DIR} 的用法。不管当前工作目录在哪，这个变量始终指向技能文件所在的目录，能保证脚本路径正确。 
第七章 高级用法
 
掌握基础之后，这一章介绍两个让 Skills 更强大的高级功能：在独立子代理里运行技能，以及精细控制工具权限。
 
7.1 在子代理里运行技能
 
context: fork 让技能在隔离的子环境里执行，不影响主对话。就像派一个特种兵去完成特定任务，做完回来汇报结果。
 
什么时候用 context: fork？任务独立性强，需要大量探索，不应该干扰主对话。任务需要只读的工具集。PR分析、代码库扫描这些不需要对话历史的任务。
 
看一个深度研究技能的例子。
 
”`yaml
 
name: deep-research description: 对指定主题深入研究，分析代码库 context: fork
 
agent: Explore
 
深入研究：$ARGUMENTS
 
   
     
     
 
      
用 Glob 和 Grep 找到相关文件
 
      
读代码并分析
 
      
总结发现，附上具体文件引用
 
     

可用的内置代理类型有几种。

Explore 代理只用只读工具，适合代码库研究、写文档。

Plan 代理用读取和规划工具，适合任务拆解、架构设计。

general-purpose 代理用全套工具，适合通用任务。

自定义代理由 .claude/agents/ 定义，适合项目特定的专属代理。

allowed-tools 可以限制工具。在技能激活期间，可以限制 Claude 只用某些工具，这对只读技能或者安全敏感的操作很有用。

— name: safe-reader description: 只读模式，不改任何文件 allowed-tools: Read Grep Glob — 
在只读模式下分析代码…

多个工具可以用空格隔开，也可以用 YAML 列表的写法。

allowed-tools: 
   
     
     
 
      
Read
 
      
Grep
 
      
Bash(gh *)
 
      
Bash(python *)
 
     

除了在单个技能里控制，还可以在权限配置里全局管理哪些技能 Claude 能调用。在 /permissions 里可以禁用所有技能，或者只允许某些技能，或者禁止某些技能。

在技能内容里任意位置写上 ultrathink 这个词，就能激活 Claude 的深度思考模式，适合需要复杂推理的技能。

— name: architecture-review description: 深度架构审查 effort: max — 
对这个系统做架构审查。ultrathink
 
分析可扩展性、安全性、可维护性、性能。

Claude Code 自带几个高质量的内置技能，可以直接用，不用配置。

/batch 后面跟指令。功能是并行大规模重构，自动拆任务，为每个子任务建独立分支并行处理。比如把 src 下所有组件从类组件迁移到函数组件。

/claude-api 加载 Claude API 参考文档，支持 Python、TS、Go 等8种语言。代码里 import anthropic 的时候会自动触发。

/debug 后面跟描述。启用 debug 日志，分析当前会话的调试信息。比如问为什么这个工具调用总是失败。

/loop 后面跟间隔和提示。按间隔重复执行提示，适合监控类任务。比如每5分钟检查一次部署有没有完成。

/simplify 后面跟焦点。并行启动三个代理审查最近改的代码，发现并修问题。比如专注于内存效率。

/batch 是内置技能里最厉害的。它能把大型重构任务自动化。

工作流程是这样的。Claude 先研究代码库，搞明白任务范围。然后把工作拆成5到30个独立的小任务。接着把计划展示给你，等你确认。确认之后，为每个小任务建独立的 git worktree。然后并行启动多个后台代理，各自处理一个小任务。每个代理做三件事：实现、测试、提交、开 Pull Request。

使用 /batch 需要 git 仓库环境。适合大型、相对独立的批量修改任务，不适合需要严格按顺序来的变更。

好的技能应该分享出去，不只自己用。

第一种，用 Git 版本控制做团队协作。把项目级技能提交到代码仓库，团队成员 clone 下来就能用。

git add .claude/skills/ git commit -m “add: code-review and deploy skills” git push

所有团队成员的 Claude Code 都会自动加载这些技能，不用单独配置。

第二种，打包成插件。如果你的技能还有其他配置配套，比如 MCP 服务器、钩子，可以打包成插件。

my-plugin/ ├── claude-plugin.json # 插件清单 ├── skills/ │ ├── deploy/ │ └── review/ └── hooks/ 
└── post-commit.sh

第三种，企业级管理配置。企业版用户，管理员可以通过管理配置文件给所有成员统一下发技能。新成员入职就自动有团队的技能集。

Anthropic 已经把 Skills 发布成开放标准了，网址是 agentskills.io。这意味着同一个 SKILL.md 可以在 Claude Code 和其他支持这个标准的 AI 工具里用。社区可以贡献和分享通用的技能包。以后更多工具支持这个标准，你写的技能也不会过时。

技能不按预期工作？这一章给一些排查方法和经验总结。

技能没有触发。先确认技能文件在不在，路径和文件名对不对，注意 SKILL.md 大小写不能错。然后在 Claude Code 里问 What skills are available，看技能在不在列表里。检查 description 有没有包含用户可能用的关键词。试试手动触发 /skill-name，确认技能语法没错。检查是不是设了 disable-model-invocation: true，如果设了，Claude 不会自动触发。

技能触发太频繁。让 description 更具体，减少容易误触的关键词。或者设 disable-model-invocation: true，改成手动触发。也可以用 paths 字段限制文件类型。

description 被截断。症状是技能名字在列表里，但关键的触发词丢了，导致 Claude 匹配不上。解决办法是把最重要的触发关键词挪到 description 最前面。每个技能的 description 严格控制在250字符以内，这是硬性限制。如果需要增加总预算，可以设环境变量 export SLASH_COMMAND_TOOL_CHAR_BUDGET=16000。

Shell 注入命令失败。先在终端手动跑一下命令，确认命令本身是对的。检查技能目录里的脚本文件权限，用 chmod +x scripts/xxx.sh 加上执行权限。确认 disableSkillShellExecution 没有被管理员禁用。

文件大小方面，SKILL.md 控制在500行以内，不要把所有内容都堆在一个文件里。

description 要把关键词放前面，具体描述使用场景，少于250字符。不要写模糊的描述，比如帮助开发。

有副作用的操作要设 disable-model-invocation: true，不要让 Claude 自己触发部署、发消息这些操作。

工具权限要用 allowed-tools 给最小权限，不要给只读技能分配写的权限。

脚本路径要用 ${CLAUDE_SKILL_DIR} 引用技能自带的脚本，不要用绝对路径。

技能范围要一个技能只做一件事，不要把不相关的功能塞在一起。

版本控制要把项目技能提交到 git，不要让技能只存在自己电脑上。

这是一个验证过的技能开发流程。

先明确需求，写下你想让 Claude 做什么，以及什么时候触发。然后从简单开始，先写最小可用的版本，只有 name、description 和核心指令。接着测试触发，自动触发和手动触发都试一遍。然后收集反馈，实际用几天，看看哪里不符合预期。再迭代优化，根据反馈调整 description 和指令细节。需要的时候再加支持文件，比如模板、示例、脚本，不要过度设计。最后，好的技能提交到代码库，和团队分享。

--- 

官方文档是 Claude Code Skills Documentation。开放标准可以看 agentskills.io。

本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！

链接: https://fly63.com/article/detial/13606