看完这篇教程，你将能够：理解 Skill 是什么、知道一个 Skill 由哪些文件组成、学会让 Agent 帮你写 Skill、掌握 SKILL.md 的写作逻辑，并成功安装你自己的第一个 Skill。

全程实战：我们最后会一起做一个「论文解读与内容创作」Skill —— 让 Agent 帮你读学术文章、提取观点、自动生成创作素材。

---

一、什么是 Skill？

1.1 一句话解释

Skill 就是一个写给 Agent 【比如Codex、Claude code、Qoder、Workbuddy、Trae 等，下面我们以Qoder为例】看的 Markdown 说明书，教它如何做一件特定的任务。

1.2 一个生活化的类比

想象你请了一位非常聪明的助理（Agent）。他什么都会一点，但不了解你的具体习惯：

• 你希望周报用固定模板写

• 你希望读论文时按「研究问题 → 方法 → 结论 → 局限」的结构做笔记

• 你希望小红书文案必须是emoji开头、三段式

没有 Skill 时：你每次都要把这些要求重新说一遍，说漏了他就会自由发挥。

有了 Skill 后：你把这些要求写成一份**岗位培训手册（SOP）**交给助理。从此以后，只要你一说"帮我读这篇论文"，他就会自动翻开手册，按你的规矩办事。

1.3 Skill 是怎么被触发的？

你可能好奇：Agent 怎么知道什么时候该用哪个 Skill？

机制其实很朴素：

1. 每个 Skill 的头部都有一段 description（描述），这段描述会被注入 Agent 的"视野"中

2. 当你发消息时，Agent 会扫描所有可用 Skill 的描述，判断"这个任务和我的哪本手册匹配？"

3. 匹配上了，它才会去读那本手册的完整内容，然后照做

所以记住一个核心结论：description 写得好不好，直接决定了你的 Skill 能不能被 Agent "想起来"用。 这是全文最重要的知识点，后面会重点讲。

---

二、Skill 包含哪些文件？

2.1 目录结构

一个 Skill 就是一个文件夹，里面必须有且只有一个核心文件 SKILL.md，其余都是可选的：

skill-name/                 # 技能文件夹（名字用英文小写+连字符）
├── SKILL.md                # 【必需】主说明书：frontmatter + 正文指令
├── reference.md            # 【可选】详细参考资料，按需加载
├── examples.md             # 【可选】示例集
└── scripts/                # 【可选】工具脚本目录
    ├── validate.py
    └── helper.sh

各文件的角色：

文件	必需？	作用
SKILL.md	✅ 必需	主入口。Agent 触发 Skill 后读的第一个文件
reference.md	可选	太长的细节内容放这里，SKILL.md 里放链接，Agent 需要时才读
examples.md	可选	大量的输入输出示例，让 Agent 模仿
scripts/	可选	预写好的脚本（如校验、解析），比让 Agent 现场编代码更可靠

2.2 Skill 存放在哪里？

类型	路径	适用范围
个人级（Personal）	~/.qoder/skills/skill-name/	你所有的项目都能用
项目级（Project）	.qoder/skills/skill-name/	跟随仓库，团队协作者共享

💡 选择建议：只给自己用的工作流（如读论文、写周报）放个人级；团队规范类（如代码审查标准、提交信息格式）放项目级，可以随 Git 一起提交给同事。

---

三、动手之前：先想清楚 6 个问题

写 Skill 之前，先在心里（或者直接在对话框里）回答这 6 个问题，Skill 的质量 80% 取决于这一步：

1. 用途与范围：这个 Skill 具体帮 Agent 完成什么任务？（越具体越好，"读学术论文并产出创作素材"就比"帮助学习"好得多）

2. 存放位置：个人级还是项目级？

3. 触发场景：用户说什么话、做什么操作时，Agent 应该想起这个 Skill？

4. 领域知识：哪些信息是 Agent 本来不知道、必须你告诉它的？（比如你的笔记模板、你的排版偏好）

5. 输出格式：产出物有没有固定模板？（笔记结构、文案风格）

6. 现有模式：有没有现成的好例子可以参考？

---

四、如何让 Agent 协助你写 Skill

好消息是：你不需要从零手写，Agent 自己就会写 Skill。 你要做的是"把需求说清楚"。

4.1 直接对话法（推荐新手）

打开对话框，把第三节的 6 个问题变成一段话发给 Agent。给你一个可以直接抄的"咒语模板"：

帮我创建一个 Skill，需求如下：

1. 用途：当你阅读学术论文/文章时，按照我的固定框架提取结构化笔记，
   并基于笔记生成适合内容创作的素材
2. 存放位置：个人级（~/.qoder/skills/）
3. 触发场景：当我发论文 PDF、链接，或者说"帮我读这篇论文"时使用
4. 领域知识：笔记必须包含：研究问题、核心方法、关键结论、
   局限性、可引用的金句；创作素材要分"深度长文版"和"社交媒体版"
5. 输出格式：先输出结构化笔记，确认后再生成创作素材
6. 其他：笔记用中文，专业术语保留英文原文

4.2 Agent 会帮你做什么？

收到需求后，Agent 会走一个四阶段流程，你只需要在关键节点确认：

阶段	Agent 做的事	你要做的事
① 需求挖掘	向你追问不清楚的细节（放哪？要不要脚本？）	如实回答
② 设计	起草 Skill 名称、description、章节大纲	看一眼是否贴合你的意图
③ 实现	创建目录、写 SKILL.md 和配套文件	无需动手
④ 验证	检查行数、描述质量、术语一致性	提一句"帮我读 xx 论文"实测触发效果

4.3 人机协作的黄金分工

• 你负责：业务知识（笔记框架长什么样、文案要什么风格）、验收结果

• Agent 负责：格式规范（frontmatter 语法、description 写法）、文件创建、规范检查

即使 Agent 帮你写，你也需要看懂 SKILL.md 的结构，这样才能提出修改意见。所以下一章是全文核心。

---

五、SKILL.md 的格式与书写逻辑（核心章节）

5.1 整体骨架

每个 SKILL.md 都由两部分组成：YAML frontmatter（元数据） + Markdown 正文（指令）。

---
name: your-skill-name
description: 简要描述这个 Skill 做什么、什么时候使用
---

# Your Skill Name

## Instructions
写给 Agent 的清晰、分步骤的操作指南。

## Examples
具体的使用示例。

5.2 Frontmatter：不可或缺的两个字段

frontmatter 就是文件开头被 --- 包起来的部分，只有两个必填字段：

字段	规则	作用
name	最长 64 字符，仅限小写字母/数字/连字符	Skill 的唯一标识
description	最长 1024 字符，非空	Agent 据此决定何时启用 Skill

Description 的三条黄金法则

法则一：用第三人称写（因为它会被注入系统提示词）

# ✅ 好
description: Processes Excel files and generates reports
# ❌ 坏（第一/第二人称）
description: I can help you process Excel files
description: You can use this to process Excel files

法则二：具体 + 带触发词（把用户可能说的话埋进去）

# ✅ 好：能力具体，触发词丰富
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
# ❌ 坏：太模糊，Agent 永远想不起它
description: Helps with documents

法则三：既写 WHAT 也写 WHEN

• WHAT：这个 Skill 能干什么（具体能力）

• WHEN：什么场景下该用它（触发情景）

再给一个实战例子（后面论文 Skill 用的就是这版）：

description: 阅读学术论文并提取结构化观点笔记，进而生成内容创作素材。当用户分享论文 PDF、arXiv 链接、学术文章，或要求"读论文""解读论文""论文笔记""基于论文创作"时使用。

5.3 正文写作的四条核心原则

原则一：简洁为王（最重要）

Agent 本来就很聪明，只写它不知道的东西。每写一段话都问自己一句："这句话值得占用上下文窗口吗？"

# ❌ 啰嗦（Agent 不需要你科普什么是 PDF）
## 提取 PDF 文本
PDF（便携式文档格式）是一种常见的文件格式，包含文本、图像等内容。
要提取 PDF 中的文本，你需要使用一个库。有很多库可以用于 PDF 处理，
但我们推荐 pdfplumber，因为它易于使用且能处理大多数情况……

# ✅ 简洁（直接给结论和代码）
## 提取 PDF 文本
使用 pdfplumber 提取文本：

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()

原则二：SKILL.md 控制在 500 行以内

正文太长会拖累性能。超出的内容拆到 reference.md、examples.md 中。

原则三：渐进式披露（Progressive Disclosure）

把"必需信息"放 SKILL.md，"细节资料"放附属文件，并在 SKILL.md 里放链接：

## 更多资源
- 完整的笔记字段定义见 [reference.md](reference.md)
- 各平台文案示例见 [examples.md](examples.md)

⚠️ 注意：引用只能有一层。SKILL.md → reference.md 可以，但 reference.md 再套娃链接到别的文件，Agent 可能读不全。

原则四：给合适的自由度

指令的"松紧程度"要和任务的"容错程度"匹配：

自由度	形式	适用场景	举例
高	纯文字说明	有多种合理做法、依赖上下文	论文观点点评、代码审查建议
中	模板/伪代码	有推荐模式但允许变化	笔记模板、报告生成
低	具体脚本	操作脆弱、必须严格一致	数据迁移、格式校验

5.4 五种常用写作模式

写正文时可以直接套用这五种模式：

模式一：模板模式 —— 固定输出格式

## 论文笔记模板

请使用以下模板输出：

# 《论文标题》
## 研究问题
[一句话概括论文要解决什么问题]
## 核心结论
- 结论 1（附数据支撑）
- 结论 2（附数据支撑）
## 我的点评
[批判性思考]

模式二：示例模式 —— 用输入输出对教 Agent

当"输出质量取决于见过好例子"时用这个模式：

## 社交媒体版文案示例

**输入**：一篇关于睡眠与记忆的论文
**输出**：
🧠 熬夜背的书，可能白背了！
最新研究发现：深度睡眠阶段大脑会"回放"白天学的内容……
（正文 3 段，每段不超过 80 字）

模式三：工作流模式 —— 复杂任务拆步骤 + 清单

## 论文解读工作流

复制此清单并跟踪进度：

任务进度：
- [ ] 第 1 步：通读论文，识别结构
- [ ] 第 2 步：按模板填写笔记
- [ ] 第 3 步：向用户确认笔记
- [ ] 第 4 步：生成创作素材

模式四：条件分支模式 —— 不同情况走不同流程

## 判断用户需求

**用户只要笔记？** → 执行"笔记流程"，产出后停止
**用户要创作素材？** → 先执行"笔记流程"，确认后执行"创作流程"

模式五：反馈循环模式 —— 质量敏感任务的自检

## 笔记产出后

1. 输出笔记
2. **立即自检**：五个必备字段是否齐全？术语是否保留英文原文？
3. 如有缺失 → 修正后再输出
4. **全部通过才提交给用户**

5.5 五个反面教材（Anti-Patterns）

反模式	❌ 错误示范	✅ 正确做法
Windows 风格路径	scripts\helper.py	scripts/helper.py
给太多选项	"可以用 pypdf、pdfplumber、PyMuPDF……"	"默认用 pdfplumber；扫描版 PDF 改用 pdf2image + pytesseract"
时效性信息	"2025 年 8 月之前用旧 API"	把过时内容收进"旧模式（已废弃）"折叠区块
术语不一致	一会儿"字段"一会儿"框"一会儿"控件"	全文统一只用一个词
名字太笼统	helper、utils、tools	processing-pdfs、paper-digest

---

六、实战：写一个「论文解读与内容创作」Skill

光说不练假把式。下面是我们用前面的方法论做出的完整 Skill，你可以直接拿去用。

6.1 需求回顾

让 Agent 帮我读学术文章 → 按我的框架提取观点和信息 → 生成内容创作素材。

6.2 目录结构

paper-digest/
├── SKILL.md          # 主说明书（工作流 + 笔记模板）
└── templates.md      # 创作素材模板（渐进式披露）

6.3 完整的 SKILL.md

---
name: paper-digest
description: 阅读学术论文并提取结构化观点笔记，进而生成内容创作素材。当用户分享论文 PDF、arXiv 链接、学术文章，或要求"读论文""解读论文""论文笔记""基于论文创作"时使用。
---

# 论文解读与内容创作

## 工作流

复制此清单并跟踪进度：

任务进度：
- [ ] 第 1 步：获取并通读论文
- [ ] 第 2 步：按模板输出结构化笔记
- [ ] 第 3 步：自检并向用户确认笔记
- [ ] 第 4 步：（用户要求时）生成创作素材

## 第 1 步：获取并通读论文

- 用户给出 PDF 文件：直接读取全文
- 用户给出链接：抓取网页内容；若是 arXiv 摘要页，优先获取全文
- 只能看到摘要时：明确告知用户"当前仅基于摘要"，再继续

## 第 2 步：输出结构化笔记

使用以下模板（正文用中文，专业术语保留英文原文）：

# 《论文标题》
- 作者 / 机构 / 发表时间与 venue：

## 研究问题
[一句话：这篇论文要解决什么问题？为什么重要？]

## 核心方法
[用了什么方法/实验设计？控制在 100 字以内]

## 关键发现
- 发现 1（附关键数据）
- 发现 2（附关键数据）
- 发现 3（附关键数据）

## 局限性
[作者承认的局限 + 你识别的潜在问题]

## 可引用金句
> [原文中最有传播力的 1-2 句话，标注出处页码]

## 第 3 步：自检并确认

输出笔记后立即自检：
- [ ] 五个板块齐全，无"略"或占位符
- [ ] 每个关键发现都有数据支撑
- [ ] 术语保留英文原文（如 "in-context learning" 不翻译）

自检通过后，询问用户：笔记是否需要调整？确认后询问是否需要创作素材。

## 第 4 步：生成创作素材

用户确认后，询问目标平台，然后按 [templates.md](templates.md) 中
对应平台的模板生成。素材必须忠于笔记内容，不得编造论文中没有的数据。

6.4 配套的 templates.md

# 创作素材模板库

## 深度长文版（公众号 / 博客）

1. 标题：制造认知冲突，如"你以为的 A，其实是 B"
2. 开头：用一个生活场景引出研究问题（150 字内）
3. 正文：按"问题 → 方法 → 发现"三段展开，每个发现配一个类比
4. 结尾：局限性 + 对读者的行动建议

## 社交媒体版（小红书 / 微博 / X）

1. 首行：emoji + 最具冲击力的发现（不超过 30 字）
2. 正文：3 个要点，每个不超过 80 字，口语化
3. 结尾：一个互动提问（如"你会因为这个研究改变习惯吗？"）
4. 附上论文标题和链接

## 视频脚本版（口播 60 秒）

- 0-5s：钩子（最反直觉的发现）
- 5-40s：研究怎么做的 + 发现了什么
- 40-55s：这意味着什么
- 55-60s：引导关注 / 评论互动

6.5 这个 Skill 好在哪里？（对照第五章复盘）

• ✅ description 同时包含 WHAT（读论文、提取笔记、生成素材）和 WHEN（PDF、arXiv 链接、"读论文"等触发词）

• ✅ SKILL.md 只有骨架和必备模板，创作模板拆到 templates.md（渐进式披露）

• ✅ 笔记模板给中等自由度（结构固定、措辞自由），创作模板给高自由度

• ✅ 工作流带清单 + 自检反馈循环

• ✅ 明确约束"不得编造数据"，防幻觉

---

七、如何安装 Skill

写好 Skill 文件夹后，有两种安装方式。

方式一：让 Agent 帮你安装（推荐，零命令行）

直接在对话框里说：

帮我把这个 Skill 安装到个人目录：
[把 SKILL.md 内容粘贴过来，或描述需求让 Agent 现场写]

或者如果你已经有现成的 Skill 文件夹（比如从同事那拷贝的）：

帮我把 /Users/你的用户名/Downloads/paper-digest 这个 Skill 
安装到我的个人 skills 目录

Agent 会自动完成：创建 ~/.qoder/skills/paper-digest/ 目录 → 写入所有文件 → 做规范检查。

方式二：手动导入安装

适合自己管理文件、或批量安装的场景。以 macOS 为例：

第 1 步：确定安装位置

# 个人级（所有项目可用）
mkdir -p ~/.qoder/skills/paper-digest

# 或项目级（仅当前仓库，可随 Git 共享）
mkdir -p .qoder/skills/paper-digest

第 2 步：放入文件

把 SKILL.md（以及 templates.md 等附属文件）放进上一步创建的目录，确保结构如下：

~/.qoder/skills/paper-digest/
├── SKILL.md
└── templates.md

如果用命令行拷贝：

cp -r /path/to/paper-digest ~/.qoder/skills/

第 3 步：验证安装

1. 重新打开或刷新 Agent 会话（让 Skill 列表重新加载）

2. 发一句触发语测试：帮我读一下这篇论文 [附上任意 PDF]

3. 观察 Agent 是否按你的模板输出笔记 —— 输出了，说明安装成功且触发正常

排错小贴士

症状	可能原因	解决办法
Agent 完全不触发	description 缺少触发词	在 description 中补上用户常用说法
触发了但行为不对	SKILL.md 指令模糊	把"自由发挥"段落改成模板或清单
找不到 Skill	目录结构错了	确认是 skills/名字/SKILL.md，不是 skills/名字.md
frontmatter 报错	name 含大写或下划线	改成小写字母 + 连字符

---

八、发布前的验收清单

把这张清单收藏起来，每次写完 Skill 过一遍：

核心质量

• description 具体、包含触发关键词

• description 同时包含 WHAT 和 WHEN

• description 用第三人称

• SKILL.md 正文在 500 行以内

• 全文术语统一

• 示例具体，不是抽象描述

结构

• 文件引用只有一层深

• 长内容已拆到 reference/examples 文件

• 工作流有清晰步骤

• 没有会过期的时效性信息

如果包含脚本

• 脚本真的能解决问题（不是把活又推回给 Agent）

• 依赖包已写明

• 错误提示清晰友好

• 没有 Windows 风格路径

---

九、总结

回顾一下全流程：

1. 想清楚：6 个问题明确需求（用途、位置、触发、知识、格式、参考）

2. 说需求：用"咒语模板"让 Agent 起草

3. 看结构：SKILL.md = frontmatter（name + description）+ 正文（原则 + 模式）

4. 装上去：Agent 代装，或手动放进 ~/.qoder/skills/ 或 .qoder/skills/

5. 验效果：发触发语实测，不好用就回去改 description 和模板

如果你需要在Agent中接入API，自由切换全球200+大模型，链接注册可领百万Tokens：魔芋AI大模型网关I全球大模型一站式调用及服务平台魔芋AI大模型聚合平台（大模型网关平台）专注于提供高效能、低成本的多品类 AI 模型服务，助力开发者和企业聚焦产品创新。https://www.moyu.info/register?aff=qBX9

如果你需要团队/企业版workbuddy、qoder、trae、aws quick官方服务折扣，欢迎联系。

Skill 的本质，是把你的隐性经验显性化：你脑海里"读论文就该这么记笔记"的直觉，写成文字后，就变成了 Agent 永不遗忘、每次必执行的标准动作。从一个高频小场景开始（比如论文笔记、周报、 commit message），写你的第一个 Skill 吧。