要在 Claude Code 中创建自定义 Skill，先决定它供个人跨项目使用，还是随当前项目共享；再在对应的 .claude/skills/ 路径下新建一个 Skill 目录，并在目录内编写 SKILL.md。文件需要用 frontmatter 描述 Skill 的适用场景，再写清执行步骤和结果要求。保存后启动项目会话，用明确匹配的任务测试，不能只凭文件存在就认定它已经生效。
Claude Code 的 Skill 应该放在哪里？
存放位置决定 Skill 适用于哪些会话。Anthropic 官方文档列出了个人级和项目级两种常用位置：
- 个人级：
~/.claude/skills/<skill-name>/SKILL.md，适合自己在本机多个项目中重复使用的流程。 - 项目级：
.claude/skills/<skill-name>/SKILL.md，位于当前仓库中，适合与项目约定绑定、希望团队成员共享的 Skill。提交相关文件后，团队可以随仓库获得它。
例如，你要做一个仅服务于当前仓库的“生成变更说明”Skill，可以选择项目级路径；如果同一套流程会用于多个仓库，再考虑放到个人级目录。不要把项目级路径误写成仓库根目录下直接放一个 SKILL.md：Skill 通常有自己的目录，SKILL.md 位于该目录中。
以下示例用 macOS 或 Linux 常见终端命令创建项目级目录：
mkdir -p .claude/skills/change-note然后在该目录内创建 SKILL.md。如果创建的是个人级 Skill，把目录改为 ~/.claude/skills/change-note。不同系统和终端创建文件的方式可能不同，关键是最终路径和文件名正确。本文路径和格式依据 Anthropic 官方 Skills 文档核查，日期为 2026 年 10 月 9 日；如果你的 Claude Code 版本或组织管理策略有限制，请以当前官方文档和实际环境为准。
SKILL.md 应该怎么写？
一个最小的 Skill 文件包含两部分：用一对 --- 包住的 YAML frontmatter，以及其后的 Markdown 指令。官方入门示例用 description 说明 Skill 适用场景；这个描述也帮助 Claude 判断用户的请求是否相关。目录名可作为斜杠命令名称，若在 frontmatter 中设置了名称，则命令名称由该名称决定。初次编写时，可以先使用目录名，不必增加还没用到的字段。
下面以“根据当前未提交改动整理变更说明”为例。把内容保存为 .claude/skills/change-note/SKILL.md：
---
description: 根据当前代码改动生成简洁的变更说明。用户询问改了什么、需要整理提交说明时使用。
---
## 任务
根据用户指定的范围整理代码变更说明。
## 步骤
1. 先查看与任务相关的代码差异；如果差异为空，明确说明没有可总结的改动。
2. 依据实际差异归纳改动目的和影响，不要根据文件名猜测功能。
3. 不确定的行为或影响要标明待确认，不要自行补全。
## 输出要求
用中文输出：先写一段简短摘要，再列出主要改动和需要留意的事项。不要声称测试已经通过，除非确实执行并确认了相关测试。这个示例没有绑定特定的测试命令，也没有要求修改文件或运行高风险操作，因此适合作为入门模板。后续可根据团队实际需要补充格式、验收条件和允许读取的材料；不要预设 Claude 可以访问或读取所有文件。涉及敏感文件、写入或执行命令的工作，仍需遵守项目权限设置。
适用描述怎样写才有用？
描述要能帮助 Claude 分辨“什么时候用”，不要只写“处理代码”或“开发助手”这类范围很大的词。可以写清任务类型、典型请求和边界，例如“用户询问当前代码改动或需要整理提交说明时使用”。如果这个 Skill 只适用于某个目录、某类文件或某种输入，也应在描述或正文中说明。
Skill 正文则负责说明“使用时怎么做”。把步骤拆成可检查的动作，并写清输入不足时如何处理、输出应包含什么，以及哪些信息不能臆测。不要把整份项目背景都复制进 Skill：官方文档区分了始终加载的 CLAUDE.md 与按需加载的 Skill 正文。稳定的项目事实和约定可以放在项目说明中，只有特定任务流程才需要放入 Skill。
创建后怎样确认 Skill 已经生效？
验证时同时检查“Claude Code 能否发现它”和“执行是否符合要求”：
- 确认文件位于正确范围：个人 Skill 在用户目录，项目 Skill 在当前仓库的
.claude/skills/下。 - 核对目录名称、
SKILL.md文件名和 frontmatter 分隔符，尤其检查description是否写在两条---之间。 - 在目标项目中启动 Claude Code 会话，再通过命令菜单查看可用项，或直接按目录名称调用，例如
/change-note。 - 准备一个确实符合 Skill 描述的任务，检查输出是否遵循文件中的步骤、格式和限制。
也可以用自然语言提出与 description 匹配的请求，让 Claude 判断是否适用。官方文档说明，Skill 可以在相关时自动使用，也可以由用户直接调用。测试时不要只用过于宽泛的提示，例如“帮我看看项目”；应明确说“请根据当前未提交改动整理变更说明”，这样才容易判断 Skill 是否按预期工作。
“文件已保存”“命令能调用”和“结果符合预期”是三个不同的检查点。若命令能调用但结果不对，问题可能出在步骤含糊、验收标准缺失或测试请求与适用范围不符。用同一个具体任务复测，比较修改前后的输出，比一次改动很多内容更容易定位原因。
Skill 没被识别或结果不理想，先检查什么？
- 检查路径：确认正在使用的项目就是 Skill 所在仓库，项目级目录拼写为
.claude/skills/技能目录名/SKILL.md。 - 检查文件结构：确认文件名大小写、YAML 分隔线和 frontmatter 内容没有写错，正文确实位于 frontmatter 之后。
- 检查适用描述：如果描述太宽泛或太含糊，Claude 可能难以判断何时自动使用。先把典型任务和边界写清，再用匹配的提示测试。
- 检查命名：按 Skill 目录名称调用；如果设置了 frontmatter 名称，则核对实际命令名称。避免把一个项目中的相似 Skill 与另一个同名 Skill 混淆。
- 检查会话范围：确认当前会话从适用的项目位置启动，并重新检查可用 Skill。若所在环境受组织配置限制，单靠改文件未必能改变管理策略。
如果 Skill 已经触发但执行偏离预期，不必马上增加大量说明。先找出偏差属于输入范围、操作顺序、输出格式还是安全边界，再只补充相应的一条规则。比如它把未知信息写成确定结论，就增加“无法从差异确认时标记待确认”；它漏掉风险，就明确要求单独列出注意事项。完成后用同一任务再次验证。
什么时候值得把流程做成 Skill？
适合封装的任务通常重复出现、步骤比较稳定，而且结果有明确的检查标准，例如按团队格式生成变更说明、重复执行一套代码审查清单，或遵循固定的项目操作流程。若其他成员也需要该流程，通常优先考虑项目级 Skill，并将其纳入仓库共享。
一次性需求、还在频繁变化的流程，或尚未验证是否有效的提示词，不必急着做成 Skill。先在普通对话中试几次，确认输入、步骤和输出标准稳定后再整理成文件。这样能避免维护一套很长却没人确定是否正确的说明。简单判断：如果你经常重复粘贴同一份指令，而且能说清怎样算完成，就值得考虑创建；否则先直接在对话中说明通常更省事。
常见问题：Skill 和项目说明文件有什么区别？
项目说明文件适合放 Claude 在项目中持续需要的约定；Skill 更适合某种具体任务的操作流程，正文按需加载。若 CLAUDE.md 中有一段内容已经从背景说明变成了重复执行的步骤，可以评估是否拆成 Skill，但要保留两者各自清楚的职责。
Claude Code 也兼容旧式自定义命令文件 .claude/commands/；Anthropic 文档说明它与相应 Skill 可以提供相同的斜杠命令能力。新建可复用流程时，采用带目录的 Skill 形式更便于放置说明、模板等辅助文件，也更容易按个人或项目范围管理。
创建 Skill 的核心不是写一段很长的提示词，而是把一个稳定流程整理成可判断、可执行、可核对的说明：选好作用范围，写清适用条件和任务步骤，再用真实任务验证。这样得到的 Skill 才更可能在重复工作中发挥作用。