写你的第一个 Skill：一个文件夹+一段 markdown

上周同事问我："你那个自动帮你提 commit 的东西是怎么搞的？每次信息都写得那么规整。"我说：一个文件夹加一段 markdown。他以为我在开玩笑。

不是。

Skills 就是这么朴素：你新建一个目录，在里面放一个叫 SKILL.md 的文件，写上你想让 AI 记住的规范或步骤，然后工具下次启动就能发现它、把它当成自己的一部分。你不需要写代码，不需要配置文件，不需要学 DSL——唯一需要的是把你脑子里的操作规范，用普通中文或英文写清楚。

这篇就是手把手做这件事：写你的第一个 Skill，从建目录到跑通验证，一次做完。

---

Skill 是什么，为什么是"一个文件夹"

如果你看过上一节 Skills 入门：SKILL.md 渐进式读法，已经知道 Skill 的基础概念，这里快速过一遍核心认知，然后直接动手。

Skill 的物理结构极其简单：

my-skill/
└── SKILL.md

一个目录，一个文件。就这样。

工具（这里以 Claude Code 为主，其他支持 Skills 的工具逻辑类似，以官方文档为准）会在对话开始时扫描指定位置的 SKILL.md 文件，把它的内容读进上下文。你以后说一句"帮我提 commit"，它就会想起你在 SKILL.md 里写的规范，按那个规范给你做。

这里有个地方很容易被低估：Skills 不是给人读的文档，是给模型读的提示词。你在 SKILL.md 里写的每一行，AI 都会读到。写得越清楚、越具体，它执行得越准。这个差别在写第一个 Skill 的时候就要建立起来。

---

第一步：建目录

Skill 放哪里，工具才能发现它？这是最先要搞清楚的问题。

以 Claude Code 为例：

• 项目级：放在项目根目录下的 .claude/skills/ 里。这个目录下的 Skill 只对当前项目生效。
• 全局级：放在 ~/.claude/skills/（Mac/Linux）或 %USERPROFILE%\.claude\skills\（Windows）里。这里的 Skill 对你所有项目都生效。

初学建议从项目级开始，方便测试、不影响其他项目。

建目录：

# 进入你的项目
cd /path/to/your-project

# 建 skills 目录（如果 .claude 不存在会一起创建）
mkdir -p .claude/skills/git-commit-guide

目录名就是这个 Skill 的名字，用小写加连字符，一个 Skill 一个目录。现在你有了：

your-project/
└── .claude/
    └── skills/
        └── git-commit-guide/

空的，接下来填 SKILL.md。

---

第二步：写 SKILL.md——含完整可抄实例

在刚才建好的目录里创建 SKILL.md：

touch .claude/skills/git-commit-guide/SKILL.md

然后用任何编辑器打开它，照下面写。我先给你完整实例，再逐段拆解：

---
name: git-commit-guide
description: 当用户说"帮我提 commit"、"提交一下"、"写个提交信息"、"git commit 帮我写"时使用。按约定式提交规范生成标准的 git commit 信息并执行提交。
---

# Git 提交规范助手

你的任务是帮用户生成符合约定式提交（Conventional Commits）规范的提交信息，并完成提交。

## 执行步骤

1. **检查暂存区**：先跑 `git status` 和 `git diff --cached`，看清楚要提交的内容。如果暂存区是空的，告诉用户"没有已暂存的文件，先 `git add` 一下"，停下来等确认。

2. **分析变更**：根据 diff 内容判断这次提交的类型：
   - `feat`：新功能
   - `fix`：修复 bug
   - `docs`：文档变更
   - `refactor`：重构（不增加功能、不修 bug）
   - `test`：测试相关
   - `chore`：构建流程、工具配置等

3. **生成信息**：按下面格式写：

<类型>(<可选范围>): <一句话说清做了什么>

<可选正文：如果改动复杂，说明为什么这么改>

标题行不超过 72 个字符，用祈使句（"添加"而不是"添加了"）。

4. **给用户过目**：把准备好的 commit 信息展示出来，等用户确认或说"改一下"。

5. **执行提交**：用户确认后跑 `git commit -m "..."` 完成提交，回报 commit hash。

## 约束

- 不要帮用户 `git add .` 全量暂存，只对已暂存内容写信息。
- 不确定类型时选最接近的一个，告诉用户"我判断是 feat，如需改动告诉我"。
- 不写"update"、"fix bug"这类无信息量的信息。

这就是一个完整、可立刻抄用的 SKILL.md。长度适中，步骤清晰，有达标标准，有停止条件。

---

拆解：frontmatter 两个字段的作用

---
name: git-commit-guide
description: 当用户说"帮我提 commit"……
---

name 是这个 Skill 的唯一标识符，用在日志和引用里，跟目录名保持一致就行。

description 是模型决定要不要触发这个 Skill 的依据。这是整个 SKILL.md 最重要的一行——下一节专门讲怎么写好它。

---

正文的核心结构

好的 Skill 正文通常包含三层：

1. 任务总目标：你的任务是什么（一句话）。
2. 有序步骤：先做什么，再做什么，每步做到什么算过，什么情况停下来。
3. 约束条件：哪些事不能做，哪些判断要给用户而不是自己猜。

步骤不用多，3-6 步最好读。太长的 SKILL.md 会稀释重点——正文超过 600 字就该拆成两个 Skill 了。

---

第三步：放对位置，确认工具能发现

建好 SKILL.md 后，目录结构应该是：

your-project/
└── .claude/
    └── skills/
        └── git-commit-guide/
            └── SKILL.md

Claude Code 在每次会话启动时会扫描 .claude/skills/ 下的所有子目录，找到 SKILL.md 就读进来。不需要重启电脑，也不需要额外配置——下次在这个项目目录启动 Claude Code 就自动生效了。

如果你想让这个 Skill 在所有项目都可用，把整个 git-commit-guide/ 目录移到全局目录下（~/.claude/skills/ 或对应 Windows 路径）即可。全局 Skill 和项目 Skill 可以共存，触发时都会命中。

其他支持 Skills 体系的工具扫描路径可能不同，以各工具的官方文档为准。

---

第四步：触发验证——你应该看到什么

Skill 装好不等于 Skill 生效。必须跑一次验证，看到预期结果，才能确认它真的在工作。

步骤：

1. 在项目目录启动 Claude Code：

   claude
   

2. 做一点改动并暂存：

   echo "# test" >> README.md
   git add README.md
   

3. 在对话里说：

   > 帮我提 commit
   

你应该看到：Claude Code 先跑 git status、git diff --cached，然后给你生成一条符合约定式提交格式的信息，比如 docs(readme): 添加测试行，展示出来等你确认，而不是直接就 commit 了。

如果它按这个流程走了，你的第一个 Skill 就生效了。

如果没触发（它直接帮你 commit 了但没按规范、或者完全没有 Skill 的行为），先看下面的故障排查表。

---

description 怎么写才能被准确触发

这是新手写 Skill 最容易忽视的地方。

错误的写法：

description: git commit 助手

这种写法太短、太模糊。模型看到它，不知道什么时候该触发。

正确的写法：

description: 当用户说"帮我提 commit"、"提交一下"、"写个提交信息"、"git commit 帮我写"时使用。按约定式提交规范生成标准的 git commit 信息并执行提交。

正确写法的三个要素：

1. 触发条件用自然语言写出来，给几个用户实际会说的例子（比如"帮我提 commit"、"提交一下"）。因为用户表达方式五花八门，多举例让模型的模式匹配更准。

2. 说清楚这个 Skill 做什么，一句话总结交付物是什么。

3. 不要写成文档摘要，比如"这个 Skill 讲解了约定式提交规范"——那是给人看的；description 是给模型用来做匹配决策的，要写场景、写动作、写触发词。

总结成一句话：description 不是简介，是触发器，写给模型看的。

如果你有多个 Skill，description 要互相区分开。比如你有 git-commit-guide 和 write-pr-description，它们的触发场景不能重叠太多，否则模型会混淆，随机触发其中一个。

---

进阶：bundle 脚本和参考文件

当你的 Skill 需要引用一段代码模板、一份检查清单、或者一个脚本，可以把它们作为文件放在同一个目录里：

git-commit-guide/
├── SKILL.md
├── commit-types.md    ← 类型参考表，SKILL.md 里 include 进来
└── validate.sh        ← 可选的提交前检查脚本

在 SKILL.md 正文里，你可以直接引用这些文件的内容，比如：

提交类型对照见同目录的 `commit-types.md`，逐条比对后再做判断。

不过，bundle 文件不要塞太多。每个文件都会被读进上下文，上下文有限，关键信息会被稀释。一个 Skill 目录里放 1-2 个辅助文件是合理的，超过 5 个就要想想该不该拆 Skill 了。

SKILL.md 精简的原则：

• 一个 Skill 解决一个明确的场景，不要万能
• 步骤 3-6 条，每条 1-2 句话，够用就好
• 把"为什么这么做"的解释留给 README，不要堆进 SKILL.md 正文
• 约束条件列在最后，突出"不能做什么"比"能做什么"更重要

---

故障排查表

症状	原因	解法
说"帮我提 commit"，Skill 完全没触发，它直接就提了	description 写得太短或没有触发词	在 description 里加真实触发词，比如"帮我提 commit"、"提交一下"；保存后重新启动会话
Skill 触发了，但没按步骤走，直接就执行了	正文缺少「步骤 N 完成后等用户确认」之类的停止条件	在关键节点明确写"展示给用户，等确认后再执行"
有时触发有时不触发，不稳定	description 和另一个 Skill 的触发词重叠	检查所有 Skill 的 description，把重叠的触发词各自分清楚
SKILL.md 改了，但行为没变	旧会话还在用旧上下文	退出当前 Claude Code 会话，重新启动；或者在会话里用 /clear 清除上下文
多人协作，同事说"没触发你那个 Skill"	Skill 放在全局目录，没提交进代码库	如果是团队共享的 Skill，放进项目的 .claude/skills/，一起提交到 git
工具报错找不到 SKILL.md	目录结构写错，或文件名大小写不对	确认是 SKILL.md（全大写），且文件在 .claude/skills/<名字>/ 下

---

常见问题

Q：一个项目能有多少个 Skill？

没有硬性上限，但每个 Skill 都会被读进上下文，建议控制在 10 个以内。真正高频用到的才写成 Skill，偶发场景直接对话就够了。

Q：SKILL.md 写中文还是英文？

都可以。模型对中英文理解能力差不多。如果你的团队主要用中文，写中文更容易维护。如果要开源给多语言团队用，写英文。

Q：Skills 和 CLAUDE.md 有什么区别？

CLAUDE.md 是项目级的上下文说明（项目是什么、代码规范、注意事项），每次会话都读进来；Skills 是按需触发的，只在匹配到触发词时才生效。两者可以共存——大原则放 CLAUDE.md，具体流程和操作规范放 Skills。详细对比见 上下文是一切：引用规则。

Q：已经有 Skill 了，怎么让它在另一个项目也用？

两种方式：一是把 Skill 目录复制过去（不同项目各维护一份）；二是移到全局目录 ~/.claude/skills/，所有项目自动可用。团队共享建议用项目级，方便统一版本。

Q：可以在 Skill 里写条件判断吗，比如"如果是 Python 项目就…"？

可以，直接写在正文里，用自然语言描述就行，不需要代码。模型能理解"如果 diff 里有 .py 文件，则……"这类条件。更复杂的多步编排见 Skills 编排工作流。

---

下一步

第一个 Skill 跑通之后，自然会发现更多场景：写 PR 描述、生成代码注释、跑测试并报告结果……每一个重复了几次的场景都是一个潜在的 Skill。

• 想了解 Skills 和 MCP 的分工，用哪个什么时候用，去看 给 Agent 加能力的两条路：Skills vs MCP
• 想把这个 Skill 变成多步工作流（一句话跑完「提交+写 PR+关 issue」），去看 Skills 编排工作流
• 了解上下文和 CLAUDE.md 的关系，巩固基础，看 上下文是一切：引用规则
• 回到 AI 编程教程大全 看本阶梯其他节在哪里
• 查 Skills 术语解释 了解完整定义

---

👉 看看我们的 AI 编程实战体系课，或逛 AI 编程教程大全 把基本功打扎实。