---
title: "五分钟做第一个 Skill"
wiki: skills
category: "构建指南"
slug: M01-五分钟做第一个Skill
url: https://learnagent.wiki/skills/cards/M01-五分钟做第一个Skill
tags: ["Skill", "上手", "实战", "第一个 Skill"]
last_updated: 2026-04-11
reading_time: 32
---

> > 模块1：一文带你看懂，5分钟搞定你的第一个 Skill | 用时：约 5~10 分钟 | 目标：做出一个能直接用的 Skill

# Skill 从小白到高手系列课

> 模块1：一文带你看懂，5分钟搞定你的第一个 Skill | 用时：约 5~10 分钟 | 目标：做出一个能直接用的 Skill

---

想象一下这个场景：

你刚开完周会，领导说"下班前把周报交一下"。你打开 AI，开始输入：

> "帮我写个工作周报，要有本周完成情况、下周计划、遇到的问题，格式用表格，任务前面带勾选框，下周计划分 P0/P1/P2 优先级......"

这段话，你上周说了一遍，上上周又说了一遍。

说实话，写到第三遍的时候，你已经不是烦 AI 了——你是烦自己。为什么每次都要重新描述一遍格式？为什么 AI 就是记不住我想要什么？

好问题。

这就是我们今天要解决的：用 5 分钟，做一个属于你自己的 Skill。以后你只需要说"帮我写周报"，剩下的全自动化。

话不多说，开始吧。

---

## 你是不是也有这个烦

做 Skill 之前，先确认一下你有没有经历过下面这些崩溃时刻。

### 自媒体人——每次都要重新对"风格"

写小红书的人都知道，那个格式特别固定：标题要用 emoji 开头，正文要口语化像跟朋友聊天，300 字左右，末尾还要带 5-8 个话题标签。

但就是这个固定格式，你每次都得重新跟 AI 说一遍。

**不用 Skill 的时候：**

```
你：帮我写一篇小红书笔记，主题是咖啡种草

AI：好的，需要什么风格？

你：标题用 emoji 开头，正文口语化，300 字左右，带话题标签

AI：好的，以下是...

你：等等，标签不够，要多加几个

AI：好的，增加了标签

你：还有，语气再活泼一点，像闺蜜推荐那种
```

来回三四轮，还是不满意。

你可能会问：那我直接把这段话保存下来，下次复制粘贴不就行了？

好问题。但你会发现，每次粘贴完还要根据具体主题调整，而且 AI 还是经常"失忆"——因为它每次都是从零开始理解你的需求。

---

### 产品经理——PRD 模板每次都要重新贴

每个公司的 PRD 格式不一样，每个团队的偏好也不一样。你每次打开 AI，都得先把你们公司的 PRD 模板贴一遍。

> 你：帮我写一个 PRD，格式是背景、用户故事、功能需求、非功能需求、验收标准......
>
> AI：好的，请问功能需求和非功能需求的边界是什么？
>
> 你：（这是你第四次解释了）

等你说完，咖啡都凉了。

---

### 开发者——commit message 每次都要想格式

commit message 要遵循规范，code review 要检查特定规则，部署 checklist 每次都要过一遍。

> 你：帮我写个 commit message，格式是 type(scope): description......
>
> AI：好的，请问 scope 填什么？
>
> 你：……你看看我改了哪个文件不就知道了？

来回 4 轮，就为了一个 commit message。

---

### 设计师——架构图画了又画，每次提示词从头重复

"用 Mermaid 语法、从左到右的流向、不同颜色区分内部和外部组件、数据库用圆柱体"——说过不下十遍。

更惨的是，你终于调出了一个特别满意的版本，但下次再想复现——对不起，上次的提示词没保存。

---

### 学生——论文格式每次都要解释半天

引用格式用 APA 还是 GB/T 7714？图表标题在上面还是在下面？摘要要不要英文版？

不同课的老师格式要求还不一样。你跟 AI 每次都得先确认是"哪个老师的哪个格式"。

---

### 电商运营——每周的销售报告格式都一样，但每次都要重新描述

"要环比数据、要同比对比、要 TOP10 排行、要趋势图"——这周说完，下周还得再说。

> 你：这周报我每周都在写，为什么每次都要重新确认？

---

如果你有上面任何一种经历，Skill 就是为你解决这个问题的。

说白了，**Skill 就是给 AI 的一本操作手册。你写一次，它以后就照着做。**

---

## 先选一个你要做的

你做 Skill 的第一步不是学语法，而是想清楚你要解决什么重复劳动。

你看一下哪个跟你最相关：

- 写小红书笔记（自媒体人首选）
- 写公众号文章（自媒体/运营）
- 写 PRD 需求文档（产品经理）
- 画架构图（开发/设计）
- 写学术论文摘要（学生）
- 社交消息回复（所有人）
- 写 commit message（开发者）
- 写电商周报（电商运营）
- 写 Docker 部署配置（DevOps）
- **去除 AI 写作痕迹（内容创作者新宠）**

选好了吗？下面我以"周报生成助手"为例，手把手带你做。如果你选了别的场景，做完之后我会告诉你怎么改成你需要的。

> **真实案例预览**：社区里有个爆火的 Skill 叫 `avoid-ai-writing`，专门帮内容创作者去除 AI 写作痕迹。它只有一个 SKILL.md 文件，但收获了 **887** 个 Stars。这说明什么？**最简单的单文件 Skill 也能创造巨大价值**。后面模块 5B 我会完整拆解它。

---

## 创建你的第一个 Skill

Skill 的结构特别简单——一个文件夹，里面放一个 Markdown 文件，就够了。

先在你项目的根目录下创建这个结构：

```
你的项目/
└── .claude/
    └── skills/
        └── weekly-report/
            └── SKILL.md
```

等等，`.claude` 目录你可能没有。没关系，手动创建就行。Windows 上用资源管理器建文件夹，Mac/Linux 用终端：

```bash
mkdir -p .claude/skills/weekly-report
```

然后在 `weekly-report` 文件夹里创建一个文件，名字必须是 `SKILL.md`（大写 S 和大写 MD），把下面的内容复制进去：

```yaml
---
name: weekly-report
description: "生成标准化的工作周报。当用户需要写周报、写工作总结、生成周报模板、本周工作回顾时使用。输出包含：本周完成、下周计划、遇到的问题、核心数据。"
---

## 输出格式

### 本周核心指标（自动填充）
| 指标 | 本周数据 | 上周数据 | 环比 |
|------|----------|----------|------|
| 任务完成数 | [ ] | [ ] | [ ]% |
| 代码提交数 | [ ] | [ ] | [ ]% |
| 文档产出数 | [ ] | [ ] | [ ]% |

### 本周完成（带勾选框）
- [ ] [任务描述] — 完成情况（如：已完成/进行中/延期）
- [ ] [任务描述] — 完成情况
- [ ] [任务描述] — 完成情况

### 下周计划（带优先级）
- [P0] [最重要的事] — 预期产出
- [P1] [次要任务] — 预期产出
- [P2] [可选任务] — 预期产出

### 遇到的问题与风险（选填）
| 问题描述 | 影响 | 解决方案 | 需协助 |
|----------|------|----------|--------|
| [问题] | [高/中/低] | [方案] | [是/否] |

### 本周总结（一句话）
[用一句话概括本周核心进展或感悟]

## 操作步骤
1. 询问用户本周的主要工作内容（可让用户简要列举）
2. 自动填充表格结构，留出空白让用户填写数据
3. 生成带勾选框的待办格式，方便用户后续勾选
4. 输出 markdown 格式的周报，可直接粘贴到文档或邮件
```

就这些。你已经做完一个 Skill 了。

我知道你可能有点懵——这就完了？对，这就完了。让我花点时间解释一下你刚才复制的那段东西到底是什么，每个部分起什么作用。

---

## 你刚才复制的东西是什么

这个文件分成两部分。

上半部分被 `---` 包围的，叫 YAML 头部，也叫 frontmatter。这里面只有两个字段是必须的：

### name：这个 Skill 的身份证号

name 是这个 Skill 的名字。有严格的命名规则：

只能用小写字母、数字和连字符（就是键盘上 0 右边那个短横线）。不能大写，不能用下划线，不能用中文，不能有空格。

而且文件夹的名字必须和 name 一模一样。你创建的文件夹叫 `weekly-report`，name 就得写 `weekly-report`，差一个字母都不行。

举几个正确的例子：`weekly-report`、`prd-generator`、`commit-message-writer`。

举几个错误的例子：`WeeklyReport`（不能大写）、`weekly_report`（不能用下划线）、`周报生成器`（不能用中文）、`-weekly`（不能以连字符开头）。

还有一条：name 的长度不能超过 64 个字符。不过一般你也用不到那么长的名字。

### description：这个 Skill 最关键的字段

description 是 AI 决定"什么时候该用这个 Skill"的唯一依据。你可以把它理解成给 AI 看的搜索关键词——用户说的话跟 description 里的内容匹配上了，AI 就会激活这个 Skill。

所以你看我写的 description："当用户需要写**周报**、**工作总结**、**生成周报模板**时使用"——我故意塞了好几个触发词。因为用户可能会说"帮我写个周报"，也可能说"帮我总结一下这周的工作"，还可能说"给我个周报模板"。如果 description 里没有这些词，AI 就匹配不上，Skill 就不会触发。

这是大多数人做 Skill 后遇到的第一个问题：Skill 做好了，但 AI 就是不用。90% 的情况都是 description 里的触发词不够多。后面模块 3 会专门讲怎么调这个，现在你只要记住一个原则：**description 里多写几个用户可能说的词，宁多勿少。**

description 的字数上限是 1024 个字符。对于大多数 Skill 来说，100-300 个字符就够了。写太短匹配不到，写太长反而会稀释关键词的密度。关键是把"做什么"和"什么时候用"都写清楚，触发词一个不漏。

### 正文：给 AI 的操作指令

`---` 结束之后的部分就是正文了。`## 输出格式` 开始的内容，是你给 AI 的操作指令。

用大白话写就行，告诉 AI 你要什么格式、按什么步骤做、输出什么样式。这就是 AI 激活你的 Skill 之后会读到的内容。

正文没有字数限制，但建议控制在 500 行以内（大约 5000 token）。太长的正文会浪费上下文空间。如果内容确实很多，可以把详细部分拆到 references/ 目录下的独立文件里——但这是进阶用法，现在你不需要管。

---

## 放到正确位置然后测试

文件创建好了，还得放对位置 AI 才能找到。

Skill 有两个存放位置：

**项目级**：`.claude/skills/`——只在当前项目生效。比如你有个博客项目，博客相关的 Skill 放这里。换个项目就不会出现。

**用户级**：`~/.claude/skills/`——对你所有项目都生效。比如你做了一个 commit message 的 Skill，不管在哪个项目里提交代码都想用，就放这里。

`~` 是你的用户目录。Mac 上是 `/Users/你的用户名`，Windows 上是 `C:\Users\你的用户名`。所以用户级 Skill 的完整路径是 `C:\Users\你的用户名\.claude\skills\`。

现在先放项目级就行。确保你的目录结构长这样：

```
你的项目/
└── .claude/
    └── skills/
        └── weekly-report/
            └── SKILL.md    ← 文件在这个位置
```

注意是三层：`.claude` → `skills` → `weekly-report` → `SKILL.md`。不是两层，不是直接把 SKILL.md 放在 skills 目录下。

放好后，**重启 Claude Code**。这一步不能省，因为 AI 是在启动的时候扫描 skills 目录的。你加了新文件，它不知道，得重启才能发现。

重启后，试试输入："帮我写一下这周的工作周报"。

如果一切正常，你会看到 AI 自动生成了一份**结构化周报**，大概长这样：

```markdown
### 本周核心指标（自动填充）
| 指标 | 本周数据 | 上周数据 | 环比 |
|------|----------|----------|------|
| 任务完成数 | [ ] | [ ] | [ ]% |
| 代码提交数 | [ ] | [ ] | [ ]% |

### 本周完成（带勾选框）
- [ ] 完成用户登录模块开发 — 已完成
- [ ] 编写 API 接口文档 — 进行中
- [ ] 修复订单结算 bug — 已完成

### 下周计划（带优先级）
- [P0] 完成支付接口对接 — 预期产出：可正常发起支付
- [P1] 优化首页加载速度 — 预期产出：首屏加载 < 1s

### 遇到的问题与风险
| 问题描述 | 影响 | 解决方案 | 需协助 |
|----------|------|----------|--------|
| 第三方 API 响应慢 | 高 | 增加缓存机制 | 是 |

### 本周总结
[用一句话概括本周核心进展或感悟]
```

你会发现，**表格结构、勾选框、优先级标记、风险表格**——全部自动完成。你不需要解释"周报要有哪些模块"，AI 已经从你的 Skill 里学会了。

---

## 这和你不用 Skill 有什么区别？

不用 Skill 的时候，你说"帮我写个周报"，AI 会给你一大段文字，没有结构，没有表格，你得自己整理格式。

用了 Skill 之后，AI 直接给你一份**可以直接复制粘贴到文档的标准化周报**——带表格、带勾选框、分模块，你只需要填空就行。

**为什么选周报作为第一个 Skill？**

周报是典型的**中自由度**任务——有固定结构（表格、勾选框），但内容需要灵活生成。这正好展示 Skill 的核心价值：把"每次都要重新描述格式"变成"一句话触发标准模板"。

| 维度 | 不用 Skill | 用 Skill |
|------|-----------|----------|
| 启动成本 | 每次描述格式（3-5分钟） | 一句话触发 |
| 输出稳定性 | 格式不统一，每次不一样 | 固定模板，填空即可 |
| 协作性 | 团队各人格式不一 | 统一标准，可直接复用 |

---

## 想换场景？改三行就够

你刚才做的是周报 Skill。但如果你想做一个公众号写作的 Skill，不用从头来。

把 `weekly-report` 文件夹复制一份，改个名字叫 `wechat-article-writer`。然后打开里面的 SKILL.md，改三个地方：

**name 改成：**
```
name: wechat-article-writer
```

**description 改成：**
```
description: "生成微信公众号文章。当用户需要写公众号、微信公众号、推文、文章时使用。输出800-1500字，包含标题、正文、摘要。"
```

**正文部分改成：**
```markdown
## 写作风格
- 标题：数字+痛点驱动，25字以内
- 开头：场景代入，前3句抓住读者
- 正文：分段清晰，每段2-4行，适当加粗关键句
- 结尾：互动引导+公众号引流
- 总长度：800-1500字

## 操作步骤
1. 理解用户想写的主题
2. 生成3个备选标题供选择
3. 按选定标题写正文
4. 生成100字以内摘要
```

**别忘了文件夹名字也要改。** 文件夹叫 `wechat-article-writer`，name 也叫 `wechat-article-writer`，两个必须一致。

重启 Claude Code 后，试试说"帮我写一篇关于远程办公的公众号文章"。AI 就会用你新的 Skill 来输出。

其他场景也一样——核心就是改 name + description + 正文。模板是复用的，内容是替换的。你不需要重新学任何东西，只是换了"填空题的答案"。

---

## 9 个场景的 description 模板（直接复制用）

如果你想快速换场景，这里给你 9 个现成的 description 参考，覆盖 9 类用户画像：

### 1. 周报/工作总结
```yaml
name: weekly-report
description: "生成标准化的工作周报。当用户需要写周报、写工作总结、生成周报模板时使用。输出包含：本周完成、下周计划、遇到的问题、核心数据。"
```

### 2. 自媒体人——公众号文章
```yaml
name: wechat-article-writer
description: "生成微信公众号文章。当用户需要写公众号、微信公众号、推文、文章时使用。输出800-1500字，包含标题、正文、摘要。"
```

### 3. 产品经理——PRD 需求文档
```yaml
name: prd-generator
description: "生成标准产品需求文档。当用户需要写PRD、产品需求文档、功能规格说明、需求说明时使用。输出包含：背景、用户故事、功能需求、非功能需求、验收标准。"
```

### 4. 开发者——代码审查
```yaml
name: code-reviewer
description: "执行标准代码审查。当用户需要code review、代码审查、检查代码质量、review PR时使用。输出结构化审查报告，包含问题分级和修改建议。"
```

### 5. 设计师——架构图生成
```yaml
name: architecture-diagram
description: "生成精美软件架构图。当用户需要画架构图、系统图、流程图、技术方案图、时序图时使用。使用Mermaid语法输出。"
```

### 6. 学生——论文摘要
```yaml
name: academic-abstract-writer
description: "生成学术论文摘要。当用户需要写论文摘要、学术摘要、abstract、论文总结时使用。输出符合学术规范，包含研究背景、方法、结果、结论。支持APA/IEEE/GB7714格式。"
```

### 7. 电商运营——周报生成
```yaml
name: ecommerce-weekly-report
description: "生成电商运营周报。当用户需要写周报、销售报告、运营周报、数据周报时使用。输出包含：核心指标概览、环比同比分析、TOP10商品排行、下周计划。"
```

### 8. 社交场景——消息回复
```yaml
name: social-reply-helper
description: "帮你写得体的社交回复。当用户需要回复消息、社交回复、微信回复、不知道怎么回复时使用。根据关系亲疏自动调整语气。"
```

### 9. DevOps——部署配置
```yaml
name: deploy-config-generator
description: "生成部署配置文件。当用户需要写docker-compose、Dockerfile、CI/CD配置、部署脚本、Nginx配置时使用。输出生产级别配置，包含健康检查和日志配置。"
```

把对应的正文也换成你自己需要的内容就行了。

---

## 三个完整的改法示例

光看 description 可能还不够直观，我挑三个常见场景，从文件夹命名到完整 SKILL.md 内容全部给你写出来。你照抄改改就能用。

### 学生场景——论文摘要助手

文件夹名：`academic-abstract-writer`

完整 SKILL.md 内容：

```yaml
---
name: academic-abstract-writer
description: "生成学术论文摘要。当用户需要写论文摘要、学术摘要、abstract、论文总结、开题报告摘要时使用。输出符合学术规范，包含研究背景、方法、结果、结论。支持APA/IEEE/GB7714格式。"
---

## 写作风格
- 语言：严谨学术用语，避免口语化表达
- 结构：研究背景（2-3句）→ 研究方法（2-3句）→ 主要结果（2-3句）→ 结论（1-2句）
- 关键词：3-5个，中英文对照
- 总长度：300-500字（中文）或 200-300 words（英文）

## 操作步骤
1. 询问用户的研究主题和学科领域
2. 确认格式要求（APA/IEEE/GB7714/其他）
3. 生成摘要初稿
4. 生成中英文关键词
5. 如有参考文献，按指定格式排列

## 反模式
- 不要使用"我认为""我觉得"等主观表述
- 不要超过500字
- 不要使用感叹号
- 关键词不要超过5个
```

你看，正文部分比周报那个多了"反模式"这一栏。告诉 AI 不要做什么，跟告诉它要做什么一样重要。学术写作里最怕 AI 突然冒出一句"我觉得这个研究特别有意思"——加上反模式就能避免。

### 社交场景——消息回复助手

文件夹名：`social-reply-helper`

完整 SKILL.md 内容：

```yaml
---
name: social-reply-helper
description: "帮你写得体的社交回复。当用户需要回复消息、社交回复、微信回复、不知道怎么回复、帮我想想怎么回、怎么回复领导时使用。根据关系亲疏自动调整语气。"
---

## 判断逻辑
根据对方身份自动选择语气：
- 领导/上级：尊重但不卑躬屈膝，简洁有力，主动给出时间节点
- 同事：友好专业，不越界，避免过度承诺
- 客户：热情但不油腻，突出价值，及时响应
- 朋友/家人：轻松自然，可以开玩笑
- 不确定的对方：礼貌得体，不站队，不表态

## 操作步骤
1. 用户提供对方的消息内容和双方关系
2. 生成3个备选回复（不同语气强度）
3. 用户选择或要求调整

## 输出格式
每个回复标注适用场景，比如"适合关系一般的同事""适合比较熟的领导"

## 反模式
- 不要替用户做承诺（如"我明天一定完成"）
- 不要主动道歉除非用户要求
- 不要加表情包（除非对方先用了）
- 每个回复不要超过3句话
```

这个 Skill 的特色在于"判断逻辑"——让 AI 先判断对方是谁，再决定用什么语气。你在正文里把分类规则写清楚，AI 就不会对领导用开玩笑的语气了。

### DevOps 场景——部署配置生成器

文件夹名：`deploy-config-generator`

完整 SKILL.md 内容：

```yaml
---
name: deploy-config-generator
description: "生成部署配置文件。当用户需要写docker-compose、Dockerfile、CI/CD配置、部署脚本、Nginx配置、K8s配置、容器编排时使用。输出生产级别配置，包含健康检查和日志配置。"
---

## 生成原则
- 所有服务必须设置 restart: unless-stopped
- 必须包含健康检查（healthcheck）
- 必须配置日志驱动和日志轮转
- 端口映射使用环境变量，不硬编码
- 数据持久化使用 named volume，不用 bind mount
- 每个服务限制内存和CPU上限

## 输出格式
1. 配置文件完整内容
2. 需要的 .env 变量列表
3. 启动命令和验证方法
4. 注意事项（安全相关）

## 反模式
- 不要用 latest 标签，必须指定具体版本
- 不要暴露数据库端口到公网
- 不要在配置文件里写明文密码
- 不要省略健康检查
```

这个 Skill 的关键是"生成原则"——相当于给 AI 划了红线。它生成的配置文件会自动带健康检查、日志轮转、资源限制，这些是你每次手动写 docker-compose 都容易忘的东西。反正我每次都会忘。

三个场景看下来你应该发现了：不管什么场景，SKILL.md 的骨架都是一样的。name + description + 正文，正文里写风格/规则 + 步骤 + 反模式。你把内容换成自己的，其余结构照搬就行。

---

## 刚才到底发生了什么

你可能好奇，为什么只放了一个 Markdown 文件，AI 就"学会"了写周报。

其实 AI 并不是真的学会了什么。它做的事情可以用三步描述：

**第一步：启动时扫描。**

AI 启动的时候，扫描 `.claude/skills/` 目录，读每个 SKILL.md 的 name 和 description。注意它只读这两行，不读正文。每个 Skill 的 name + description 大概占 100 个 token。

如果你装了 20 个 Skill，这一步总共才占 2000 个 token。和你打一段话差不多。

我打个比方。你有一个书架，上面放了20本书。每本书的封面只印了书名和一句话简介——比如"《周报生成指南》：帮你快速写工作周报"。你不用翻开每一本书，光看封面就知道每本书是干什么的。AI 启动时做的事就跟你扫一眼书架一样——它只看"封面"，不翻开内容。

**第二步：匹配用户意图。**

你说"帮我写个工作周报"。AI 把这句话跟它扫描到的所有 description 比了一下。你的 weekly-report 的 description 里有"周报"这个词，匹配上了。

这就像你说"我想学做红烧肉"，你不会去翻那本《日本料理入门》，你会直接从书架上抽出《中式家常菜》——因为封面上的简介告诉你这本书里讲的是中餐。AI 做的就是这个匹配动作。

**第三步：加载正文执行。**

AI 去读 weekly-report 的完整 SKILL.md 正文——输出格式、操作步骤、反模式，全部加载进来。然后按照这些指令来生成输出。

这一步才是真正"翻开书看内容"。你抽出那本《中式家常菜》，翻到红烧肉那一页，按步骤做菜。其他19本书从头到尾都没被翻开过。

整个过程是自动的。你不需要手动触发，不需要说"请使用我的周报 Skill"。AI 自己判断。

这也是 Skill 和普通提示词最根本的区别：提示词需要你手动粘贴，Skill 是 AI 自动判断什么时候该用。你可以装 20 个 Skill，AI 会在不同的场景下自动选择最合适的那个。

### 渐进式披露：为什么不会卡

上面这个三步流程，背后有一个设计思路叫"渐进式披露"。听起来很高级，但说白了：**用到哪个才给哪个，不用的不占地方。**

你可以把 AI 的上下文空间想象成一张桌子，桌子就那么大。如果你一启动就把 50 个 Skill 的完整内容全摊在桌子上，桌子就满了，你自己要说话的地方就没了。

渐进式披露的做法是：先把所有 Skill 的"封面"摆在桌上——每个就占名片那么大一点地方，50 个也就铺一层。等你开口说了具体需求，AI 才把对应的那本"书"翻开，把完整内容摊在桌上。而且它一次只翻开一本，不会同时摊开好几本。

所以你完全不用担心"装太多 Skill 会不会变卡"。不会的。name + description 加起来每个 Skill 才 100 个 token 左右。就算你装了 50 个，总共才 5000 token——大约等于你说三句话的量。对你正常使用几乎没有任何影响。

真正占空间的是被触发的那个 Skill 的正文，但一次只有一个会被触发。所以不管你装 5 个还是 50 个，使用体验是一样的。

这也是为什么我不建议你把正文写得太长。如果一本"书"翻开以后占了半张桌子，你自己说话的空间就被挤压了。500 行以内，够用。

---

## 如果没生效怎么办

第一次做 Skill 最容易遇到的问题，我按出现频率从高到低全列出来：

### 第一个：AI 完全不用你的 Skill

这是最常见的。原因几乎都是 description 里的触发词不够。

比如你的 description 只写了"生成工作周报"，但你说的是"帮我总结一下这周的工作"——"总结"这个词不在 description 里，AI 就匹配不上。

**修复方法**：把所有你平时可能说的说法都写进 description。"周报、工作总结、周报模板、本周回顾"——你觉得用户可能会用什么词来描述这个需求，就都写上。多一个词不花钱。

还有一个容易忽略的情况：你装了两个 Skill，功能有点重叠。比如你同时装了"周报生成"和"工作总结"，两个 description 里都写了"总结"。这时候你说"帮我写个总结"，AI 可能不知道该用哪个。**解决办法**是在各自的 description 里加上区分条件——周报的写"当用户需要写**工作周报**或**周报模板**时使用"，工作总结的写"当用户需要写**项目总结**或**阶段复盘**时使用"。

### 第二个：AI 用了你的 Skill，但输出风格不对

比如你想要带表格的周报，AI 输出了一段纯文字。

问题出在正文——你的指令太模糊了。"结构化"这三个字不够具体。改成"必须包含表格、带勾选框、分 P0/P1/P2 优先级"，AI 的输出立刻就不一样了。

还有一个特别有效的技巧：在正文里加上"反模式"，就是告诉 AI 不要做什么。比如"不要输出纯文字""不要遗漏风险表格"。告诉 AI "不要做什么"和"要做什么"一样重要，有时候甚至更重要。

### 第三个：AI 找不到你的 Skill 文件

检查目录层级。必须是这样的结构：`.claude/skills/weekly-report/SKILL.md`。

注意是 `.claude/skills/技能名/SKILL.md` 三层，不是 `.claude/skills/SKILL.md` 两层。很多新手会把 SKILL.md 直接放到 skills 目录下，那样 AI 找不到。

还有一个容易忽略的点：SKILL.md 的文件名必须是大写的 S 和大写的 MD。写成 `skill.md` 或 `Skill.md` 都不行，必须是 `SKILL.md`。

最后确认一下：文件夹名字和 name 字段一致吗？文件夹叫 `weekly-report`，name 也叫 `weekly-report`，差一个字母 AI 都找不到。

### 第四个：AI 有时用有时不用，不稳定

这种情况一般是因为你的 description 触发词太窄了。比如你只写了"周报"，但有时候你会说"帮我写个总结"——没说"周报"这两个字，AI 就匹配不上了。

**解决办法**：在 description 里多写几个同义说法。不只是在 description 里堆关键词，还可以写"当用户提到工作总结、本周回顾、周报模板时"这样的句子，把触发场景描述得更完整。

另外一个思路是检查你的 description 是否跟 AI 内置的能力撞车了。比如你做了一个"翻译"的 Skill，但 AI 本来就会翻译——它可能直接用自己的能力来处理，根本不会去看你的 Skill。这种情况你得在 description 里强调你的 Skill 有什么不同，比如"当用户需要翻译且要求保留原文语气和方言特色时使用"。

### 第五个：Skill 加载了但输出太长或太短

正文里要写死长度限制。"总长度300-500字"比"写短一点"好用一万倍。AI 对数字的理解比对模糊描述的理解好得多。

如果你的输出格式比较复杂，在正文里放一个完整的示例。比如你想让 AI 输出表格，就在正文里直接放一个示例表格，告诉 AI "按这个格式输出"。给 AI 看一个"成品长什么样"，比描述"成品应该什么样"有效得多。

### 快速排查清单

- [ ] 文件名是大写 `SKILL.md`？
- [ ] 路径是 `.claude/skills/技能名/SKILL.md` 三层？
- [ ] 文件夹名和 name 字段完全一致？
- [ ] 重启了 Claude Code？
- [ ] description 里有你实际说的关键词？
- [ ] 正文里有具体的长度限制和格式要求？
- [ ] 正文里有反模式（告诉 AI 不要做什么）？

七个都确认了，基本就没问题了。

---

## 如果你装了多个 Skill

做了第一个 Skill 之后，你大概率会上瘾，忍不住再做几个。

这不是问题——Skill 本来就是鼓励你多装的。但有几个注意点你要知道。

### 多个 Skill 之间不会打架吗？

大部分情况不会。因为 AI 是按 description 来匹配的，只要每个 Skill 的 description 写得够明确、够区分，AI 就能正确选择。

但如果两个 Skill 的 description 有重叠，就会出问题。比如你同时装了这两个：

```yaml
# Skill A
description: "生成文档内容。当用户需要写周报、总结、报告时使用。"

# Skill B
description: "生成周报。当用户需要写周报、工作周报、周报模板时使用。"
```

你说"帮我写个工作周报"，两个都能匹配上。AI 会困惑。

**解决办法**：让每个 Skill 的 description 有明确的边界。要么合并成一个（都是文档写作，统一管），要么在各自的 description 里加上区分条件——A 写"当用户需要写**通用总结**或**项目报告**时使用"，B 写"当用户需要写**工作周报**时使用"。

实际操作中，这类冲突最常出现在你做了"通用型"和"专用型"两个 Skill 的时候。比如你做了一个"通用文档助手"，description 写了"当用户需要写文档、报告、总结时使用"；同时你又做了一个"周报专用助手"。你说"帮我写篇文档"，通用型那个会被触发，但它可能没有周报专用那个做得好。

我的建议是：要么只做专用型，每个场景一个 Skill，互不重叠；要么只做一个通用型，把不同场景的处理逻辑都写在一份正文里。不要两种混着来，容易打架。

### 装多少个算多？

理论上没有上限。50 个 Skill 的 name + description 加起来才 5000 token，不会卡。

但实际上我不建议一次装太多。先从 2-3 个你最刚需的开始。用一周，确认每个都跑通了，再加新的。不然出了问题你都不知道是哪个 Skill 在捣乱。

我自己的做法是按"两周原则"来：新做的 Skill 先放项目级，用两周。如果两周后我确认它在所有项目里都用得上，再移到用户级。这样用户级慢慢积累的都是经过验证的 Skill，质量有保证。

### Skill 的加载顺序有影响吗？

没有。AI 不是按顺序逐个检查 Skill 的。它是一次性把所有 description 都看一遍，然后选匹配度最高的那个。所以不管你的 Skill 在文件夹里排在第一个还是最后一个，结果都一样。

### 项目级和用户级可以重名吗？

可以，但不建议。如果你在项目级和用户级都放了一个叫 `code-reviewer` 的 Skill，AI 会困惑——到底该用哪个？如果你确实需要在某个项目里覆盖全局设置，把项目级那个的 description 写得更有区分度。

### 一个真实的多 Skill 协作案例

我有一个项目，里面同时装了 5 个 Skill：commit-message-writer、code-reviewer、prd-generator、api-doc-writer、test-generator。这五个 Skill 各管一件事，description 互不重叠。提交代码的时候 commit-message-writer 自动生效，写 PRD 的时候 prd-generator 自动生效。我在一个项目里同时用这五个，从来没出现过冲突。

关键就是每个 Skill 的 description 都写得足够具体，不会互相抢活。你可以把 description 想象成每个 Skill 的"岗位职责"——五个人的岗位清清楚楚，不会出现两个人抢同一件事做的情况。

---

## 做完之后

现在你已经有了一个能用的 Skill。

如果你觉得输出效果还不够好，不用急。模块 3 会教你怎么调 description 让触发更精准、怎么改正文让输出更稳定。模块 2 会讲背后的原理，搞清楚为什么 AI 能自动匹配。

但说实话，大部分人做到这一步就已经够用了。先跑起来，用几天，遇到问题再回来调。不要一上来就追求完美。

用了一周之后你可能会发现：输出太长、有时候风格跑偏、有些说法触发不到。带着这些具体的问题去看模块 3，你会发现每个问题都有对应的解决方法。

---

## 写在最后

写到这儿，你应该已经做出了人生中第一个 Skill。

说实话，一开始我也没当回事，觉得不就是把提示词存起来嘛。直到有一天我连续跟 AI 说了五遍"小红书风格，300字，带emoji，口语化"，第五遍的时候我直接崩溃了——不是 AI 写得不好，是我自己说得烦了。

后来我做了一个小红书写作的 Skill，现在每次只需要说"写一篇咖啡种草"，AI 就自动按我想要的风格输出。零重复描述。

做完你就知道为什么这么多人上瘾了。

**Skill 这东西，最大的价值不是技术多复杂，而是它帮你省下的那几分钟、那几次重复描述。** 一周省下来几十分钟，一个月就是几个小时。这些时间你可以用来干别的，或者干脆用来休息。

带新人最爽的状态，从来都不是他能说会道。而是我给他一套手册，他自己能翻，能执行，能自检，能迭代。

你少说一句废话，他多交一份结果。

**Skill 也一样。**

---

## 下一步

如果你读到这里已经有点心动了，那就别犹豫。

- 想让输出更精准？→ 跳到模块 3：把 Skill 改成你自己的
- 想搞懂原理？→ 跳到模块 2：搞懂 Skill 到底怎么回事
- 想看别人的 Skill 长什么样？→ 跳到模块 5：爆款拆解

不管从哪里开始，最终你都会掌握从"零门槛"到"能写自己的 Skill"的完整能力。

你准备好了吗？

---

*以上，既然看到这里了，如果觉得不错，欢迎继续往下看其他模块～*

*下节课见~*

---
*Source: https://learnagent.wiki/skills/cards/M01-五分钟做第一个Skill*
*Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*