Claude Code 技能：构建可自动激活的自定义扩展

如何为 Claude Code 构建自定义技能？ 在 ~/.claude/skills/<name>/（个人级）或 .claude/skills/<name>/（项目级）中创建一个 SKILL.md 文件，其 YAML frontmatter 包含 name、description 和 allowed-tools 字段，后面接 markdown 格式的专业知识正文。Claude 会针对 description 进行 LLM 推理，在任务与之匹配时自动激活该技能。通过 git 共享的项目技能，队友无需任何配置即可使用。

连续三次会话，我都把同一份安全检查清单粘贴进 Claude Code。清单里是团队特有的漏洞模式：我们 API 设计中独有的 IDOR 检查、认证流程的会话处理规则、PII 字段的数据暴露规则。每一次，Claude 都完美地应用了它们。每一次，我都得自己记着去粘贴。

当您发现自己在反复解释同一段上下文时，就该构建一个技能了。

TL;DR

技能是由模型调用的扩展——Claude 会根据上下文自动发现并应用它们，无需您显式调用 ¹。技能是否可靠，关键在 description 字段：Claude 用 LLM 推理（而非关键词匹配）来决定何时激活每个技能 ¹。把跨会话通用的领域知识（安全模式、代码风格、业务规则）做成技能。一次性任务不必建技能——改用斜杠命令即可。

前置条件： 熟悉 Claude Code 的扩展系统。关于技能、命令与子代理的对比，请参阅指南中的 Skills 章节。

何时该构建技能

并非每一条重复的提示词都值得做成技能。判断框架如下：

技能承载的是 Claude 随时可用的知识，斜杠命令承载的是 您显式触发的动作。在两者之间犹豫时，不妨自问：“这件事该由 Claude 自动应用，还是该由我决定何时运行？”

一个常见错误： 为每周才做一次的事构建技能。我曾写过一个 git-rebase-helper 技能，结果任何与 git 沾边的提示词都会触发它——rebase、合并、cherry-pick，连 git status 也不例外。它的 description 太宽泛，在 80% 根本用不到它的会话里污染上下文，还要和其他技能争抢那 2% 的上下文预算 ¹。解决办法是删掉这个技能，改用斜杠命令：真正需要时输入 /rebase。技能应当编码 稳定的领域专长，而不是 偶尔为之的工作流。

教程：构建一个代码审查技能

步骤 1：创建目录

技能可以存放在四个位置，作用范围由宽到窄 ¹：

本教程创建一个个人技能：

mkdir -p ~/.claude/skills/code-reviewer

步骤 2：编写带 frontmatter 的 SKILL.md

每个技能都需要一个 SKILL.md 文件，它由两部分组成：位于 --- 标记之间的 YAML frontmatter，告诉 Claude 何时 使用该技能；以及 markdown 正文，写明技能被调用 时 Claude 应遵循的指令 ¹。

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

### Data Exposure
- PII masked in log output and error messages
- API responses don't leak internal IDs or stack traces
- Sensitive fields excluded from serialization defaults

请留意 allowed-tools: Read, Grep, Glob ——它把技能限制为只读操作。这个代码审查器可以查看文件，却无法修改。工具限制能防止技能产生意料之外的副作用。

除 name、description 和 allowed-tools 之外，其他有用的 frontmatter 字段 ¹：

官方文档中有一点值得注意：context: fork“只有对那些带有明确指令、且能从隔离中获益的技能才有意义” ¹。请把它用在分析类技能上（代码审查、安全审计等需要干净上下文的场景），而不是那些本应融入主对话的知识类技能。

步骤 3：添加配套资源

技能可以引用同一目录下的其他文件 ¹：

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

用相对链接在 SKILL.md 中引用它们：

See [SECURITY_PATTERNS.md](SECURITY_PATTERNS.md) for OWASP Top 10 checks.
See [PERFORMANCE_CHECKLIST.md](PERFORMANCE_CHECKLIST.md) for query optimization.

技能激活时，Claude 会用标准的文件读取工具按需读取这些文件 ¹。请把 SKILL.md 控制在 500 行以内，把详细的参考资料移到配套文件中 ³——技能文件越短，上下文注入的开销越小，Claude 也更能专注于当前任务。

步骤 4：测试激活

技能会在您下次启动 Claude Code 会话时生效。测试方法：

# Ask Claude to review code — should trigger the skill automatically
claude "Review the authentication middleware in app/security/"

可以用两种方法之一确认技能已加载 ¹：

# In an interactive session, ask Claude directly:
> What skills are available?

# Or check the context budget for excluded skills:
> /context

如果技能没有激活，问题几乎总是出在 description 字段上。请看步骤 5。

步骤 5：关键一步——写好 description

description 字段是整个技能中最重要的一行。底层机制是这样的：会话开始时，Claude Code 会提取每个技能的 name 与 description，把它们注入 Claude 的上下文。当您发送消息时，Claude 用 语言模型推理 ——不是正则、不是关键词匹配、也不是向量相似度——来判断是否有技能与之相关。官方文档写道：“Claude 会把您的任务与技能描述进行匹配，以决定哪些技能相关。如果描述含糊或彼此重叠，Claude 可能加载错误的技能——或者错过本该帮上忙的那一个” ¹。

对 Claude Code 源码的独立分析印证了这一机制：技能描述会被注入系统提示词的 available_skills 部分，模型在调用时用常规的语言理解挑选相关技能 ⁴。这种基于 LLM 的匹配，对描述的写法有着重要影响。

糟糕的描述：

description: Helps with code

Claude 根本无从判断何时该激活它。“Helps with code”既匹配一切，又什么都不匹配——而由于匹配依赖 LLM 推理，含糊的描述会带来无法预期的激活行为。

稍好的描述：

description: Review code for bugs and issues

仍然太笼统。哪一类 bug？哪一类问题？Claude 何时该用它，而不是用自带的分析能力？

有效的描述：

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

这条描述之所以奏效，是因为它写清了： - 它做什么： 针对 具体的问题类型 审查代码 - 何时使用： 检查改动、审查 PR、分析代码质量 - 触发词： review、audit、check——用户自然会输入的词

需要知道的一个约束： 所有技能描述共享一份上下文预算，它“按上下文窗口的 2% 动态伸缩，并以 16,000 个字符作为兜底” ¹。技能一多，每条描述就得写得精炼——冗长的描述会与其他技能争抢有限的空间。您可以通过 SLASH_COMMAND_TOOL_CHAR_BUDGET 环境变量覆盖这个预算 ²，但更好的做法是把描述写得更短、更准确。

多试几种描述。 开一个全新会话，请 Claude 审查代码，看技能是否激活。没激活就补充触发词；在不该激活时激活了，就把描述写得更具体。

步骤 6：根据使用情况迭代

用上一周之后，您会发现： - 技能本该检查却漏掉的模式——把它们补进 SKILL.md - 在无关任务上误激活——收紧描述，或加上 disable-model-invocation: true，改为显式调用 /code-reviewer - 缺少上下文——添加配套资源文件 - 工具限制过紧或过松——调整 allowed-tools

技能是活的文档。第一版永远不是最终版。

进阶：把技能当作提示词库

除了单一用途的技能之外，这套目录结构本身就是一个井井有条的提示词库：

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

每个技能编码团队专长的一个侧面。合在一起，它们构成一个知识库，Claude 会根据上下文自动从中取用。初级开发者无需开口，就能获得资深水准的指导。

关于技能数量的提醒： 技能越多，争抢上下文预算的描述也越多 ¹。如果发现技能不激活，运行 /context 查看是否有技能被排除在外。宁可少而精，也不要多而含糊。

与团队共享技能

个人技能（~/.claude/skills/）只属于您自己。适合放个人偏好、实验性的模式，或专属于您工作流的专长。

项目技能（仓库根目录下的 .claude/skills/）通过 git 共享 ¹：

# Create project-level skill
mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...

# Commit and push
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

队友拉取代码后就自动拥有了这个技能。无需安装，无需配置。用 git 分发，是在团队内统一专长最有效的方式。

共享技能的几条准则： - 项目技能专注于领域专长（业务规则、架构模式） - 个人技能留给工作流偏好（格式化、提交风格） - 在 SKILL.md 顶部用注释写明这个技能为何存在 - 像对待其他代码一样，在 PR 中审查技能的改动

要点回顾

• 当您发现自己在反复解释上下文时，就该构建技能。 同一份检查清单粘贴三次，它就该成为一个技能。
• description 字段决定一切。 Claude 用 LLM 推理把您的请求与描述做匹配 ¹。花在描述上的时间，应当多于花在技能正文上的时间。
• 用 allowed-tools 约束副作用。 只读技能应限制为 Read、Grep、Glob。
• 通过 git 共享项目技能。 零配置的团队知识分发 ¹。
• 不要过度抽象。 为每个微小模式都建一个技能，既带来维护负担，又要争抢上下文预算。只为那些稳定、可复用、值得维护的专长构建技能。

常见问题

什么是 Claude Code 技能？

技能是以 markdown 文件形式存储、由模型调用的扩展，Claude 会根据上下文自动发现并应用它们。与需要您显式触发的斜杠命令不同，技能在 Claude 的 LLM 推理判定当前任务与技能描述相符时自动激活。它们编码领域专长——安全模式、代码风格规则、业务逻辑——并跨会话保留，您不必每次重新解释上下文。

如何为 Claude Code 创建自定义技能？

在 ~/.claude/skills/<name>/ 下创建目录即为个人技能，在 .claude/skills/<name>/ 下则是项目级技能。目录内创建一个 SKILL.md 文件，先写 YAML frontmatter（包含 name、description，以及可选的 allowed-tools），再写 markdown 正文，说明 Claude 应当应用的专业知识。description 字段至关重要——Claude 会针对它进行 LLM 推理，决定何时激活技能。分步走查请见上文的完整教程。

Claude Code 技能与斜杠命令有什么区别？

技能根据上下文自动激活——Claude 用 LLM 推理对照技能描述，判断它们是否相关。斜杠命令则是由用户调用的动作，需要您输入 /command-name 显式触发。如果希望 Claude 始终掌握这些知识（领域专长、质量标准），就构建技能；如果希望自己决定何时执行（部署脚本、一次性工作流），就构建斜杠命令。

Claude Code 技能可以调用其他工具吗？

可以，但由您通过 frontmatter 的 allowed-tools 字段控制哪些工具可用。像代码审查器这样的只读技能应限制为 Read, Grep, Glob，以免产生意外的副作用。若省略 allowed-tools，技能可以使用 Claude 能访问的任何工具。技能还可以在 frontmatter 中定义自己的钩子，这些钩子仅在技能运行期间生效。

为什么我的 Claude Code 技能没有激活？

最常见的原因是 description 字段含糊或过于宽泛。Claude 用 LLM 推理——而非关键词匹配——来判断技能是否与当前任务相关。如果描述写成“helps with code”，Claude 无从区分它与其他任何编码任务。请把描述写具体：点明确切的问题类型、触发场景，以及用户自然会输入的动词。另外，在会话中运行 /context，看看技能是否因 2% 的上下文预算上限而被排除。技能太多、争抢空间时，总有一些会被丢掉。

Claude Code 技能存放在哪里，又该如何共享？

技能有四个存放位置，作用范围依次扩大：个人（~/.claude/skills/<name>/SKILL.md）、项目（.claude/skills/<name>/SKILL.md）、插件，以及企业级（托管设置）。个人技能作用于您的所有项目。项目技能通过 git 共享——队友拉取后即自动获得，零配置。所有技能描述共享上下文窗口 2% 的预算，因此技能较多时请保持描述简洁。

参考资料