Skills：给 Claude 一本
随用随取的操作手册

要让这位新同事干好活，你会给他准备几样东西。Claude Code 里正好各有对应：

一句话定义

一个 Skill 就是一个文件夹，里面至少有一个 SKILL.md。文件开头几行告诉 Claude"我是谁、什么时候该用我"，后面写具体怎么做。文件夹里还可以放模板、参考资料和脚本。

weekly-report/
├── SKILL.md            # 必需：说明书本体
├── templates/
│   └── report.md       # 可选：周报模板
└── scripts/
    └── stats.py        # 可选：统计改动量的脚本

对照表

可以把它看成两部分：

• 配置区（两条 --- 之间）：告诉 Claude Code 什么时候用、怎么用这个 skill。
• 正文：告诉 Claude 具体怎么做。就是普通的 Markdown，像写给同事的说明一样写就行。

重名了听谁的？

排在前面的优先。比如你的个人目录和项目目录里各有一个 weekly-report，生效的是个人目录里那个。你自己写的 skill 也会覆盖 Claude Code 内置的同名 skill。

插件里的 skill 不参与抢名字，调用时永远带插件名前缀，比如 /my-plugin:weekly-report，所以不会和别人的冲突。

动手算一笔账

拖动滑块设置"装了多少个 skill"，再依次点下面 4 个步骤，看上下文怎么增长。对照组是"把所有手册都写进 CLAUDE.md"。

数字是为了说明量级的示意值，实际大小取决于你写了多少内容。

试试这两个开关

先站在 Claude 的角度看看。启动后，它手里关于 skill 的信息大致就是下面这么一份清单：

用户说"帮我汇总一下这周干了啥"时，Claude 只能拿这句话去和每行简介比对。简介写得越具体、越贴近用户的原话，就越容易被选中。

二选一：哪个更好？

写法五要点

1. 先写做什么，再写什么时候用。例如"根据 git 提交生成周报。当用户提到周报……时使用。"
2. 放进用户真会说的词，中英文都放：周报、本周总结、weekly report。
3. 具体胜过笼统。点名文件类型和场景：".xlsx 表格"比"文档"好。
4. 一个 skill 只做一件事。"PDF 表单填写"比"文档处理"更容易被准确触发。
5. 重要的放前面。description 和 when_to_use 合计超过 1,536 个字符的部分会被截掉。

给你的 description 做个体检

这个体检只是按上面五个要点做的简单规则比对，方便你自查，不代表 Claude 实际的判断方式。

终端画面为教学示意，与真实 Claude Code 的界面细节可能略有不同，但流程和原理一致。

参数替换游乐场

选一种写法，在命令行里改改参数，下方或旁边会实时显示 Claude 最终收到的内容。

动态上下文：!`命令`

在正文里写 !`命令`，Claude Code 会在把 skill 交给 Claude 之前先执行命令，再把输出原地替换进去。Claude 从头到尾看不到命令本身，只看到结果。

Skill 加载后会待多久？

很多人以为 skill 用完就"退出"了。其实它的内容会一直留在这次对话里，但它授予的权限只持续一轮：

• 写成"长期守则"，而不是"一次性步骤"。第 2 轮你说"再短一点"时，Claude 仍然会遵守 skill 里的规则。
• 权限在你发下一条消息时清除。想再次免确认，就重新调用一次 skill。
• 对话自动压缩时，每个 skill 只保留前 5,000 token，所有 skill 合计最多 25,000。调用过很多 skill 时，较早的可能整个被丢掉，需要时再调用一次。最重要的规则要写在前面。

在子代理里运行：context: fork

---
name: deep-research
description: 深入调研代码库中的某个问题
context: fork
agent: Explore
---

调研 $ARGUMENTS：
1. 找到相关文件
2. 阅读并分析
3. 只汇报结论和关键文件路径

skill 会交给一个拥有独立上下文的子代理去执行。它翻了几百个文件，主对话里也只会多出最后那份结论。默认在后台运行，设置 background: false 则等它跑完再继续。注意：在后台跑的 fork 型 skill 改的文件不进检查点，/rewind 撤不回（第 3 课），要用 git 回退。

只在特定文件上生效：paths

---
name: react-conventions
description: 本项目 React/TypeScript 组件的写法约定
paths: "src/**/*.tsx"
---

加了 paths 后，只有在处理匹配的文件时，Claude 才会考虑自动加载这个 skill。这样可以减少误触发。

全部 frontmatter 字段

如果要把 skill 上传到 claude.ai 或通过 API 使用，只支持 name、description、license、compatibility、metadata、allowed-tools 这几个字段。

安装前检查清单

想关掉你自己、项目和插件里 skill 的命令注入，可以在 settings.json 里加上：

{
  "disableSkillShellExecution": true
}

也可以用权限规则禁止某个 skill，例如 "deny": ["Skill(deploy *)"]。

常见问题