Claude Code Skills 怎么用?2026 自定义技能包实测教程

Claude Code Skills 怎么用?一篇讲透 SKILL.md 与 .claude/skills 自动加载

主关键词:claude code skills 怎么用。 先给结论(TL;DR):Skills 就是把你反复粘贴给 Claude 的那段"操作流程/检查清单/风格规范",抽成一个 SKILL.md 文件丢进 .claude/skills/ 目录,Claude 在相关时自动加载、你也能用 /技能名 手动触发。从 Claude Code v2.1.157(2026-05-29)起,.claude/skills 里的技能免市场、免安装、开会话即自动加载;claude plugin init 一键生成脚手架。我把自己日常在 btcover.com 跑的 3 个工作流(发推回复、内容改写、视频切片)全封装成了 Skill,这篇就用真实目录 + 触发调试日志带你走一遍。

版本说明:本文涉及的版本号与功能均来自 Anthropic 官方 changelog 与文档(见文末来源),写于 2026-05-30。Claude Code 迭代极快,具体行为以官方最新文档为准。

Skill 是什么?它到底解决什么问题

在没有 Skill 之前,我的痛点很具体:每次让 Claude 帮我把一篇英文文章改写成 btcover 风格的中文稿,我都要把同一段约 600 字的"改写规范"(语气、字数、SEO 结构、不许抄句子)粘进对话框。粘多了会发现两个问题:

CLAUDE.md 越塞越胖。我一度把这套规范写进 CLAUDE.md,结果它每个会话都全量加载,哪怕我这次只是改个 bug,也得为这几百 token 买单。
流程会漂移。手动粘贴时偶尔漏一段,产出质量就不稳定。

Skill 正好治这个病。官方文档的原话是:当你"一遍遍粘贴同样的指令/清单/多步流程",或者 CLAUDE.md 里某一段已经从"事实"长成了"流程",就该把它做成 Skill。关键区别在于——Skill 的正文只在被用到时才加载,长长的参考资料平时几乎不占 token。

还有一个 2026 的大背景值得知道:Skill 用的是 Agent Skills 开放标准(agentskills.io)。Anthropic 在 2025-12-18 把它开源成标准,如今 Codex CLI、Cursor、Gemini CLI 等几十个工具都能读同一套 SKILL.md。也就是说你写的技能不只服务 Claude Code,跨工具复用是可能的(具体兼容范围以各工具文档为准)。想横向对比这几个工具,可以看我的四大 AI 编程 Agent 横评。

顺带一提:官方已经把"自定义命令"并进了 Skill。.claude/commands/deploy.md 和 .claude/skills/deploy/SKILL.md 都会生成 /deploy,行为一致。旧的 commands/ 文件继续可用,但新写一律推荐用 Skill,因为它能带附属文件、能让 Claude 自动触发。

SKILL.md 怎么写:目录结构 + 最小骨架

一个 Skill 就是一个目录,里面必须有 SKILL.md 作为入口,其余文件都是可选的:

my-skill/
├── SKILL.md          # 主指令(必需):YAML frontmatter + Markdown 正文
├── reference.md      # 详细参考(可选,用到才加载)
├── examples.md       # 示例输出(可选)
└── scripts/
    └── helper.py     # 可执行脚本(被运行,不进上下文)

SKILL.md 由两部分组成:两条 --- 之间的 YAML frontmatter(告诉 Claude 何时用这个技能),和后面的 Markdown 正文(技能跑起来时 Claude 遵循的指令)。最小可用骨架长这样:

---
name: summarize-changes
description: 总结未提交的改动并标出风险。当用户问"我改了什么""帮我写 commit message""帮我 review diff"时使用。
---

## 当前改动

!`git diff HEAD`

## 指令

把上面的改动用 2-3 个要点总结,然后列出你注意到的风险(缺少错误处理、硬编码、需要更新的测试等)。如果 diff 为空,就说没有未提交的改动。

这里有两个要点会决定技能好不好用:

description 是触发器。Claude 靠它判断"这次该不该自动加载这个技能",所以一定要写进用户真会说出口的关键词。官方提示:description 加上可选的 when_to_use 合并后会被截断到 1536 字符,把最关键的用途写在最前面。
!`git diff HEAD` 是动态上下文注入。这一行不是给 Claude 看的命令,而是 Claude Code 在把技能内容发给模型之前先执行,用命令输出替换掉这一行。所以模型拿到的是你工作区真实的 diff,而不是它猜的。多行命令用 ```! 围栏块。

name 字段其实是可选的(默认取目录名),真正决定你输入什么命令的是目录名:.claude/skills/deploy-staging/SKILL.md → /deploy-staging。name 只影响技能列表里显示的标签。

Frontmatter 常用字段速查(实测最常用的几个)

字段	作用
`description`	触发文本,Claude 据此自动加载(强烈建议写)
`disable-model-invocation: true`	只允许你手动 `/触发`,禁止 Claude 自动跑(用于 `/deploy`、`/commit` 等有副作用的)
`user-invocable: false`	只允许 Claude 自动用,从 `/` 菜单隐藏(用于纯背景知识)
`allowed-tools`	技能激活时免确认的工具,如 `Bash(git add ) Bash(git commit )`
`disallowed-tools`	技能激活时从工具池移除的工具(v2.1.152 起);如后台循环里禁掉 `AskUserQuestion`
`context: fork`	在隔离的子代理上下文里跑这个技能
`agent`	配合 `context: fork`,指定用哪个子代理(`Explore`/`Plan`/自定义)
`argument-hint` / `arguments`	自动补全提示与命名参数

allowed-tools 和 disallowed-tools 这对组合是我后来踩坑才理解的:allowed-tools 是"免确认"(不限制可用范围,其他工具仍可调),disallowed-tools 才是真正"从池子里拿掉"。disallowed-tools 的限制会在你发下一条消息时清除。

.claude/skills 自动加载:免市场、免安装

这是 2026-05 最值得说的更新。v2.1.157(2026-05-29)的 changelog 原话是:"Plugins in .claude/skills directories are now automatically loaded, no marketplace required",同时新增 claude plugin init <name> 来在 .claude/skills 里生成脚手架。

技能存哪儿决定了谁能用:

位置	路径	作用范围
个人	`~/.claude/skills/<名>/SKILL.md`	你所有项目
项目	`.claude/skills/<名>/SKILL.md`	仅当前项目(可提交进 Git 共享)
插件	`<plugin>/skills/<名>/SKILL.md`	启用该插件处,命名空间 `plugin:skill`

我实测的工作流是:在项目根的 .claude/skills/ 里 mkdir 一个目录、写好 SKILL.md,开会话就有了,不需要任何 install。Claude Code 还有 Live change detection——你在会话中改 SKILL.md 文本,改完即时生效,不用重启;但如果是新建一个会话开始时还不存在的顶层 skills 目录,则需要重启 Claude Code 才能被监听到。

如果你想让一个技能文件夹同时携带 hooks、MCP、子代理,就给它加一个 .claude-plugin/plugin.json,它会作为名为 <名>@skills-dir 的"就地插件"加载——同样免市场。脚手架一行命令搞定:

# 在 ~/.claude/skills/ 下生成 my-helper,下次会话自动以 my-helper@skills-dir 加载
claude plugin init my-helper

# 顺便建好 skills 和 hooks 目录
claude plugin init my-helper --with skills hooks

注意一个坑(官方明确警告):项目作用域的 @skills-dir 插件只从你启动 Claude 的那个目录的 .claude/skills/ 加载,不会像普通技能那样向上回溯到仓库根。所以要么从仓库根启动,要么切目录后跑 /reload-plugins。

触发词与渐进式加载:Claude 怎么决定用哪个技能

理解加载机制能帮你写出"该触发时触发、不该触发时安静"的技能。它是三级渐进式的:

平时:只有技能的名字 + description 进上下文,正文不进。这就是为什么 description 关键词那么重要——它是 Claude 唯一的判断依据。
被触发时(你打 /名 或 Claude 判断相关):整段 SKILL.md 正文作为一条消息进上下文,并在整个会话剩余时间保留。
附属文件(reference.md、scripts/):只有当正文里引用、且 Claude 真的需要时才读。

第 2 点有个容易忽略的副作用:技能正文一旦加载就常驻,每一行都是反复计费的 token。所以官方建议正文保持精简(<500 行),把大块参考挪到 reference.md。我自己的 reply-tweet 技能就是把"数据洞察"那一长段拆进了附属文件。

disable-model-invocation 直接改变加载行为:设为 true 后,description 平时根本不进上下文,只有你手动 /触发 时才整段加载。这正是给 /deploy 这类有副作用命令用的——你不想 Claude 看代码"差不多了"就自己去部署。

想把技能进一步升级成多智能体协作?可以把 Skill 用 context: fork 丢进子代理跑,或者反过来让自定义子代理预加载技能,这块我在 Claude Code 多智能体与 Agent Teams 里讲得更细。Skill 之外的 MCP、hooks 等扩展机制,可以先看 Claude Code 基础教程打底。

实测:把我自己的 3 个工作流封装成 Skill

下面是我在 btcover_wp 项目里真实跑着的几个技能(目录我做了脱敏,逻辑是真的)。我的 .claude/skills/ 目前长这样:

.claude/skills/
├── rewrite/          # 抓 URL → 改写成 btcover 原创 → 发布
│   ├── SKILL.md
│   └── references/style-guide.md
├── reply-tweet/      # 单条推文深度回复 / 扫 KOL 时间线找热帖
│   ├── SKILL.md
│   └── references/data-insights.md
└── video-clip/       # YouTube 转录 → 切 2-5 分钟双语字幕短视频
    ├── SKILL.md
    └── scripts/burn_subs.sh

工作流 1:内容改写(rewrite)。 触发设计是关键。我把 description 写成"当用户分享任何 URL(x.com / twitter.com / 网页文章链接)时触发",于是我直接往对话框里丢一条推特链接,Claude 就自动加载了它,不用我打命令。正文里我把"改写规范"压到 60 行内,把详细的语气/SEO 示例挪进了 references/style-guide.md,用一行 参考 [style-guide.md](references/style-guide.md) 链过去。

工作流 2:推文回复(reply-tweet)。 这个技能有两种模式(单链接深度回复 / --trending 扫时间线),我用 argument-hint 做了补全提示。这里踩过一个真实的坑:它最初触发过头——我只是提到"X 上有人说……",它就把整个回复流程拉起来了。解决办法就是把 description 写得更具体(强调必须是"推文 URL 或明确说'回复推文/热门帖子'"),触发立刻精准了。这印证了官方那条排错建议:技能触发太频繁 → 把 description 写更具体。

工作流 3:视频切片(video-clip)。 它带一个 scripts/burn_subs.sh(用 ffmpeg 烧双语字幕)。脚本路径我用 ${CLAUDE_SKILL_DIR}/scripts/burn_subs.sh 引用,这样无论技能装在个人级还是项目级都能解析对。把脚本放进 Skill 的好处是:Claude 负责编排(选片段、生成字幕),重活交给脚本,token 消耗反而低。

我把 video-clip 里那套"ASS 双语字幕、两步法剪辑"的踩坑经验也写进了技能正文,免得每次 Claude 重新发明轮子——这正是 Skill 替代反复粘贴的价值。

实测成本对比(示意,以你环境为准)

下面这组是我用同一篇英文文章做"改写发布"任务,对比"每次手动粘贴 600 字规范"和"封装成 rewrite 技能"的差异。数字为实测示意,会因模型版本(我用的是 v2.1.158 默认的 Opus 4.8)、文章长度、网络而变化:

维度	手动粘贴规范	封装成 Skill
每次额外输入 token(规范本身)	~900 tokens 每次	0(不触发时不加载)
我的操作步骤	复制 → 粘贴 → 描述任务	丢一条 URL
产出一致性	偶尔漏段落	稳定
单篇折合人民币(粗估)	略高、且每次都付	略低、按需付

核心收益不是省那点钱,而是操作从"三步粘贴"变成"扔个链接",以及产出不再漂移。

调试与踩坑:技能不触发 / 触发过头 / description 被截断

这几个是我和官方排错清单里都验证过的高频问题:

技能不触发:先问 Claude 一句 What skills are available?(或中文"有哪些技能可用?")确认它在列表里;在 → 多半是 description 关键词没覆盖你的说法,补关键词或换种说法触发;还不行就直接 /技能名 手动触发。
技能触发过头:把 description 写更具体,或加 disable-model-invocation: true 改成纯手动。
description 被截断:技能多了之后,description 会被压缩进一个按模型上下文窗口 1% 计算的预算里,关键词可能被砍掉。跑 /doctor 能看预算是否溢出、哪些技能受影响。可以把不常用的技能在 skillOverrides 里设成 "name-only" 腾预算,或调 skillListingBudgetFraction。
改了技能没生效:SKILL.md 文本是即时生效的;但插件型技能的 hooks/、.mcp.json、agents/ 改动要 /reload-plugins。需要会话中重扫技能目录,可用 /reload-skills(v2.1.152 起);SessionStart hook 也能返回 reloadSkills: true 让新装技能中途可用。
新建目录没被监听:开会话时还不存在的顶层 skills 目录,得重启 Claude Code。

中文场景额外提醒两点:(1)大陆可用性——Skill 本身是本地文件机制,跟网络无关;只要你的 Claude Code 能登录使用,技能就能跑。如果你走的是国产模型接入(把 Claude Code 接到 GLM、Qwen3-Coder、kimicc 等),Skill 一样生效,接入方法见国产模型接入 Claude Code。(2)中文触发词——description 里中英文关键词都写上,我实测"回复推文""热门帖子"这种中文短语作为触发词完全可行,反而比纯英文更贴合我的实际说话方式。

结论:什么时候该写 Skill

一句话选型:只要你发现自己在对话里第二次粘贴同一段流程,就该把它做成 Skill。 是事实/知识就考虑 user-invocable: false 的背景型;是有副作用的操作(部署、提交、发消息)就加 disable-model-invocation: true 做纯手动型;是日常自动化(像我这套发推/改写/切片)就靠 description 让它自动触发。配合 v2.1.157 的免市场自动加载,从"想到"到"用上"基本就是 mkdir + 写 SKILL.md + 开会话三步。

想系统学习 Claude Code、Codex、Cursor 这套现代 AI 编程工作流(含 Skills、子代理、国产模型接入的完整实操)?点此了解并立即订阅 →

FAQ

Q1:SKILL.md 怎么写最容易触发成功? 把 description 写成"做什么 + 何时用",并塞进用户真会说出口的关键词(中英文都加)。Claude 平时只看得到 description,看不到正文,所以触发全靠它。触发过头就写更具体,或加 disable-model-invocation: true。

Q2:.claude/skills 和插件、.claude/commands 有什么区别? .claude/skills/<名>/SKILL.md 是普通技能,免市场自动加载;给文件夹加 .claude-plugin/plugin.json 它就变成 <名>@skills-dir 就地插件,能携带 hooks/MCP/子代理;.claude/commands/*.md 是被并入 Skill 体系的旧式命令,仍可用但功能少。三者都会生成 /命令。

Q3:改完技能要不要重启 Claude Code? SKILL.md 文本改动即时生效(Live change detection)。插件型技能的 hooks/、.mcp.json、agents/ 改动需 /reload-plugins。会话中想重扫技能目录用 /reload-skills。只有"新建一个会话开始时不存在的顶层 skills 目录"才需要重启。

Q4:Skill 能跨工具用吗?用国产模型还能用 Skill 吗? Skill 遵循 Agent Skills 开放标准(agentskills.io,2025-12-18 开源),理论上 Codex CLI、Cursor、Gemini CLI 等也读同一套 SKILL.md,跨工具复用可期(具体兼容以各工具文档为准)。把 Claude Code 接到 GLM、Qwen3-Coder 等国产模型时,Skill 是本地文件机制,照常生效。

来源:Claude Code 官方文档 · Skills、Claude Code 官方文档 · Plugins Reference、Claude Code CHANGELOG(v2.1.139–v2.1.158)、Agent Skills 开放标准规范 · agentskills.io。版本与功能以官方最新为准。