注册
Claude

Claude Code 写一个会自动触发的 Skill：从需求到触发，用 description、when_to_use 和 paths 控制它什么时候出场

写好的 Skill 总是不触发，或者什么都触发？本文按 Claude Code 官方「Extend Claude with skills」走一遍完整实例：把「改数据库迁移前先检查」写成一个会自动出场的 Skill，包含 description、when_to_use、paths、附带脚本、触发测试和评估。

NNathaniel bigo··原创首发·AI 辅助撰写
11 分钟读完
资料核对于 2026-11-05 · 依据官方文档与公开资料整理 Pro 账号
本文根据 Claude Code 官方文档《Extend Claude with skills》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

  • 已经会写最简单的 Skill，但总遇到「它不自己出场」或「不该出场时乱出场」的人；
  • 想让 Claude 在改某一类文件时自动套用团队规矩，而不是每次手动输入命令的人。

本站的 /guides/claude-code-custom-skill-slash-command-example 写的是手动触发的 /release-notes。本文反过来：写一个主要靠自动触发的 Skill，重点是怎么让它在对的时候出现。字段规范和目录结构不重复，见 /guides/skill-md-format-spec-how-to-write。

结论先说

  1. 自动触发靠的是 description。 官方说，普通会话里所有技能的名字和描述会被放进上下文，Claude 据此判断要不要加载；技能全文只在被调用时才进来。
  2. description 要把关键用途放最前面，写进用户会自然说的词。 官方给了硬数字：description 和 when_to_use 合起来在技能列表里最多保留 1,536 个字符，超出被截断。
  3. 想把范围收窄，用 paths。 设置后 Claude 只在处理匹配这些文件时才自动加载这个技能；匹配相对当前工作目录。
  4. 「必须每次都做」的规则不要只靠 Skill。 官方说 Claude 可能后来不照着做，必须每次发生的要改用 Hook。
  5. 看到触发不等于做对了。 官方建议拿几条真实提示词，分别在有技能和关掉技能的新会话里各跑一次，对比结果。

让 Skill 自动触发的步骤

图：本站根据 Claude Code 官方文档：Skills 整理的示意图

一、先把需求说清楚

好的 Skill 来自一个具体的重复问题。本例的需求：

团队的数据库迁移文件放在 migrations/ 下。每次让 Claude 改迁移，我都要重复提醒：不要直接删列，新增非空列必须带默认值，改完要跑检查脚本。

这是官方说的「总是把同一段指令粘贴进对话」的典型情形。它还有两个特点：不需要你每次想起来才用（所以适合自动触发），只和一类文件有关（所以适合 paths）。

二、建目录和 SKILL.md

放项目里，提交进仓库全队共用（官方的项目技能位置）：

bash
mkdir -p .claude/skills/migration-review/scripts

.claude/skills/migration-review/SKILL.md：

text
---
name: migration-review
description: 修改或新增数据库迁移文件前后的检查清单。当用户要改 migrations、加表、加列、删列、改字段类型时使用。
when_to_use: 用户说「写个迁移」「给表加个字段」「这个迁移安全吗」，或者正在编辑 migrations 目录下的 SQL 文件。
paths: migrations/**
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check.sh *)
---

处理迁移文件时，整个任务期间都遵守这些规则：

1. 不直接删除列或表；需要删除时，先拆成「停止使用」和「删除」两个迁移，并在回复里提醒我。
2. 新增 NOT NULL 列必须带默认值，或者先加可空列再回填。
3. 改完每个迁移文件后，运行 `${CLAUDE_SKILL_DIR}/scripts/check.sh <迁移文件路径>`，把输出原样告诉我。
4. 检查不通过时，说明原因并修改，不要绕过脚本。
5. 命名规则和更多例子见 [conventions.md](conventions.md)，需要时再读。

对照官方文档逐项解释：

  • description 加 when_to_use：官方说 when_to_use 用来补充「什么时候该调用」，比如触发短语或示例请求，会追加到 description 后面，一起计入 1,536 字符上限。所以两个都别写成长文。
  • paths：官方说明可以是逗号分隔的字符串或 YAML 列表，格式与路径专属规则相同。
  • allowed-tools：官方说它在调用这个技能的那一轮里，让列出的工具不再弹确认；下一条消息发出后失效。官方还给了同样的写法：用 ${CLAUDE_SKILL_DIR} 同时写在正文和 allowed-tools 里，规则就能精确匹配正文要求运行的命令，脚本不会弹窗。
  • 规则写成整个任务期间都适用的口吻：官方说技能内容进入对话后不会被重新读取，所以要写成常驻指令，而不是一次性步骤。

三、加脚本和参考文件

官方说脚本是被执行的而不是被读进上下文，适合把确定性的检查交给程序。下面这个 scripts/check.sh 是本站为演示写的，规则很简单，请按自己的数据库改：

bash
#!/usr/bin/env bash
# 演示脚本：检查迁移文件里的两类高风险写法
f="$1"
[ -f "$f" ] || { echo "文件不存在：$f"; exit 2; }
if grep -Eiq 'DROP[[:space:]]+(COLUMN|TABLE)' "$f"; then
  echo "发现 DROP COLUMN / DROP TABLE，请拆成两个迁移"; exit 1
fi
if grep -Eiq 'ADD[[:space:]]+COLUMN.*NOT NULL' "$f" && ! grep -Eiq 'DEFAULT' "$f"; then
  echo "新增 NOT NULL 列没有 DEFAULT"; exit 1
fi
echo "检查通过：$f"

再建 conventions.md，写命名规则和两三个「好的 / 坏的」迁移示例。官方建议 SKILL.md 控制在 500 行以内，详细内容挪到单独文件，并且在 SKILL.md 里写明每个文件是什么、什么时候读（上面第 5 条就是这样做的）。

四、测试：它到底触发了吗

官方的验证办法有几条，按顺序做：

  1. 启动 claude，问「What skills are available?」（用中文问「有哪些技能可用」也可以），确认 migration-review 在列表里。
  2. 用自然语言提需求，不要用命令：
text
给 users 表加一个 phone 字段，非空，写个迁移
  1. 如果没有自动加载，用 /migration-review 直接调用，确认技能本身没问题。
  2. 再用一句不相关的话（比如「帮我改一下首页的按钮颜色」），确认它没有乱出场。

Skill 触发不对时先查什么

图：本站根据官方「Troubleshooting」整理的示意图

五、触发不对怎么办（官方排查顺序）

不触发：

  1. 看 description 里有没有用户自然会说的词；
  2. 确认它出现在可用技能列表里；
  3. 换一种更贴近 description 的说法再试；
  4. 用 /名字 直接调用；
  5. 如果设了 paths，检查 Claude 读、改、写的文件是否在当前工作目录之内。官方特意提到：兄弟 git worktree 里的文件不会激活，即使用 /add-dir 添加过也一样。要么在那个目录里启动，要么用 /cd 把会话移过去。

另外官方提醒：YAML 写错时技能仍会加载，但元数据是空的，所以 /名字 能用、自动匹配却不行。可以用 claude --debug 看解析错误，或运行 claude plugin validate .claude/skills。

触发太频繁： 让 description 更具体，或者加 disable-model-invocation: true 改成只能手动触发。

描述被截断： 技能多了之后，官方说描述列表有预算（约为模型上下文窗口的 1%），超出时从最少使用的技能开始丢描述。运行 /doctor 能估算列表占的上下文，/skill-doctor 能找出该关掉的技能。

后来不照着做： 见结论第 4 条。必须每次都做的，用 Hook；见 /guides/claude-code-hooks。官方还说对话被压缩后可能只保留技能内容的开头，所以最重要的规则放最前面。

六、让 Claude 帮你调 description

提示词：

text
我有一个技能 .claude/skills/migration-review/SKILL.md。请给出 8 句用户可能会说的话，其中 4 句应该触发它，4 句不应该；然后逐句判断按现在的 description 和 when_to_use 会不会触发，不会的给出修改建议。先不要改文件。

七、怎么知道它真的有用

官方的说法是：触发只说明 Claude 找到了它，不说明结果对。方法是收集几条真实的提示词，各在新会话里跑两遍，一遍开着技能、一遍关掉（项目技能可以在 skillOverrides 里设为 "off"），比较结果；在新会话里跑很重要，因为你写技能时留下的上下文会掩盖指令里的漏洞。

要自动化这个流程，官方提到可以装 skill-creator 插件：

text
/plugin install skill-creator@claude-plugins-official

装好后让 Claude「evaluate my migration-review skill with skill-creator」，它会生成测试用例、做有无技能的对比，并能测 description 的命中率。如果提示 marketplace 找不到，官方给的办法是先 /plugin marketplace add anthropics/claude-plugins-official。插件系列见 /guides/claude-code-plugins-marketplace。

常见问题

Q：Skill 和 CLAUDE.md 怎么分工？

事实和常驻约定放 CLAUDE.md；只在某类任务时才需要的流程放 Skill，平时只占一行描述。选型对比见 /guides/skill-vs-mcp-vs-subagent-vs-hook。

Q：触发不稳定，有没有专门的排查文章？

见 /guides/skill-not-triggering-description-optimize。

Q：放哪个目录、同名谁优先？

见 /guides/claude-code-skills-directory-location-priority。

订阅和额度

Skill 的好处之一是正文按需加载，不会像长 CLAUDE.md 那样每次都占上下文。需要 Claude Code 订阅可看 /chongzhi/claude-code，价格和额度以官方页面当前显示为准。

相关教程

参考资料

  • Claude Code 文档：Extend Claude with skills — https://code.claude.com/docs/en/skills

Nathaniel 的更多内容

  1. 01

    Claude Personal Finance 是什么：连银行账户问花销、怎么开、只读权限、谁能用、怎么解除

    Claude 的 Personal Finance（beta）通过 Plaid 只读连接你的银行、信用卡、贷款和投资账户，在一页里看余额和花销并用自然语言提问。本文按官方帮助页讲谁能用（仅美国、Pro/Max/Ultra）、连接与解除步骤、Claude 能看什么，以及它做不到的事。

    Claude0
  2. 02

    Claude Code 离开一小时回来对话被「压缩」了：Idle compaction 是什么、条件、怎么关

    Claude Code 的 idle compaction 会在你离开约一小时后，把 200K token 以上的长对话先压缩成摘要，下一条消息就不用重新处理整段历史。本文按官方文档讲触发条件、看到什么提示、用 /config 或 idleCompaction 关闭、调阈值，以及恢复旧对话的用量警告。

    Claude0
  3. 03

    ChatGPT Computer History 是什么：Mac 桌面端的活动记忆怎么开、怎么暂停和清除、谁能用

    Computer History 是 ChatGPT macOS 桌面应用里默认关闭的可选功能，把你在应用和网站里的活动整理成记忆和时间线，供 ChatGPT 与 Codex 引用。本文按官方文档讲怎么开、记录什么不记录什么、怎么暂停与清除、数据存哪、谁能用，以及提示注入风险。

    ChatGPTCodex0
  4. 04

    Codex 输入框出现灰色建议：Composer predictions 是什么、Tab 接受、怎么关、谁能用

    Codex 桌面 App 的 Composer predictions（beta）会在 Codex 回完后，根据当前对话在输入框里给出下一条消息的建议，按 Tab 接受、不会自动发送。本文按官方帮助页讲谁能用、哪些线程支持、怎么关、算不算额度，以及没出现时怎么查。

    ChatGPTCodex0
  5. 05

    ChatGPT 隐私中心（Privacy Center）在哪里：隐私设置入口、三大分类和哪些套餐有

    ChatGPT 的 Privacy Center 把记忆、广告、位置、临时对话、锁定对话、两步验证、模型改进、数据导出和删号等入口集中到一页。本文按官方帮助页讲怎么打开、三大分类各有什么、哪些套餐有，以及它不会替你改任何设置。

    ChatGPT0
  6. 06

    Claude Code 处理大仓库：怎么让它只看需要的目录（子目录 CLAUDE.md、claudeMdExcludes、deny 规则）

    仓库太大，Claude Code 总在读无关文件、读进别的包的规则？本文按官方大仓库指南讲：从哪个目录启动、子目录 CLAUDE.md、claudeMdExcludes、Read 的 deny 规则、worktree.sparsePaths、additionalDirectories，以及一份合并后的配置示例。

    Claude0

同产品的其他教程

  1. 01

    Claude Code 在 CI 里跑：从本机 claude -p 到 GitHub Actions 的完整例子（自动审 PR、控成本）

    一条线走完 Claude Code 的 CI 用法：先在本机用 claude --bare -p 配 --json-schema 跑通，再写进 GitHub Actions 用 claude-code-action@v1 自动审 PR，最后加上 --max-turns、超时、并发限制来控成本，并附上常见故障的排查顺序。

    Claude0
  2. 02

    Claude Code 自定义 subagent 实例：测试员、调试员、只读调研员、只读数据库员怎么写

    四个可直接改的 subagent 实例：跑测试的 test-runner、找根因的 debugger、只读调研员、用 PreToolUse hook 限成只读 SQL 的 db-reader；讲 tools、disallowedTools、model、maxTurns 怎么配，怎么点名调用。

    Claude0
  3. 03

    Claude Code 的 CLAUDE.md 模板：前端、后端、数据分析各一份，附拆分与自检方法

    直接拿去改的三份 CLAUDE.md 模板（前端、后端、数据分析），每份都控制在官方建议的 200 行以内；再讲怎么用 .claude/rules 的 paths 拆出专属规则、用 @ 导入长文档，以及用 /context all 和 /doctor prompt-audit 检查是否生效。

    Claude0
  4. 04

    Claude Code 自己写一个插件并发布到 marketplace：plugin.json、marketplace.json、validate 到团队安装的完整流程

    想把自己写的 Skill、Hook 打包给团队用？按 Claude Code 官方 Plugins 文档，从目录结构、plugin.json、claude plugin validate，到写 marketplace.json、推到 Git、让同事一条命令安装，再到版本更新，走完一遍完整流程。

    Claude0
  5. 05

    Claude Code 配 Sentry MCP 排查线上报错：添加命令、浏览器授权、贴 issue 链接修 bug 和插件子智能体

    线上报错只能手动复制堆栈给 Claude Code？Sentry 官方提供 MCP 服务，可以让它直接读 issue、堆栈和 trace。本文按 Claude Code 官方 MCP 文档和 Sentry MCP 官方说明，讲添加命令、/mcp 授权、典型排查流程、插件方式和自托管注意事项。

    Claude0
  6. 06

    Claude Code 配 Context7 MCP 查最新文档：两种安装方式、use context7 怎么写、指定库和版本

    Claude Code 写出来的代码用了旧版 API？Context7 是一个把库的最新文档喂给编程助手的 MCP 服务。本文按 Context7 官方仓库和文档，讲两种安装方式、在 Claude Code 里的添加命令、use context7 与 library ID 的写法，以及使用时的注意事项。

    Claude0

0 条评论

登录 后参与评论

还没有评论，来抢沙发～