1. 为什么你的 Claude Code 每次都要重新贴一遍操作手册如果你用 Claude Code 做过稍微复杂一点的项目大概率经历过这个循环新开一个会话先把部署步骤贴进去再开一个会话又把提交规范贴一遍换个项目还得把某个框架的 API 约定重新喂一遍。贴到第三遍的时候你会开始怀疑自己到底是在用 AI 提效还是在给 AI 当人肉剪贴板。LLM Skill 这套机制就是冲着这个痛点来的。简单说Skill 是把一份操作手册变成一个带 YAML 头的 Markdown 文件放在约定目录里Claude 在需要的时候自己把它读进来。它和 CLAUDE.md 最大的区别在于加载时机CLAUDE.md 是每次会话一开始就全文塞进上下文而 Skill 的正文平时不占上下文只有 Claude 判断该用的时候才展开。这意味着你可以堆一堆长篇参考材料平时不花钱用的时候才花。这套机制适合谁三类人最该上手一是手里有固定工作流的开发者比如每次发版都要走一套检查清单二是团队里负责统一规范的人想把代码约定沉淀成可复用资产三是经常写重复提示词的人与其每次复制粘贴不如做成一个/deploy斜杠命令。SKILL.md 的结构、frontmatter 字段含义、以及怎么在 Claude Code 里加载触发验证是接下来要拆的三件事。需要先说明一点Skill 和过去的 custom command 已经合并了。.claude/commands/deploy.md和.claude/skills/deploy/SKILL.md都会生成/deploy斜杠命令。但 Skill 比 command 多了三样东西一个目录用来装周边文件、frontmatter 可以控制触发行为、以及让 Claude 自己按相关性调用。所以如果你还在用老的 commands 目录是时候迁移了。2. SKILL.md 放哪里与 frontmatter 字段全解先解决位置问题。Skill 的存放路径决定了它的作用范围这个必须搞清楚否则你写完了发现别的项目用不了会很懵。位置路径谁能用个人~/.claude/skills/skill-name/SKILL.md你所有项目项目.claude/skills/skill-name/SKILL.md只在这个项目Pluginplugin/skills/skill-name/SKILL.md装了这个 plugin 的地方Managed企业统一下发全组织同名冲突时的优先级是 enterprise personal project。plugin 用plugin-name:skill-name的命名空间隔离不会跟别的冲突。另外 skill 和老的.claude/commands/同名时skill 优先。一个 skill 本质是个目录入口是 SKILL.mdmy-skill/ ├── SKILL.md ← 必须主入口 ├── reference.md ← 可选详细参考材料按需加载 ├── examples.md ← 可选例子 └── scripts/ └── helper.py ← 可选脚本由 Claude 执行不加载为上下文SKILL.md 必须有其他都可选。但周边文件要在 SKILL.md 里用链接或说明引用出来Claude 才知道它们存在、什么时候该读。接下来是 frontmatter这是整个 Skill 机制里最容易被低估的部分。正文前面用---包一段 YAML规定这个 skill 的行为--- name: my-skill description: 这个 skill 干什么、什么时候用 disable-model-invocation: false user-invocable: true allowed-tools: Read Grep ---只有description是推荐必填的。所有字段的含义如下字段作用name斜杠命令名。不填就用目录名。只能小写字母、数字、连字符最多 64 字符description关键字段。Claude 靠这个判断什么时候自动调用。不填就取正文第一段when_to_use补充触发条件和常见触发词。跟 description 合起来在 skill 列表里最多 1536 字符超了被截断argument-hint自动补全时提示参数形式比如[issue-number]disable-model-invocationtrue 时 Claude 不会自动调用只能用户手动/name触发。适合有副作用的操作user-invocablefalse 时不在/菜单里显示只让 Claude 自己按需调用。适合背景知识型 skillallowed-tools这个 skill 激活时 Claude 可以免审核使用的工具。空格分隔model/effort这个 skill 激活时用哪个模型 / 花多少思考预算context: fork把这个 skill 放进 fork 出来的 subagent 跑不污染主上下文agent搭配context: fork用指定用哪种 agenthooks绑定到这个 skill 生命周期的 hookpathsglob 模式。设了以后 Claude 只在操作匹配路径的文件时自动调用shell内联 shell 命令用什么解释器默认 bash可选 powershell有个硬性约束name必须跟目录名一致。改 name 等于改目录名别只改一个。description为什么这么要紧因为 Claude 判断要不要调用一个 skill只能看 description 和 when_to_use 两段话正文平时不在它的上下文里。所以 description 必须写清楚三件事这个 skill 做什么不是关于 X 的而是用来做 X、什么时候该触发列具体的用户说法、文件类型、任务特征、把最常见的触发场景前置因为尾部可能被 1536 字符限制截掉。反面教材长这样description: 一个关于 API 设计的 skillClaude 看完不知道是该在写 API 时触发、还是在 review API 时触发、还是在解释 API 给新人听时触发。好例子是这样description: 写新的 API endpoint 时触发——检查命名约定、错误返回格式、请求验证。触发词加一个接口、新 endpoint、implement API。不覆盖 GraphQL只管 REST。这里有个小陷阱Claude 默认偏少触发怕用错。所以 description 要稍微往推销的方向写一点比如即使用户没明说 X只要任务有 Y 特征就触发比中性描述更有效。3. 可复制的 SKILL.md 模板与渐进式加载配置理解了字段接下来直接上可复制的模板。我按两种典型场景各给一份你可以改改就用。第一份是任务型 skill适合部署、提交、生成文档这类有明确步骤的操作。注意disable-model-invocation: true因为部署有副作用不该让 Claude 自己决定触发--- name: deploy-check description: 发版前跑一遍检查清单——跑测试、看 diff、确认版本号、生成 changelog。触发词准备发版、deploy check、上线前检查。 disable-model-invocation: true argument-hint: [version] allowed-tools: Bash(npm test *) Bash(git diff *) Bash(git status *) --- # 发版检查 $ARGUMENTS 按顺序执行以下步骤每步完成后报告结果 1. 跑 npm test如果有失败停下来报告不要继续 2. 跑 git status 和 git diff --stat确认没有未提交的意外改动 3. 检查 package.json 里的 version 是否已经是 $ARGUMENTS 4. 如果版本号不对提示我手动改不要自己改 5. 生成 changelog 草稿按 feat / fix / chore 分类 详细的分支命名规范和 changelog 格式见 reference.md。第二份是参考型 skill适合代码规范、API 约定这类背景知识。这种让 Claude 按需触发即可disable-model-invocation留默认--- name: api-conventions description: 写或改 REST API endpoint 时触发——检查命名、错误返回格式、请求验证。触发词加接口、新 endpoint、改 API。只管 REST不管 GraphQL。 paths: src/api/** --- # REST API 约定 写 endpoint 时遵守以下约定 - 路径用复数名词kebab-case/user-profiles 不是 /getUserProfile - 错误返回统一格式{ error: { code: ..., message: ... } } - 所有输入必须验证用项目里的 validate() 工具函数 - 分页参数统一用 limit offset 完整的错误码表和验证示例见 reference.md。这两份模板里都提到了 reference.md这就是渐进式加载progressive disclosure的落地方式。Skill 体系有三层Metadataname description一直在 Claude 上下文里用来判断是否触发SKILL.md 正文触发后才加载周边文件和脚本由 Claude 按 SKILL.md 的指引按需读取脚本是执行的、不加载为上下文。这决定了 SKILL.md 的体积管理策略官方建议控制在 500 行以内超了就把详细参考拆到同目录的 reference.md 或 examples.md并在 SKILL.md 里明确说详细看 reference.mdClaude 才知道什么时候读。有个容易踩的点skill 一旦触发SKILL.md 的渲染结果进入会话就留在那里后面不会重新读文件。所以写 SKILL.md 要写成贯穿整个任务的指引而不是一次性步骤。另外Skill 内容分两种性质写法不同。参考型像文档写遇到 X 时考虑 Y任务型像 playbook写第一步、第二步、第三步。想清楚你的 skill 属于哪种再动笔。传参数用$ARGUMENTS拿全部参数用$ARGUMENTS[N]或简写$N0-based拿单个Migrate $0 component from $1 to $2.用户跑/migrate SearchBar React Vue$0 SearchBar、$1 React、$2 Vue。多词参数用引号包。动态注入上下文用!shell command在 skill 发给 Claude 之前执行命令把输出替换到 placeholder 里--- name: pr-summary description: 总结一个 PR 的改动 allowed-tools: Bash(gh *) --- ## PR 信息 - diff: !gh pr diff - 评论: !gh pr view --comments ## 任务 总结这个 PR……Claude 收到的是命令运行完的结果不是命令本身。多行命令用 ! 开头的代码块。4. 在 Claude Code 里加载、触发与验证 Skill 生效配置写完了怎么确认它真的生效这一步很多人跳过结果 skill 不触发时一头雾水。下面是我实测下来比较稳的验证流程。第一步确认 skill 被发现了。在 Claude Code 里直接问What skills are available?如果列表里没有你的 skill说明路径或文件名有问题。检查三件事目录名和name字段是否一致、SKILL.md 是否在skill-name/SKILL.md这个层级、frontmatter 的---是否闭合。第二步手动触发验证。对于任务型 skill直接敲斜杠命令/deploy-check 1.2.0观察 Claude 是否按 SKILL.md 里的步骤走。如果它没读 SKILL.md 而是自己发挥多半是 description 没写清楚或者正文结构太松散。第三步验证自动触发。对于参考型 skill不要用斜杠命令而是用自然语言描述一个应该触发它的任务帮我加一个新的 API endpoint用来查用户订单列表如果 skill 配置正确Claude 应该会先读 api-conventions 的 SKILL.md然后按里面的约定写代码。你可以从它的输出里看到是否遵守了 kebab-case 路径、统一错误格式这些约定。第四步验证参数传递。跑一个带参数的 skill看$ARGUMENTS是否正确替换。比如/fix-issue 123Claude 收到的应该是修 GitHub issue 123按项目代码规范来。第五步验证 subagent 隔离。如果你的 skill 用了context: fork触发后它应该在一个新开的隔离上下文里跑不看当前会话历史。适合我要研究一下 X这种只需要产出一份总结的任务--- name: deep-research description: 深入研究一个话题 context: fork agent: Explore --- 深入研究 $ARGUMENTS 1. 用 Glob 和 Grep 找相关文件 2. 读代码、分析 3. 总结发现给出具体文件引用注意context: fork只对有明确任务的 skill 有意义。纯约定文档型的 skill fork 进去只会看到约定但没任务什么都不做就返回。关于allowed-tools它授权 skill 激活时可以免审核调用指定工具allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *)这不限制有哪些工具可用别的工具还是能调只是会触发权限提示。所以它是个免审核白名单不是工具黑名单。如果你在团队里统一管理 skill建议把项目级的放在.claude/skills/下随代码提交个人通用的放~/.claude/skills/。这样新人 clone 下来就能用不用口头传授。5. Skill 不触发、description 被截断等常见报错排查这一节按真实报错场景来对照着查。Skill 完全不触发。先问 Claude What skills are available? 确认 skill 被发现了。如果没被发现检查路径和 name 一致性。如果被发现了但不触发看 description 里有没有用户会自然说出的关键词。很多时候是 description 写得太抽象比如处理数据相关任务用户实际说的是帮我清洗一下这个 CSV对不上。解决办法是重新措辞请求往 description 里的说法靠或者直接用/skill-name强制触发。Skill 触发太频繁。说明 description 范围太宽。写得更具体缩小触发范围或者加disable-model-invocation: true改成只手动触发。有副作用的操作本来就该手动触发别让 Claude 自己决定要不要部署。Description 被截断。多个 skill 挤在一起时每个 description 会被截到适配字符预算。把最重要的触发场景前置到 description 开头。单个 skill 的 description when_to_use 合起来 1536 字符上限超了也被截。环境变量SLASH_COMMAND_TOOL_CHAR_BUDGET可以调高总预算但治本的办法还是精简。Skill 触发后效果慢慢消失。这是最隐蔽的坑。SKILL.md 内容在会话里不会重新读取只是模型可能选了别的工具或方式。解决办法有三个写贯穿任务的指引而不是一次性步骤用 hooks 做硬强制长会话压缩后重新/skill-name再调用一次恢复上下文。401 或权限相关报错。如果你在 skill 里调用了外部 API而 API Key 没配好会看到 401。这时候检查环境变量是否在 skill 执行的环境里可见。Claude Code 的 skill 执行环境继承当前 shell 的环境变量但如果你在 skill 里用!注入命令要确认那个命令能拿到 Key。local proxy failed 或连接类报错。这类通常出现在 skill 里用!注入的命令需要访问网络时。检查命令本身是否能独立跑通先在终端里手动执行一遍确认不是 skill 机制的问题。reading choices 相关报错。如果你在 skill 里让 Claude 做选择而选项格式不对可能看到这个。确保 SKILL.md 里给出的选项是明确的、可枚举的别让 Claude 自己猜。OAuth 或认证类报错。如果 skill 里集成了需要 OAuth 的工具确认 token 没过期。这类问题跟 skill 本身无关是外部依赖的问题。Codex auth.json 相关。如果你在 skill 里调用 Codex 或类似工具需要确认auth.json的路径和内容正确。这类集成建议把 Base URL、Key、Model ID 三件套都显式写清楚别依赖隐式配置。排查时有个通用思路先把 skill 的正文简化到最小可触发版本确认机制通了再逐步加内容。很多时候不是 skill 机制的问题是正文里某个命令或引用出了问题。6. 把 Skill 沉淀成团队资产从个人技巧到可复用技能包写到这里你已经有了一个能跑的 skill。但单个 skill 只是开始真正有价值的是把它变成可复用的技能包。我试过的一个做法是每个 skill 目录里除了 SKILL.md再放一个CHANGELOG.md记录这个 skill 的演进。因为 skill 本质是提示词资产改了什么、为什么改过两个月自己都忘了。团队里多人维护时这个记录能省很多沟通成本。另一个经验是skill 的 description 要当成 API 文档来写。它是 Claude 判断触发的唯一依据也是团队成员理解这个 skill 干什么的第一入口。写 description 时想象你在跟一个新人解释什么时候该用这个工具而不是在写产品介绍。如果你有多个相关 skill考虑用 plugin 打包。plugin 用plugin-name:skill-name的命名空间隔离不会跟别的冲突也方便分发。团队里统一装一个 plugin比每个人手动复制目录靠谱得多。最后说一个容易被忽略的点skill 的正文要写成贯穿整个任务的指引。因为 SKILL.md 一旦触发就留在会话里不会重新读取。所以别写成第一步做 A第二步做 B这种一次性步骤而要写成在整个任务过程中遇到 X 时考虑 Y遇到 Z 时检查 W。这样即使会话很长Claude 也能持续参考。如果你想把 skill 和外部模型能力结合起来比如在 skill 里调用不同的模型做特定任务可以通过 API 接入的方式实现。模型对话入口在 https://taotoken.net/api接入文档在 https://taotoken.net/docAPI Key 在 https://taotoken.net/api-keys 管理。长期做编码和 Agent 类任务的话Coding Plan 会更合适https://taotoken.net/coding-plan。这些都可以作为 skill 里的外部能力补充让 skill 不只是提示词而是真正能调工具、调模型的完整工作流。Skill 这套机制的核心价值是把你的经验从每次重新说一遍变成写一次到处触发。开始的时候别贪多先写一个最常用的跑通了再扩展。