[经验分享] 我的第一个 Skill

用过 Claude Code 的人都知道 / 斜杠命令能触发各种"技能"。但你知道这些 Skill 是怎么写出来的吗？本文带你从原理到实践，手把手创建属于自己的第一个 Skill。

---

一、Skill 到底是什么？

Skill 的核心原理：把复杂的任务，拆解成一个个简单可执行的小步骤，每个步骤都明确"需要准备什么（输入）"和"能得到什么（输出）"，再用标准化的逻辑，让这些步骤无缝衔接、可重复使用。

就像我们做一道番茄炒蛋：

步骤	输入	输出
备料	2 个鸡蛋、1 个番茄	番茄切块、蛋液打好
炒蛋	蛋液 + 热油	炒蛋成型
炒番茄	番茄块 + 热锅	番茄出汁
混合调味	炒蛋 + 番茄汁 + 盐	成品出锅

"番茄炒蛋 Skill"的原理就是：拆解步骤 → 明确每步的输入输出 → 用固定逻辑串联，确保每次做出来的味道都一致。

对应到 Claude Code 里，Skill 本质上就是一段结构化的提示词（Prompt）。你把它写好，Claude 在触发这个 Skill 时，就会严格按照你定义的步骤来执行任务——不再每次都要你重复描述需求，也不会遗漏关键步骤。

一句话总结：Skill = 你把"做事流程"写成文件，让 AI 照着做。

光说原理有点抽象。接下来通过我的第一个 Skill 示例“月报生成 Skill”——带你完整走一遍完成一个skill创造全流程。

---

二、第一个 Skill 做什么？

Skill 不需要太复杂。我的建议是：从你日常最烦的重复劳动开始。

问自己三个问题：

1. 哪些事情我每个月/每周都在重复做？
2. 这些事情的操作步骤是不是一样的？
3. 我能不能把模板/格式固定下来？

举几个真实的例子：

场景	重复点	Skill 能做什么
报账材料汇总	每次都要整理发票、填表、核对金额	给定输入（发票照片/列表），自动按固定格式生成汇总表
月报生成	每月从各渠道收集数据、写总结、调格式	给定数据源，按固定模板输出月报文档
踩坑指南文章	每次都是"问题→根因→方案→注意事项"的结构	给定问题描述，按标准模板生成文章骨架
代码审查清单	每次 CR 都要检查相同的项	按固定清单逐项审查，输出结构化报告

我选了什么：月报

我每个月都要做月报，流程雷打不动：

下载最新日报到本地
    → 跑 Python 脚本，从日报里提取本月按项目汇总的工作内容
    → 把"提示词 txt + 月报模板 + 近三个月月报 + 本月工作内容"打包发给网页端大模型
    → 把生成的内容复制到 Word，手动调格式（第二耗时）
    → 逐章调整内容措辞（第一耗时）
    → 通读检查

每次花费我至少半小时时间（而且已经是精简过的流程），最耗时的不是"写内容"本身，而是调word格式和逐章打磨措辞——重复、机械、让人不想动手。

除了"下载日报"和"最终通读"这两步，中间的部分我全想让 Skill 帮我做。

---

三、怎么写？

3.1 Skill 需要哪些文件？

一个 Skill 的文件结构非常简单：

my-skill/                  # Skill 文件夹（文件夹名 = Skill 名）
└── skill.md               # 核心文件：Skill 的定义（必须有）

没错，最少只需要一个 skill.md 文件。如果你的 Skill 需要额外的模板文件、示例数据，也可以放在同一个文件夹下：

my-skill/
├── skill.md               # Skill 定义
├── template.md            # 输出模板（可选）
└── examples.md            # 示例数据（可选）

我的月报 Skill 最终结构：

.claude/skills/monthly-report/
├── SKILL.md              # Skill 主文件（触发规则 + 8 章生成逻辑 + 格式规范）
└── project_roles.yaml    # 项目角色映射（我来维护）

除了核心文件，还多了一个 YAML 配置文件——用来记录"每个项目我负责什么角色"，解决月报里按项目维度组织内容的细节问题。后面会讲到它是怎么来的。

3.2 Skill 文件放在哪？

Claude Code 会在两个位置查找 Skill：

级别	路径	适用场景
用户级	~/.claude/skills/<skill-name>/skill.md	你在所有项目中都想用的 Skill
项目级	<项目根目录>/.claude/skills/<skill-name>/skill.md	只在特定项目中使用的 Skill

新手建议：先放在用户级目录下，这样在任何项目里都能调用。比如你的 Skill 叫 pitfall-writer，就创建文件：

• Windows: C:\Users\你的用户名\.claude\skills\pitfall-writer\skill.md
• macOS/Linux: ~/.claude/skills/pitfall-writer/skill.md

3.3 skill.md 长什么样？

skill.md 由两部分组成：头部元数据（YAML frontmatter） + 正文指令（Markdown body）。

以我的月报 Skill 为例，结构大致如下（已脱敏）：

---
name: monthly-report
description: 根据日报数据和工作记录，按固定模板生成月度工作报告 .docx 文件
---

# 月报生成 Skill

当用户提供月份信息时，自动采集数据并按模板生成月报。

## 工作空间
- 根目录：xxx

## 数据提取

1. **采集数据**：运行 `data_extract.py` 从日报 Excel 提取本月工作内容
2. **读取 Git log**：从各项目目录抓取本月提交记录，补充项目外工作
3. **交互确认**：询问用户加班时长、问题建议、项目角色是否有变化

## 生成规则

按以下 8 个章节依次生成内容：
- 工作小结：多段结构，按项目维度组织
- 工作强度：6 个标准分类，结合加班时长
- 阶段重点工作：按角色区分写法
- ...（其余章节略）

## 输出格式

直接输出 .docx 文件，格式要求：
- 标题居中 14pt，章节标题 11pt 加粗
- 正文 11pt，内容缩进 2 字符
- 特定段落标签加粗，正文不加粗

## 注意事项

- 不确定的信息主动询问用户，不要自行编造
- 第六章（具体工作完成情况）不得与第三章（阶段重点工作）重复
- 下月计划只写进行中的项目，已结项的不写

## 输出示例

xxx

拆解一下关键要素：

要素	位置	作用
name	头部 YAML	Skill 的唯一标识，用小写 + 短横线（kebab-case）
description	头部 YAML	一句话描述 Skill 做什么，Claude 根据它判断何时触发
执行步骤	正文	告诉 Claude 分几步走、每步做什么
输出格式	正文	约束输出的格式和质量标准
注意事项	正文	兜底规则，防止 Claude "自由发挥"跑偏

关键心得：description 写得越准确，Claude 自动触发 Skill 的命中率就越高。写得太模糊（比如"处理文档"），Claude 可能在你需要的时候不触发，不需要的时候乱触发。

3.4 借助 AI 快速创建（实战过程）

理论上你可以从零手写 skill.md，但实际上让 Claude 帮你写才是正解。关键不是"怎么写文件"，而是"怎么让 Claude 理解你要做什么"。

下面完整还原我做月报 Skill 的过程：

第一步：让 Claude 先看懂你的材料

我把所有相关材料（提示词 txt、月报模板、历史月报文件、数据提取脚本）都放在同一个文件夹里，然后跟 Claude Code 说：

"我需要你根据这个目录中的材料生成一个月度自评的 Skill。需要我告诉你什么吗？比如我通常的操作流程？"

为什么要先让 Claude 分析目录？ 因为你平时积累的提示词、模板、历史产出本身就是最好的"需求文档"。让 Claude 先看这些材料，它生成的 Skill 会更贴合你的实际情况，而不是凭空猜测。

第二步：回答 Claude 的确认问题

Claude 看完材料后，主动问了我几个关键问题：

Claude 的问题	我的回答
这个 Skill 的覆盖范围是什么？	分成两个 Skill 来做
生成月报时，数据来源是怎么获取的？	需要我去网上下载最新日报，再用 data_extract.py 跑出来
生成文档时，希望直接产出 .docx 还是只生成文本？	先出文本，再出 docx

经验之谈：不要急着回答，先看看 Claude 的理解有没有偏差。如果有，及时纠正。这个"对齐"过程花不了几分钟，但能避免后面大量返工。

第三步：第一版——能跑就行

Claude 生成第一版后，我跑了一遍，发现只生成了纯文本，没有 docx 文件。而我想直接在 Word 里看效果，不想要自己手动复制粘贴。

于是我让 Claude 改成直接输出 .docx。它给了一版，但我打开一看——格式完全不对：字号、缩进、加粗都跟我之前的月报不一样。

我让它参考我之前提供的月报材料来统一格式，比如：

• 标题居中 14pt
• 章节标题 11pt 加粗
• 正文 11pt，内容缩进 2 字符
• 特定段落标签加粗，正文不加粗

有了真实参照物之后，格式就基本到位了，后续只微调了一些加粗和缩进的细节。

教训：第一版先求"能用"，不要指望一步到位。格式问题拿真实样本给 Claude 看，比口头描述"标题大一点、正文缩进"高效得多。

第四步：逐章打磨内容规则

格式 OK 了，接下来是最耗时的部分——内容规则。

我的月报包含 8 个章节，每个章节写法都不一样：

1. 个人工作小结：多段结构，开头结尾要灵活
2. 工作强度情况：6 个标准分类，需要交互式询问加班时长
3. 阶段重点工作：按角色区分写法，且不能和第六章重复
4. 创新学习：需要明确的判断标准（什么算创新，什么不算）
5. 服务支撑：以报账、月报 PPT 等固定内容为主
6. 具体工作完成情况：需要合并规则，统一描述粒度
7. 问题及建议：先问用户有没有，没有的话给出候选
8. 下月计划：按项目状态筛选（进行中的要写，已结项的不写）

我的做法是：让 Claude 先分析现有月报有什么问题，然后对照模板一条一条过。一般是它提建议，我提问题和确认。

在这个过程中，我们发现有些章节需要知道"我在某个项目中承担什么角色"，于是新增了一个 project_roles.yaml 配置文件来维护项目-角色映射。Skill 在生成对应章节时会自动读取这个文件。

感受：这个过程不像"写代码"，更像教新员工做事——你先给个大框架，他做一遍，你发现哪里不对就补充细节，反复几轮后规则就稳定了。

3.5 迭代优化的真实路径

第一版 Skill 几乎不可能完美，你需要边用边改。回顾我的迭代过程：

阶段	发现的问题	怎么改的
第一版	只出文本，没有 docx	加上 docx 输出逻辑
第二版	docx 格式跟已有月报不一致	让 Claude 参考历史月报统一格式
第三版	部分章节内容太泛，没有区分度	逐章调整生成规则（8 章各写各的逻辑）
第四版	有些项目角色信息缺失	新增 project_roles.yaml，Skill 自动读取
第五版	某些信息无法自动获取（加班、问题建议）	加入 3 个交互确认点

几个通用的迭代经验：

问题现象	调整方式
输出格式不稳定	在正文中给出更具体的输出模板或示例
有些步骤被跳过	把步骤编号写得更明确，加"必须按顺序执行"的约束
Claude 自由发挥太多	加"注意事项"约束边界，明确"不要做什么"
触发不灵敏	优化 description，让它更精确地匹配使用场景

---

四、数据从哪来？

Skill 规则写得再好，没有数据也生不出内容。这是很多人写 Skill 时容易忽略的问题：规则是骨架，数据才是血肉。

4.1 我的数据困境

月报里很多内容都要从日报上获取。我原来的做法是：手动从内部系统下载日报 Excel → 跑 Python 脚本提取 → 喂给 Skill。

这有两个问题：

1. 日报是以项目为维度写的，有些工作跟项目没关系——比如我在学一项新技术、做了一个提效工具、或者写了这个 Skill 本身——这些内容日报里不会出现
2. 有时候自己总结的日报内容太过简略，到最终汇总月报是又觉得缺乏细节。

如果领导没要求汇报这类工作，是不是就不写了？但从完整记录的角度，这些也是有价值的工作内容。靠日报只能覆盖"项目内工作"，项目外的工作会被遗漏。

4.2 找到已经在产生的数据

但我不想做一套日报系统，新建立一个复杂的习惯不容易，但是抓取已经在产生的数据源很简单。

然后我注意到了——Git 提交日志。

我们每天都在写代码，每个项目的 git log 本身就是一份现成的工作记录。那些不在日报里出现的工作——重构代码、研究新技术、写工具脚本——只要你有 commit，就留下了痕迹。

不需要额外的纪律，只需要一个微小的习惯调整：下班前，在每个项目目录跑一下 git add -A && git commit -m "今天做的事"。

消息不用规范，想到什么写什么。不要求每个改动都单独 commit，一天一个就够。

4.3 让 Skill 自动读取 Git log

我把各项目路径告诉了 Claude Code，让它帮我做两件事：

1. 一个快速 commit 脚本——一键提交所有项目，省去每个目录都跑一遍的麻烦
2. 更新月报 Skill——加入 Git log 读取逻辑，自动从各项目提取当月提交记录

更新后的 Skill 在生成月报时，会同时从日报和 Git log 两个渠道采集数据，交叉补充。

4.4 最终的数据采集链路

经过这一轮优化，月报 Skill 的数据来源变成了三层：

团队日报 Excel → 项目维度的工作汇总（主要数据源）
        +
各项目 Git log → 补充工作（重构、工具开发、技术学习等）
        +
交互环节确认  → 兜底（加班时长、开会、培训等无法自动采集的内容）
        =
完整月报

Skill 运行时会依次问你三件事：

1. 本月有加班吗？ → 有就说时长，没有就说没有
2. 本月有什么问题或建议？ → 有就说，没有的话 Skill 会根据月报内容给出 2-3 条候选供你选
3. 项目角色配置需要调整吗？ → 有新项目或角色变化就说，没有就确认

关键认知：最好的数据采集不是"额外做事"，而是找到已经在产生的数据。Git log、日报、工作记录——这些你本来就在产生的东西，稍加整理就是最好的数据源。

---

五、怎么用？

5.1 使用自己创建的 Skill

创建好 skill.md 后，重新启动 Claude Code（或刷新 Skill 列表），你的 Skill 就会自动出现：

# 方式一：查看所有可用 Skill
/skills

# 方式二：直接调用（输入 / + Skill 名称）
/monthly-report

# 方式三：在对话中直接说"帮我生成X月月报"，Claude 也会自动触发

5.2 我的月报生成流程

实际使用时，整个流程变成了这样：

步骤	操作	耗时
1. 下载日报	从内部系统下载最新日报 Excel，放到指定目录	1 分钟
2. 调用 Skill	在 Claude Code 里输入 /monthly-report X月	几秒
3. 回答问题	Skill 依次问你 3 个问题（加班、建议、角色）	1 分钟
4. 查看草稿	Skill 自动生成 _草稿.docx，用 Word 打开修改	看情况

从原来半小时以上，缩短到 5 分钟左右——而且省掉的全是最烦的"调格式+想措辞"的部分。

5.3 安全使用别人的 Skill

社区中有不少人会分享自己写的 Skill。使用前请注意以下几点：

检查项	为什么重要
读一遍 skill.md 全文	Skill 本质是提示词，看看它是否会让 Claude 执行你不想要的操作（如读取敏感文件、发送网络请求）
确认没有 rm、del、curl 等危险指令	恶意的 Skill 可能包含删除文件或上传数据的指令
先在测试目录中试用	不要直接在重要项目中运行，先用空目录跑一遍看看行为
检查是否引用了外部脚本	如果 Skill 文件夹中有 .sh、.py 等脚本文件，务必审查其内容

原则：Skill 文件是纯文本，你一定能读懂。看不懂的就不要用——这和"不要运行你看不懂的 shell 命令"是一个道理。

5.4 公开分享你的 Skill

当你的 Skill 打磨成熟后，可以通过以下方式分享：

方式	操作方法	适合场景
GitHub 仓库	把 Skill 文件夹推送到公开仓库，别人 clone 到自己的 ~/.claude/skills/ 下	最推荐，方便版本管理和更新
博客/文档	直接贴出 skill.md 内容，读者自行复制	配合教程文章（比如本文）
项目内置	把 Skill 放在项目的 .claude/skills/ 目录下并随代码提交	团队内部共享，成员 clone 后自动获得

---

六、总结

回顾整个过程，创建 Skill 的核心路径是这样的：

从重复任务开始 → 让 AI 分析你的现有材料 → 边用边改 → 找到数据源，让采集自动化

几个核心认知：

1. Skill 不是代码，是"做事流程的文本化"。不需要会编程，能写清楚步骤就行。
2. 一个 skill.md 文件就能跑。不用搭环境、不用装依赖。
3. 先求跑通，再求完美。我的第一版连 docx 都没有，迭代了五六版才稳定。
4. description 是关键。写好了描述，Skill 才能在该触发时触发。
5. 数据源比规则重要。规则写得再好，没有数据也白搭。优先找到"已经在产生的数据"（Git log、日报、工作记录），比手动输入高效得多。
6. 保持维护。 写好的skill也不是一成不变的，后续根据变化要主动进行优化