驾驭Claude代码：真正能触发的技能

驾驭Claude代码：真正能触发的技能

系列之前

• 最基本的设置
• CLAUDE.md 做得好
• 模型、层级与努力
• 情境窗口税
• 保护你代码的钩子
• 值得添加的MCP服务器

简介

技能是Claude代码中看似简单但你真正尝试持续使用时才会发现的特性。这个想法很简单：写一个带有指令的markdown文件，放到合适的目录里，Claude在需要时加载------或者你用斜杠命令明确调用它。实际上，"相关时"这部分才是事情变得有趣的地方，而且不总是好事。

本文将介绍技能的工作原理、它们的居住地、实际控制它们是否发射的因素，以及它们常见的无声失败方式。我还会介绍一些我觉得真正有用的模式，以及那些会增加文件杂乱却无明显效益的模式。

什么是技能。

技能是带有YAML前件的markdown文件，Claude Code会加载到上下文中。每个技能都会生成一个斜击命令------写入，你得到的就是。你可以直接调用，或者当对话内容符合技能描述时，克劳德自动调用。 ~/.claude/skills/security-review/SKILL.md /security-review

这种双重调用模型将技能与旧有的使用者调用方法区分开来。合并发生在版本 2.1.3，现在两个地点的结果相同。如果你已经有文件，它们会继续工作------当名称冲突时，技能优先。.claude/commands/``.claude/commands/

技能存在于三个层面：

• 个人 （）------适用于你所有项目 ~/.claude/skills/
• 项目 （）------提交到仓库，与团队共享.claude/skills/
• 企业 级------托管设置适用于整个组织

当同一个技能名称在多个层级存在时，企业级获胜，然后是个人级，然后是投射。这与大多数人的预期相反------你的全局技能优先于项目层面的技能，而不是反过来。我稍后会回到这点的重要性。

技能的解剖结构。

每个技能都需要两个东西：YAML前置和标记说明。 SKILL.md

name: pr-review
description: Reviews staged changes for correctness, test coverage, and consistency with project conventions. Use when the user asks for a code review or is about to open a PR.

Review the current changes:

1. Run \`git diff --staged\` to see what's changing.
2. Check that every modified function has a corresponding test change.
3. Flag any hardcoded values that should be environment variables.
4. Confirm the commit message matches the conventional commit format used in this repo.

Return findings as a short numbered list. If nothing to flag, say so explicitly.

字段变成了砍击命令。这是Claude用来决定是否自动加载这项技能的内容------虽然看起来像是，但它并不是为人类准备的文档。这种区分很重要。 name description

辅助文件是可选的，但很有用。技能目录可以包含模板、示例输出、脚本或参考文档：

.claude/skills/pr-review/
├── SKILL.md
├── examples/good-review.md
└── conventions.md

明确引用这些，让克劳德知道它们的存在。目录里的文件不会自动加载------你必须指向它们。 SKILL.md

具体控制自动召唤的是什么。

克劳德根据场地情况决定是否自动加载技能。描述与当前对话背景进行对比，克劳德做出判断。这是语义匹配，而非关键词匹配------听起来灵活，但有具体缺点：难以预测或测试。 description

角色描述有预算。所有技能名称都会加载到上下文中，但描述会被截断以适应动态限制（上下文窗口的1%，备用8000字符）。每个描述的长度都限制在250个字符以内。

这意味着两件事：

1. 如果你的描述太长，就会被删减。前期就要有用例------什么任务，什么触发条件。
2. 如果你有很多技能，他们会争夺预算。十个平庸技能会挤掉重要技能。

你可以用 来增加预算，但更有用的解决办法是写更紧凑的描述，保持技能总数低。这和MCP服务器工具数量的压力一样------两者都争夺相同的上下文预算，并且会叠加。一场包含十个MCP工具和十五项技能的游戏，在你还没写出提示词之前就已经把预算烧掉了。 SLASH_COMMAND_TOOL_CHAR_BUDGET

为了防止技能自动调用，可以在前言中添加内容。部署和其他破坏性工作流程应始终保持这一点------你不希望Claude自己决定现在是发布的好时机。 disable-model-invocation: true

name: deploy
description: Deploy the application to production
disable-model-invocation: true

陷阱

先例倒置

优先顺序------企业>个人>项目------让人措手不及。如果你有一个全局代码，团队为该仓库添加了一个项目级技能，且步骤不同，项目级技能就会输。全球的胜出。 ~/.claude/skills/deploy/SKILL.md deploy

这与大多数配置的运作方式相反（项目层面覆盖全局）。解决方法是为项目特定的工作流程使用不同的名称，而不是依赖不存在的覆盖行为。

# Don't do this --- assumes project-level wins
~/.claude/skills/deploy/SKILL.md        # global deploy
.claude/skills/deploy/SKILL.md          # intended project override --- will be ignored

# Do this instead
~/.claude/skills/deploy/SKILL.md        # generic deploy scaffold
.claude/skills/deploy-staging/SKILL.md  # project-specific
.claude/skills/deploy-prod/SKILL.md     # project-specific with env context

无声无匹配问题

本应自动触发的技能往往根本不会生效。描述过于模糊、冗长，或者与对话的实际表述不符。没有任何预警。Claude 根本不会加载技能，除非你特别注意，否则你会以为这个功能坏了。

失败的模式如下：

# Too vague --- Claude doesn't know when this applies
description: Helps with code quality and reviews

# Better --- specific trigger condition, specific task
description: Reviews staged changes for test coverage and conventional commit format. Use before opening a PR.

当技能没有触发时，首先要检查的不是说明，而是描述。通过直接调用技能来测试，确认指令本身有效，然后细化描述，直到自动调用可靠。 /skill-name

如果你想要对某个工作流程保证调用，可以加个注释，比如"每次PR前使用/pr-review"。这是一种手动协议，不是自动化，但很可靠。自动调用在正常时很方便，坏时则是隐形的。 CLAUDE.md

总是加载技能带来的上下文膨胀

自动调用技能每次发射时都会把指令添加到上下文窗口。这项技能会在每一个文件解释、每次代码审查、每一次提交------也就是说，在这些任务中消耗的token------都触发。长时间的治疗会叠加。

捆绑技能就是一个很好的例子：它会并行生成三个审核代理，每个代理读取文件。这是针对一次性重构的故意设置，而不是你想在每道题都加载的内容。 /simplify

要有意识地选择哪些技能可以自动调用，哪些应该明确调用。任务技能------部署、迁移、PR创建------几乎都应该使用。参考技能------约定、模式、API文档------是自动调用的合理候选对象，因为它们的全部价值在于无需你请求即可获得。 disable-model-invocation: true

还有一个值得注意的钩子交互：一个在每次写入文件时运行格式化器的钩子本身就会增加令牌开销。再加上一个广泛自动调用的技能，在主动编辑会话中每回合消耗会迅速攀升。如果你用的是PostToolUse钩子，要更保守地选择让哪些技能自动射击。

值得了解的捆绑技能。

Claude Code 内置了几个技能。这些是基于提示的（非硬编码），因此可以读取文件、生成代理并适应你的代码库：

• /batch <instruction> ------ 将大量变更分解为并行单元，在孤立的 git 工作树中每个单元生成一个代理，并为每个单元打开一个 PR。需要git仓库。对跨代码库迁移非常有用。
• /simplify [focus] ------生成三个并行审查代理，汇总发现并应用修复。传递焦点：。 /simplify focus on memory efficiency
• /loop [interval] <prompt> ------在会话开放时，按计划反复运行一个提示。对于监控部署或轮询外部资源非常有用。
• /debug [description] ------在会话中启用调试日志并读取日志。当工具调用出现意外行为时，这比听起来更有用。
• /claude-api ------ 加载你项目语言的 API 参考材料。当检测到代码中导入 Anthropic SDK 时，它还会自动调用。

捆绑技能与内置斜杠命令（， ， ）之间的区别很重要：内置命令执行固定逻辑且无法自定义。捆绑技能是基于提示的，你可以通过创建同名且优先级更高的技能来覆盖它们。 /compact /clear /cost

技巧与窍门

• 项目技能保持在版本控制中。 承诺仓库。未来的团队成员无需入职步骤就能掌握工作流程。.claude/skills/
• 一项技能，一份工作。 一个能做代码审查、生成提交消息并检查覆盖范围的技能，比三项专注技能还差。分开。
• 对于长篇参考内容，请使用辅助文件。 如果你的技能指令引用了你们团队的编码规范，把这些规范放进技能目录里，并从那里链接到。这样说明书更易读。 conventions.md SKILL.md
• 通过直接调用来测试技能指令。 绕过描述匹配。如果技能在手动调用时有效但不会自动，说明需要改进------而不是说明。 /skill-name
• 给 CLAUDE.md 添加技能清单。 列出可用的自定义技能以及使用时间。克劳德在游戏开始时会朗读，这不仅强化了自动召唤，也增强了团队意识。

摘要

技能很有用，但需要比文档所暗示的更为刻意的设置。自动调用完全取决于描述质量，而无声失败模式------技能根本不触发------第一次触发时诊断需要一段时间。优先顺序（全球节拍项目）几乎会让所有人感到惊讶。

有效的模式是：团队工作流程中使用项目级技能，保持专注并明确命名，用于任何破坏性任务，并在可靠性比便利性更重要的情况下，用技能清单来补充自动调用。 disable-model-invocation: true CLAUDE.md

在下一篇文章中，我将介绍子代理------它们与技能的区别，何时生成独立代理值得承担开销，以及为什么他们的隔离模型（每个代理一个新的上下文窗口，不共享历史）是适合技能不适合在线处理的冗长工作的最佳方案。