如何构建真正有效的 Claude Code 技能 (完整指南)

你使用 Claude 已经一周了，但每次都在重复输入同样的内容。每次提交代码时，你都要粘贴关于提交格式的三条规则。每次写文档时，你都要重新解释你的风格。Claude 做得很好，但对话一结束它就忘了，第二天你又得全部重打一遍。

技能（Skill）可以解决这个问题。它是一个小文件夹，你只需编写一次，就能永久教会 Claude 一个工作流程，这样每次会话它都会自动应用，无需你主动要求。

它的工作原理一目了然：技能就是一个文件夹，里面包含一个文件。Claude 会始终在视图中保留该技能的一行摘要，只有当你的请求匹配时，它才会加载完整的指令。这就是整个机制。

在本指南中，我们将从零开始构建一个真实的技能：commit-messages，它能按照你确切的格式编写 Git 提交信息。如果你已经安装了 Claude 且没有其他工具，你可以按步骤操作。

最终成果

技能的核心是一个文件夹，其中包含一个必需文件 SKILL.md。随着技能的发展，还会引入三个可选的文件夹：

1your-skill-name/
2├── SKILL.md          # 必需 - 主要技能文件
3├── scripts/          # 可选 - 可执行代码
4├── references/       # 可选 - 文档
5└── assets/           # 可选 - 模板等

SKILL.md 本身包含两部分：一个简短的头信息，告诉 Claude 何时 使用该技能；以及头信息下方的指令，告诉 Claude 做什么。这种拆分很重要。Claude 会不断读取头信息，因此它始终知道技能的存在，但只有当你的请求匹配时，它才会加载指令。请牢记这个区别，因为本指南中几乎所有其他内容都源于此。

创建技能

技能位于你家目录下的 .claude/skills 文件夹中，Claude Code 和桌面应用都会读取该文件夹。它是一个隐藏文件夹，可能还不存在，因此创建它以及技能文件夹的最快方法是使用一条命令。

在 Mac 上，打开终端并运行：

1mkdir -p ~/.claude/skills/your-skill-name

在 Windows 上，打开 PowerShell 并运行：

1New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills\your-skill-name"

文件夹名称并非无关紧要。Claude 将其用作技能的标识符，而一个格式化规则比其他任何规则都更容易让人犯错：

• 使用 kebab-case：notion-project-setup ✔
• 不要空格：Notion Project Setup ✖
• 不要下划线：notion_project_setup ✖
• 不要大写：NotionProjectSetup ✖

在该文件夹中，创建一个名为 SKILL.md 的文件，并用任何文本编辑器打开它。从这里开始，所有内容都将写入该文件。

先设计，再编写

有效的技能从两个决策开始，在编写文件之前就要做出。这两个决策看起来都可以跳过，但实际上都不能。

首先，明确技能应该在何时触发。用用户实际会输入的词语，写下两三个真实场景：

• "commit these changes"
• "write a commit message for this diff"
• "stage and commit"

这不是无用功。这些短语将成为你描述和后续测试的原始材料，而一个没有经过这种设计的技能往往会在最关键的地方变得模糊，从而永远无法触发。

其次，决定如何判断技能是否有效。最重要的标准是：技能是否能自动加载，而不需要你主动提及它。如果你每次都必须手动调用它，那么技能虽然技术上运行了，但实际任务失败了。还需要关注的是：它是否能在不中途纠正的情况下完成任务，以及它是否能在不同会话中给出相同形式的结果。

描述是成败的关键

在文件中，头信息中的描述作用最大，因为它是 Claude 在决定是否加载技能时唯一读取的部分。你的指令即使无可挑剔，但如果描述不匹配，Claude 根本不会去读。这就是大多数"不工作"的技能实际上失败的地方。

一个好的描述在一个句子中回答两个问题：技能做什么，以及 Claude 何时应该使用它。后半部分正是人们常常遗漏的。

以下是区别：

1# 弱 - 只说明是什么，没有给 Claude 匹配请求的依据
2description: 帮助处理 Git 提交。
3
4# 强 - 指明它应该触发的时机
5description: 使用 Conventional Commits 格式编写 Git 提交信息。当用户要求提交更改、编写提交信息或暂存并提交文件时使用。

弱版本告诉 Claude 技能存在，但从未将其与你说的任何内容联系起来。强版本命名了实际短语，因此当你输入 "commit these changes" 时，Claude 可以匹配。使用用户真正会用的词语，保持整个描述在 1024 个字符以内，并且不要在其中包含 < 或 > 符号。

当技能无法触发时，修复方法几乎总是在这里。添加你实际使用的措辞。如果你说 "save my work"，但描述只提到了 "commit"，Claude 就无法将两者关联起来。反之，如果技能在不该触发时触发了，请缩小描述范围或添加否定触发条件：

1description: 使用 Conventional Commits 格式编写 Git 提交信息。在提交更改时使用。不要用于编写代码注释或文档。

有一种快速方法可以在依赖技能之前检查它的效果。直接问 Claude：

"你什么时候会使用 commit-messages 技能？"

Claude 会用自己的话复述你的描述。如果这与你实际希望技能触发的时间不一致，那么你就找到了问题所在——问题出在描述上，而不是下面的指令。

编写 Claude 真正遵循的指令

头信息下方是正文，使用纯 Markdown 格式。这是你真正的工作流程所在，而两个习惯决定了 Claude 是会遵循指令，还是会悄悄偏离。

第一个是具体化。Claude 会执行具体指令，而忽略模糊的指令，因此你越精确，它的行为就越可靠：

1# 不好
2在最终确定前验证提交。
3
4# 好
5运行 `python scripts/validate.py "<message>"`。
6如果失败，修复以下问题：
7- 无效类型：使用 feat, fix, docs, refactor, test, chore
8- 摘要超过 60 个字符：缩短它

第二个是排序。Claude 会优先处理它首先读取的内容，因此埋在长文件底部的规则往往会被忽略。将任何绝对不能破坏的规则放在顶部，并加上一个表示其重要性的标题：

1## 重要
2- 摘要行始终不超过 60 个字符
3- 只使用现在时："add"，而不是"added"

此外，语言本身也有局限性。指令是被解释的，这意味着 Claude 会很好地遵循它们，但不会每次都完全相同。当某个检查必须在每次运行时都通过时，不要用文字描述它，而是将其移入脚本中，并让指令运行它。代码每次都会做同样的事情；而句子不会。（这就是 scripts/ 文件夹的用途，将在下一部分介绍。）

适用于大多数技能的结构如下：

1# 技能名称
2
3## 重要
4不能遗漏的关键规则。
5
6## 指令
7逐步、具体且可操作。
8
9## 示例
10具体的输入和输出。Claude 复制示例比遵循规则更可靠。

保持文件精简。当它开始超出核心指令时，就是将额外细节移出去的时候——这正是可选的文件夹的用途。

脚本、参考资料、资源

到目前为止，我们创建的技能只是给 Claude 提供指令。三个可选文件夹将其转变为给 Claude 提供工具的技能，这也是技能能做到普通提示无法做到的事情的地方。

scripts/ 存放 Claude 运行的代码，用于任何需要精确执行的任务。与其相信 Claude 凭目测提交格式是否正确，不如交给它一个脚本来检查：

1# scripts/validate.py
2import sys
3msg = sys.argv[1]
4types = ("feat", "fix", "docs", "refactor", "test", "chore")
5
6if msg.split(":")[0] not in types:
7    print(f"无效类型。请使用：{', '.join(types)}")
8elif len(msg.split("\n")[0]) > 60:
9    print("摘要太长（超过 60 个字符）")
10else:
11    print("OK")

然后你在 SKILL.md 中告诉 Claude 使用它：

1在最终确定之前，运行 `python scripts/validate.py "<message>"`
2并修复它标记的任何问题。

现在，格式规则由每次运行方式相同的代码强制执行，而不是依赖于 Claude 记住要检查。

references/ 存放仅在需要时加载的文档。假设你的提交约定有两页篇幅，涉及范围、页脚和边缘情况。如果全部放在 SKILL.md 中，那么每次提交时都会加载，即使只是一行提交信息。相反，将其移入引用文件：

1your-skill-name/
2├── SKILL.md
3└── references/
4    └── conventions.md

并在主文件中指向它：

1有关完整约定列表，请参阅 references/conventions.md

Claude 只在任务需要时才会打开该文件。这就是技能保持低运行成本的全部原因：详细内容存放在磁盘上，直到实际相关时才加载，而不是每次都占用上下文。

assets/ 存放技能在输出中使用的文件，而不是用于指导，例如模板、配置文件或徽标。提交技能不需要这些，但生成报告的技能可能会在此处保留一个 template.md，每次填充它，这样每个报告都会具有相同的结构。

综上所述，这三个文件夹是将技能从"告诉 Claude 你如何工作"提升为"交给 Claude 精确的工具来按你的方式工作"的关键。

唯一需要记住的事

技能并不是教给 Claude 新的能力。它已经知道如何编写提交。技能的作用是让它每次都按照你的方式完成任务，而无需你再次说明。

当技能不起作用时，原因几乎不是你辛苦编写的指令，而是描述。Claude 在读取下面的指令之前，就根据那一行描述来决定是否加载技能。把描述写对了，下面的一切才能被真正使用。

如果这对你有帮助，请前往我的个人资料并关注我。我写关于技术、AI 以及真正能运行的系统。

再见，

@undefinedKi