如果你经常在 Claude Code 里重复输入同一套要求，比如“先看 diff，再总结改动，然后帮我生成 commit message”，那其实就很适合把这套流程做成一个 Claude Code Skill。
简单说，Claude Code Skill 就是放在指定目录里的一个 SKILL.md 操作说明。Claude Code 会先读取这个 Skill 的描述信息，当用户的请求和它匹配时，再加载完整内容，然后按照里面写好的流程、规则、脚本或参考资料来完成任务。
它特别适合下面这些场景：
固定工作流，比如代码审查、提交信息生成、部署前检查、文档生成；
团队规范，比如代码风格、接口约定、测试要求；
工具用法，比如某个 CLI、SDK 或框架应该怎么正确使用；
长提示词复用，比如你不想每次都把同一段说明复制给 Claude Code。
下面不绕弯子，先从跑通第一个 Claude Code Skill 开始。
3 分钟跑通第一个 Claude Code Skill我们先做一个最小可用的 commit-helper Skill。它的作用很简单：帮你总结 Git 改动，并生成提交信息。
1. 创建 Skill 目录个人级 Skill 一般放在这个位置：
mkdir -p ~/.claude/skills/commit-helper
然后创建 SKILL.md 文件：
touch ~/.claude/skills/commit-helper/SKILL.md
2. 写入最小可用内容打开 ~/.claude/skills/commit-helper/SKILL.md，写入下面这段内容：
---name: commit-helperdescription: Use when the user asks to summarize git changes, review a diff, or generate a commit message.when_to_use: 当用户说“生成 commit message”“总结这次改动”“帮我看 diff”“写提交信息”时使用。---你是一个 Git 提交助手。请按以下步骤工作：1. 先查看当前 Git 状态；2. 阅读 git diff；3. 用中文总结本次改动；4. 按 Conventional Commits 格式给出 3 个提交信息候选；5. 如果改动涉及多个主题，建议拆分提交。输出格式：## 改动总结## 风险点## Commit Message 候选
3. 启动 Claude Code 测试一下进入一个 Git 项目，然后启动 Claude Code：
claude
接着在 Claude Code 里输入：
帮我总结这次改动，并生成 commit message
如果 Claude Code 按照“改动总结 / 风险点 / Commit Message 候选”这个结构输出，并且会主动查看 Git 状态或 diff，基本就说明这个 Skill 已经生效了。
如果它没有自动触发，也可以直接点名：
请使用 commit-helper skill 帮我总结这次改动，并生成 commit message
Claude Code Skill 应该放在哪里？个人级、项目级、插件级怎么选Claude Code Skill 常见有三种放置位置：
个人级：~/.claude/skills/<skill-name>/SKILL.md项目级：.claude/skills/<skill-name>/SKILL.md插件级：<plugin>/skills/<skill-name>/SKILL.md
大致可以这样理解：
位置适合场景示例个人级自己在所有项目里都想用的习惯commit message、个人代码审查、写作总结项目级当前项目或团队共享的规则部署流程、代码规范、API 规范插件级可复用、可分发的一组 Skill组织内部 Skill 包、开源 Skill 集合如果你是刚开始用，建议先从个人级 Skill 入手。它路径固定，验证起来也最简单。
等团队里也想一起用的时候，再把项目级 Skill 放到仓库的 .claude/skills/ 目录下，这样可以跟着代码一起做版本管理。
一个比较实用的原则是：不要什么都塞进全局 Skill。个人习惯放个人级，项目规则放项目级，真正要复用和分发的能力，再考虑做成插件级。
SKILL.md 应该怎么写？字段、正文和模板一个基础的 Claude Code Skill 通常长这样：
---name: skill-namedescription: What this skill does and when to use it.when_to_use: Optional trigger examples.---## Goal说明这个 Skill 要完成什么任务。## Steps1. 第一步；2. 第二步；3. 第三步。## Output format规定输出格式。## Constraints说明限制、禁止事项和注意点。
里面最关键的几个部分是：
name：Skill 名称，最好和目录名保持一致，后续维护会省很多事；
description：非常重要，Claude Code 会根据它判断什么时候该用这个 Skill；
when_to_use：补充说明触发条件，可以写用户可能会怎么说，也可以写一些边界场景；
正文：把具体流程、规则、示例、输出格式、禁止事项都写清楚。
这里尤其要注意，description 不要写得太泛。
比如这样就不太推荐：
description: Help with coding.
问题在于它太宽了。Claude Code 很难判断到底什么时候应该用这个 Skill。
更好的写法是：
description: Use when the user asks to review git diff, summarize code changes, or generate Conventional Commits style commit messages.
写 description 时，可以记住几个小原则：
把最关键的触发场景放在前面；
尽量使用用户真实会说的话，比如 “generate commit message”“review diff”；
不要写成宣传语，比如“提升开发效率的强大助手”这种就没什么帮助；
背景解释放到正文里，不要都塞进 description；
如果只适用于某个技术栈，也要写清楚，比如 “for Spring Boot projects”。
Claude Code 是怎么触发 Skill 的？Claude Code Skill 并不是每次都会把完整内容都塞进上下文。更准确地说，可以把它理解成下面这个过程：
会话开始时，Claude Code 会先看到 Skill 的描述信息；当用户请求和描述匹配时，它才会加载完整的 Skill 内容；然后再按照 SKILL.md 里写好的步骤执行。
所以，Skill 能不能被触发，关键还是看 description 和 when_to_use 写得够不够明确。
常见触发方式有三种。
1. 用自然语言自动触发帮我看一下这次 diff，并生成 commit message
只要 commit-helper 的描述写得清楚，Claude Code 就有机会自动使用它。
2. 明确指定 Skill使用 commit-helper skill 帮我生成提交信息
如果你不确定它会不会自动触发，直接点名是最稳的方式。
3. 通过斜杠命令触发有些 Skill 也可以映射成自定义命令，比如：
/deploy-staging user-service staging
这种方式很适合高频、参数固定的操作。
怎么把 Skill 做成 Claude Code 自定义命令Claude Code 支持把部分 Skill 映射成命令。比如你有一个项目级 Skill：
.claude/skills/deploy-staging/SKILL.md
它可以对应一个命令：
/deploy-staging
一个部署检查 Skill 可以这样写：
---name: deploy-stagingdescription: Use when the user wants to deploy a service to staging.---Deploy the $ARGUMENTS[0] service to $ARGUMENTS[1].Before deployment:1. Check git status.2. Run tests.3. Confirm environment variables.4. Execute the deployment command.5. Verify logs after deployment.If any step fails, stop and explain the reason before continuing.
调用时可以这样写：
/deploy-staging user-service staging
这里可以理解为：
$ARGUMENTS[0] 是第一个参数；
$ARGUMENTS[1] 是第二个参数；
有些版本或场景里，也可能看到 $0、$1 这样的参数形式，具体还是要以当前 Claude Code 的官方文档和实际版本为准。
自定义命令很适合部署、检查、生成报告这类固定流程。不过也没必要把所有 Skill 都做成命令。能用自然语言顺利触发的，就保持自然调用，反而更轻。
复杂 Skill 怎么组织？scripts、references、assets 分别放什么简单 Skill 通常一个 SKILL.md 就够了。但如果 Skill 比较复杂，可以按下面这种结构来组织：
my-skill/├── SKILL.md├── scripts/│ └── check.py├── references/│ └── api-style-guide.md└── assets/ └── template.md
这些目录一般可以这样用：
scripts/：放可执行脚本，比如检查脚本、转换脚本；
references/：放比较长的文档、规范、API 说明；
assets/：放模板、示例文件或静态资源。
不过要注意一点：这些目录不是“魔法目录”。也就是说，你把文件放进去，并不代表 Claude Code 一定会自动知道它们的用途。
更稳妥的做法，是在 SKILL.md 里明确告诉它什么时候用这些文件，比如：
如需检查 API 文档格式，请参考 references/api-style-guide.md。如需自动检查 OpenAPI 文件，请运行 scripts/check.py。生成接口文档时，请优先使用 assets/template.md 中的模板结构。
如果脚本需要执行，还要记得检查权限：
chmod +x scripts/check.py
Skill、CLAUDE.md、MCP、Hooks、Subagents 到底该用哪个？很多人刚开始会把 Claude Code Skill、CLAUDE.md、MCP、Hooks、Subagents 混在一起。其实它们各自解决的问题不太一样，可以先用下面这张表判断：
场景推荐方式项目长期规则、构建命令、代码风格CLAUDE.md可复用的专业流程或操作手册Skill调用数据库、API、外部服务MCP保存、提交、测试前自动执行动作Hooks并行分析大量文件、隔离上下文Subagents再看一下 CLAUDE.md 和 Skill 的区别，会更清楚：
对比项CLAUDE.mdSkill适合内容项目基础规则可复用流程、专业任务加载方式项目启动时读取先读描述，匹配时再读完整内容适合长度短而核心可以写得更详细作用范围项目或用户规则个人、项目、插件都可以示例构建命令、代码风格代码审查、部署流程、文档生成简单总结就是：
固定的项目规则，放到 CLAUDE.md；
重复流程、长说明、工具用法，适合写成 Skill；
要连接外部服务，用 MCP；
要做事件自动化，用 Hooks；
要并行处理大任务或隔离上下文，用 Subagents。
还有一点别弄混：Skill 可以告诉 Claude “应该怎么做”，但它本身不是 MCP，也不会天然提供外部 API 调用能力。
5 个可以直接复制的 Claude Code Skill 模板下面放几个常用模板，你可以直接放到个人级或项目级目录里使用，再根据自己的项目稍微改一改。
1. Git commit message Skill路径：
~/.claude/skills/commit-helper/SKILL.md
---name: commit-helperdescription: Use when the user asks to summarize git changes, review a diff, or generate commit messages.when_to_use: 用户要求“生成提交信息”“总结改动”“看 diff”“写 commit message”时使用。---你是 Git 提交助手。步骤：1. 查看 git status；2. 阅读 git diff；3. 总结本次改动；4. 判断是否需要拆分提交；5. 按 Conventional Commits 输出 3 个候选。输出：## 改动总结## 风险点## Commit Message 候选
2. Code review Skill---name: code-review-helperdescription: Use when the user asks to review code changes for correctness, security, performance, maintainability, and test coverage.when_to_use: 用户要求“帮我 review”“检查这段代码”“看下 PR 风险”时使用。---你是代码审查助手。请重点检查：1. 逻辑正确性；2. 安全风险；3. 性能问题；4. 可维护性；5. 边界条件；6. 测试覆盖。输出格式：## 总体结论## 必须修改## 建议优化## 测试建议
3. Unit test Skill---name: unit-test-helperdescription: Use when the user asks to generate or improve unit tests for existing code.when_to_use: 用户说“补测试”“生成单测”“提高测试覆盖率”时使用。---你是单元测试助手。步骤：1. 先理解被测函数或类的行为；2. 找出正常路径、异常路径和边界条件；3. 生成可运行的测试代码；4. 如缺少上下文，先提出需要确认的问题；5. 不要为了通过测试而修改业务逻辑，除非用户明确要求。输出：## 测试点清单## 测试代码## 还缺少的上下文
4. API document Skill---name: api-doc-helperdescription: Use when the user asks to generate API documentation from routes, controllers, OpenAPI files, or interface definitions.when_to_use: 用户要求“生成接口文档”“整理 API”“写 OpenAPI 文档”时使用。---你是 API 文档助手。请输出：1. 接口名称；2. 请求方法和路径；3. 请求参数；4. 请求体；5. 响应字段；6. 错误码；7. 示例请求和响应。如果项目中存在接口规范，请优先遵守项目规范。
5. SDK / CLI 使用规范 Skill这个模板很适合用来避免 Claude Code 使用过时命令，或者编出不存在的参数。
---name: cli-usage-guidedescription: Use when the user asks to write commands or code using a specific CLI or SDK version.when_to_use: 用户要求使用某个 CLI、SDK、内部工具或固定版本依赖时使用。---你是 CLI / SDK 使用规范助手。规则：1. 优先遵守本 Skill 中记录的版本和命令；2. 不要使用未确认存在的参数；3. 如果命令不确定，先查看项目文档或询问用户；4. 输出命令前说明用途；5. 对危险操作给出确认提示。在生成命令时，请按以下格式输出：## 命令## 作用## 前置条件## 风险提示
Claude Code Skill 不生效怎么办？可以按这个清单排查如果你写好的 Claude Code Skill 没有生效，别急，通常是下面这些问题。建议按顺序检查一遍。
第一，确认文件名是不是写对了。必须叫 SKILL.md，大小写也要注意。
第二，看路径是否正确。个人级 Skill 应该放在：
~/.claude/skills/<skill-name>/SKILL.md
项目级 Skill 则应该放在：
.claude/skills/<skill-name>/SKILL.md
第三，检查 YAML frontmatter 有没有闭合。开头和结尾都要有 ---，少一个都可能导致解析失败。
第四，看看 description 是不是太泛了。不要只写 “Help with coding”，而要写清楚它具体在什么场景下触发。
第五，如果你刚新增或修改过 Skill，建议重新启动当前 Claude Code 会话再测试。很多时候，重启一下就能解决问题。
第六，如果自动触发不稳定，可以直接明确告诉 Claude：
请使用 xxx skill 完成这个任务
第七，确认脚本和参考资料是否已经在 SKILL.md 中被提到。只是把文件放进 scripts/ 或 references/ 里还不够，正文里最好明确说明什么时候该用它们。
第八，如果 Skill 里要执行脚本，还要检查执行权限和运行环境，比如 Python 版本、依赖是否安装等。
第九，看看是不是和其他 Skill 的职责太像了。如果多个 Skill 的 description 写得过于相似，Claude Code 可能会不知道该选哪个。
第十，如果你用到了自定义命令、插件级 Skill 等能力，还要确认当前 Claude Code 版本是否支持。涉及版本差异时，最好以官方最新文档为准。
写好 Claude Code Skill 的一些实用建议想让 Claude Code Skill 更稳定、更容易维护，可以遵守下面这些原则。
首先，一个 Skill 尽量只解决一类问题。比如代码审查、提交信息、部署流程，最好分开写，不要都塞进同一个 Skill 里。
其次，description 要写触发场景，不要写宣传语。它是给 Claude Code 判断使用时机的，不是广告文案。
when_to_use 里可以多写一些用户原话，比如“生成 commit message”“帮我 review 这段代码”。这样更容易匹配真实使用场景。
流程最好写清楚执行顺序。比如先做什么、再做什么、遇到异常怎么办。步骤越明确，Claude 自由发挥的空间就越小，结果也更稳定。
输出格式也建议固定下来。明确标题、字段、列表结构，这样生成的内容更容易复制到 PR、文档或提交信息里。
如果有很长的规范文档，建议放到 references/，不要把几千字内容全堆在 SKILL.md 主体里。这样文件更清爽，也方便维护。
能执行的逻辑，比如格式检查、文档校验、代码扫描，可以放到 scripts/。这样 Skill 就不只是提示词，而是能配合工具完成更可靠的检查。
团队共用的 Skill，最好放到项目仓库里的 .claude/skills/。这样大家拿到项目后，都能使用同一套流程。
另外，尽量避免和 CLAUDE.md 重复。CLAUDE.md 更适合写项目基础约定，而 Skill 更适合写可复用的任务流程。
最后，定期清理不用的 Skill 也很重要。Skill 太多，而且描述互相重叠，反而会影响触发准确性。
如果你刚开始用 Claude Code Skill，可以按这个顺序来：
第一步，先建一个个人级的 commit-helper。它用来总结 diff 和生成提交信息，效果最容易验证，也最容易感受到 Skill 的价值。
第二步，再把团队流程沉淀成项目级 Skill。比如 code review、部署检查、API 文档生成，这些都很适合放到项目里共享。
第三步，等流程变复杂后，再拆出 scripts/ 和 references/。这样 Skill 就不只是几段提示词，而是一套包含流程、规范和可执行工具的工作包。
说到底，Claude Code Skill 的核心并不复杂：把你反复告诉 Claude Code 的工作方法，沉淀成可复用、可触发、可维护的操作手册。