为Claude Code构建自定义技能：完整教程

连续三次会话，我都将同一份安全检查清单粘贴到Claude Code中。该清单包含我们团队特定的漏洞模式——针对我们API设计的IDOR检查、针对我们认证流程的会话处理规则、针对我们PII字段的数据暴露规则。每一次，Claude都完美地执行了这些规则。每一次，我都得记着去粘贴它们。

当您发现自己反复解释相同上下文的那一刻，就是您应该构建技能的时刻。

TL;DR

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

前置条件： 熟悉Claude Code的扩展系统。有关技能、命令和子代理之间的比较，请参阅指南的技能章节。

何时构建技能

并非每个重复的提示都值得构建技能。以下是决策框架：

技能用于Claude始终可用的知识。斜杠命令用于您显式触发的操作。如果您在两者之间犹豫不决，请问自己：”Claude应该自动应用这个，还是应该由我决定何时运行它？”

一个常见错误： 为每周只做一次的事情构建技能。我曾构建了一个git-rebase-helper技能，它在任何与git相关的提示上都会激活——变基、合并、挑选提交，甚至git status。描述过于宽泛，在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字段是技能中最重要的一行。以下是其底层运作机制：在会话开始时，Claude Code提取每个技能的name和description并注入到Claude的上下文中。当您发送消息时，Claude使用语言模型推理——不是正则表达式，不是关键词匹配，不是嵌入相似度——来判断是否有任何技能相关。官方文档指出：”Claude将您的任务与技能描述进行匹配以决定哪些相关。如果描述模糊或重叠，Claude可能会加载错误的技能——或遗漏一个本可以提供帮助的技能”¹。

对Claude Code源代码的独立分析证实了该机制：技能描述被注入系统提示的available_skills部分，模型使用标准语言理解在调用时选择相关技能⁴。基于LLM的匹配机制对您编写描述的方式有重要影响。

糟糕的描述：

description: Helps with code

Claude不知道何时激活它。”帮助处理代码”匹配一切又什么都不匹配——而且由于匹配基于LLM推理，模糊的描述会导致不可预测的激活。

较好的描述：

description: Review code for bugs and issues

仍然太模糊。什么类型的缺陷？什么类型的问题？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中审查技能变更

核心要点

• 当您发现自己在重复解释上下文时，构建技能。 如果您三次粘贴了相同的检查清单，它就应该成为一个技能。
• 描述字段决定一切。 Claude使用LLM推理将您的请求与描述进行匹配¹。在描述上投入的时间应该多于技能内容本身。
• 使用allowed-tools约束副作用。 只读技能应限制为Read、Grep、Glob。
• 通过git共享项目技能。 零配置的团队知识分发¹。
• 不要过度抽象。 为每个微模式都创建技能会带来维护负担，并且会争夺上下文预算。只为稳定、可复用、且值得维护的专业知识构建技能。

参考文献