`name` 是 Skill 的名字，`description` 是 Agent 判断“要不要用它”的索引，正文才是具体操作手册。写好 `SKILL.md`，本质上是在给 Agent 做一套轻量、可按需加载的上下文地图。
这篇是 Skill 工坊系列的进阶入门篇。前面我们讲了 Skill 是什么、怎么安装、一个 Skill 文件夹里有哪些东西。现在进入最关键的文件：`SKILL.md`。
很多人第一次写 Skill，会把全部规则都塞进正文里，甚至把它写成一篇超长提示词。这样做短期能跑，长期会遇到两个问题：
· Agent 不知道什么时候该调用它。
· 一旦调用，正文太长，占用大量上下文，还容易抓不住重点。
所以真正要学的，不是“写一段更长的提示词”，而是理解 `SKILL.md` 的三层信息结构。
用《洛克王国》这款20263D火爆游戏来理解
如果把 Agent 执行任务想象成玩家进入《洛克王国》的世界，它不是一出生就需要知道所有宠物的全部技能、全部地图事件、全部克制细节。
它会先看地图和图鉴：
这里有哪些地图？
这里有哪些宠物？
这个宠物大概是什么系别？
这个任务可能要去哪儿？
只有当它真的进入某个区域、遇到某只宠物、准备打一场战斗时，才需要查看更详细的信息：
宠物具体技能是什么？
属性克制关系是什么？
当前血量、等级、状态如何？
捕捉还是战斗更合适？
Agent 使用 Skill 也是类似的。它不应该一开始就加载所有操作手册，而应该先看轻量索引，再按需读取细节。
2026 年的 Skill，核心是渐进式披露
截至 2026 年，Agent Skills 已经不只是 Claude 生态里的一个功能。OpenAI/Codex、Claude、Gemini CLI、Cursor、VS Code、GitHub Copilot、opencode 等工具都在支持或采用类似的 `SKILL.md` 思路。
这些实现细节不完全一样，但核心设计很接近：让 Agent 先看到少量元信息，再在任务相关时加载完整说明。
可以把它理解成三层：
第一层：name + description
用于发现和判断：这个 Skill 是什么，什么时候用。
第二层：SKILL.md 正文
用于执行：具体步骤、规则、输出格式、停止条件。
第三层：references / scripts / assets
用于补充：长资料、确定性脚本、模板素材，按需读取或使用。
这就是上下文工程里很重要的“渐进式披露”：不是把所有知识一次性塞给 Agent，而是让它像玩家探索地图一样，先看索引，再看区域说明，最后需要时才查细节。
一个 SKILL.md 长什么样
先看一个最小结构：
name: forum-post-checker
description: 检查 AIHELPU 论坛帖子发布格式。用户要求检查标题、分类、标签、母帖回链、参考资料或 Markdown 排版时使用。
检查用户提供的论坛帖子，并输出：
1. 标题是否清楚；
2. 分类和标签是否合适；
3. 是否包含母帖回链；
4. 是否有参考资料；
5. 是否可以直接发布；
6. 需要修改的地方。
这份文件看起来简单，但它已经包含了 `SKILL.md` 的三个核心部分：
name：这个 Skill 叫什么
description：什么时候应该调用它
正文：调用后应该怎么做
`name`：给 Skill 一个清楚的名字
`name` 是 Skill 的标识。它应该短、清楚、稳定。
不建议这样写：
name: my-skill
也不建议这样写：
name: super-ai-helper
这两个名字都太泛。一个读不出用途，一个像营销口号。
更好的写法是：
name: forum-post-checker
或者：
name: weekly-report-writer
命名建议：
1. 使用小写字母、数字和连字符
2. 尽量动词或任务导向
3. 让人一眼看出用途
4. 不要用“万能”“超级”“大师”这类泛词
5. 不要频繁改名，避免旧调用方式失效
如果用《洛克王国》类比，`name` 就像宠物图鉴里的名字。你看到“火花”“水蓝蓝”“喵喵”，能先知道它是谁；但光知道名字，还不知道什么时候该派它上场。
`description`：决定 Skill 会不会被触发
`description` 是整个 `SKILL.md` 最容易被低估的地方。
Agent 通常先看到所有 Skill 的 `name` 和 `description`，再判断当前任务要不要加载某个 Skill。也就是说，`description` 不是给人看的宣传语，而是给 Agent 用的触发索引。
不好的写法：
description: 帮助写文章
这太宽泛，几乎所有写作任务都可能触发它。
也不好的写法：
description: 一个非常强大的论坛内容增长专家，可以帮助用户完成各种内容创作任务。
这像广告，不像触发条件。
更好的写法：
description: 整理 AIHELPU 论坛 Skill 工坊帖子。用户要求检查标题、分类、标签、母帖回链、参考资料、Markdown 排版或发布格式时使用。
好 `description` 要包含三类信息：
1. 这个 Skill 做什么
2. 用户什么时候会需要它
3. 用户可能会怎么说
用洛克王国类比，`description` 就像宠物的“系别 + 适用战斗”。你不能只写“很强的宠物”，而要写清楚：
火系，适合对付草系敌人；
水系，适合对付火系敌人；
辅助型，适合回复、控制和拖回合。
如果描述太模糊，Agent 就像新手玩家乱派宠物，很容易选错。
description 的三个写法模板
模板 1：场景触发型
适合论坛、文档、运营类 Skill。
description: 检查 AIHELPU 论坛帖子发布格式。用户要求检查标题、分类、标签、母帖回链、参考资料或 Markdown 排版时使用。
模板 2：文件类型触发型
适合 Word、Excel、PDF、PPT 等文件处理 Skill。
description: 处理 Word 文档排版和内容修改。用户上传 docx 文件并要求润色、重排、生成发布版或检查格式时使用。
模板 3：工作流触发型
适合周报、会议纪要、直播选题等固定流程。
description: 生成 AI 行业直播选题清单。用户要求整理 AI 新闻、筛选直播主题、生成直播台本或检查新闻来源时使用。
写完后，可以用一句话自测：
用户如果真的需要这个 Skill，会不会说出 description 里的关键词？
如果不会，就要改。
正文：别写百科，写执行手册
`SKILL.md` 正文是在 Skill 被选中之后才读取的内容。它不是用来解释“我为什么做这个 Skill”，而是告诉 Agent “现在怎么执行”。
正文建议包含五块：
1. 任务目标：这个 Skill 要完成什么
2. 输入要求：用户需要提供什么材料
3. 执行步骤：Agent 按什么顺序处理
4. 输出格式：最后交付什么样的内容
5. 停止条件：遇到哪些情况不要猜，先问用户
示例：
## Goal
把用户提供的文章整理成适合 AIHELPU Skill 工坊发布的版本。
## Inputs
- 原始文章正文
- 母帖链接
- 参考来源链接
- 用户指定的分类或标签
## Workflow
1. 先判断文章属于科普、安装、案例还是创作者规范。
2. 检查标题是否清楚，避免夸张标题党。
3. 检查正文是否有二级标题、短段落和代码块。
4. 检查是否包含母帖回链和下一篇建议。
5. 检查参考资料是否有来源链接。
6. 输出可直接发布的 Markdown。
## Output
按以下结构输出：
- 标题
- 分类建议
- 标签建议
- 正文
- 上一篇 / 下一篇 / 返回母帖
- 参考资料
## Stop conditions
- 如果用户没有提供正文，先询问，不要编造。
- 如果来源不清楚，标记“待补充来源”。
- 如果出现隐私、密钥、账号信息，提醒删除后再发布。
这就比一句“你是资深编辑，请帮我优化文章”稳定得多。
正文里不要放太多细节
很多新手写 `SKILL.md`，会把所有参考资料、案例、规则、链接都塞进正文。
这相当于在洛克王国新手进入第一个地图时，就把全部宠物图鉴、全部属性克制表、全部副本攻略、全部装备说明一次性塞给他。
信息是多了，但决策反而慢了。
更好的方式是把正文写成“主线任务”，把长资料放到 `references/`：
forum-post-checker/
├── SKILL.md
└── references/
├── aihelpu-style.md
├── title-examples.md
└── skill-section-rules.md
在 `SKILL.md` 里只写：
当用户要求判断论坛语气时，读取 references/aihelpu-style.md。
当用户要求改标题时，读取 references/title-examples.md。
当用户要求检查 Skill 工坊规则时，读取 references/skill-section-rules.md。
这样 Agent 只有在需要时才读细节。
洛克王国版三层模型
把 Skill 的信息分层换成洛克王国，就很好理解。
LOD-0：地图和图鉴索引
对应 `name + description`。
宠物名称：火花
简要说明：火系，适合对付草系敌人。
Agent 只需要知道：
这个 Skill 存在；
大概做什么；
什么时候可能用。
LOD-1：宠物技能说明和战斗策略
对应 `SKILL.md` 正文。
火花有哪些技能；
打草系时先用哪个技能；
血量低时要不要换宠；
遇到水系时是否停止强攻。
Agent 读取正文后，就能完成大部分常规任务。
LOD-2：完整攻略、属性表和副本细节
对应 `references/`、`scripts/`、`assets/`。
完整属性克制表；
所有宠物技能数据；
副本机制说明；
捕捉概率计算脚本；
输出报告模板。
这些内容不必一开始就读。只有任务进入具体战斗、具体副本、具体计算时，才按需加载。
2026 版写法：让 Skill 更像路由器
2026 年的 Agent 不再只是“看提示词回答问题”。它可能会读文件、跑脚本、调用工具、连接 MCP、生成文档。
所以 `SKILL.md` 的作用越来越像一个轻量路由器：
用户说了什么？
这属于哪个任务？
需要读哪个 reference？
需要跑哪个 script？
哪些动作必须人工确认？
最后按什么格式输出？
一个好的 `SKILL.md` 不应该替代所有工具，而应该告诉 Agent 怎么选择路径。
比如：
如果用户只要求检查标题，不读取 references/skill-section-rules.md。
如果用户要求完整发布检查，读取 references/skill-section-rules.md。
如果用户上传 Markdown 文件，先运行 scripts/check_markdown_stats.py。
如果用户要求自动发布到外部平台，停止并要求人工确认。
这才是 Skill 和普通提示词的区别。
一个完整示例：洛克王国战斗助手 Skill
为了方便理解，我们写一个虚构的洛克王国战斗助手 Skill。
name: rock-kingdom-battle-helper
description: 帮助分析洛克王国宠物战斗策略。用户询问宠物系别克制、出战顺序、技能选择、捕捉或新手战斗建议时使用。
## Goal
根据用户提供的宠物、敌方属性、等级和战斗目标，给出新手能理解的战斗建议。
## Inputs
- 我方宠物名称、等级和属性
- 敌方宠物名称、等级和属性
- 当前目标：通关、捕捉、练级或挑战
- 用户已知限制：不能换宠、药品不足、只想低成本通关等
## Workflow
1. 先判断我方和敌方属性关系。
2. 如果信息不足，先标记“待确认”，不要编造宠物数据。
3. 给出出战建议：继续打、换宠、捕捉或撤退。
4. 给出技能选择建议，优先解释为什么。
5. 如果涉及完整克制关系，读取 references/type-chart.md。
## Output
输出：
- 一句话建议；
- 属性克制判断；
- 推荐行动；
- 风险提醒；
- 需要补充的信息。
## Stop conditions
- 如果用户没有提供敌方属性，不要猜测；
- 如果宠物技能信息不确定，标记“待确认”；
- 不输出外挂、作弊、账号交易相关内容。
这个例子不是为了做游戏攻略，而是让你看懂 `name`、`description` 和正文的分工。
写 SKILL.md 的常见错误
错误 1：name 太泛
name: helper
改成：
name: forum-post-checker
错误 2：description 像广告
description: 一个强大的 AI 内容助手，帮你完成所有写作任务。
改成：
description: 检查 AIHELPU Skill 工坊帖子。用户要求检查标题、分类、标签、母帖回链、参考资料或 Markdown 排版时使用。
错误 3：正文只写身份，不写流程
你是一位资深内容运营专家，请帮用户写出高质量文章。
改成：
1. 先判断文章类型；
2. 检查标题；
3. 检查结构；
4. 检查来源；
5. 输出修改建议和发布版。
错误 4：没有停止条件
没有停止条件，Agent 就容易猜。
应该补上：
如果缺少原文，先询问用户。
如果来源不清楚，标记待补充。
如果涉及隐私或密钥，提醒删除。
小白记这三句话就够了
name：让人和 Agent 知道它叫什么。
description：让 Agent 知道什么时候该用它。
正文：让 Agent 知道用了以后怎么做。
如果再用洛克王国记忆：
name = 宠物名称
description = 系别和适用战斗
正文 = 技能说明、战斗流程和撤退条件
创作者发布前自查
如果你准备在 Skill 工坊发布一个 `SKILL.md` 教程或案例，发布前至少检查：
1. name 是否具体
2. description 是否包含真实触发场景
3. 正文是否写了步骤，而不是只写角色
4. 是否有输出格式
5. 是否有停止条件
6. 是否说明 references/scripts/assets 什么时候使用
7. 是否避免夸大“自动完成一切”
8. 是否标明参考来源
小结
`SKILL.md` 的难点，不是 Markdown 语法，而是信息分层。
`name` 要短而清楚，像图鉴里的宠物名称。
`description` 要写出触发条件，像宠物的属性和适用战斗。
正文要写流程、格式和停止条件，像真正能上场执行的战斗说明。
当你能把一个 Skill 写成“先看索引、再看主线、需要时才查细节”的结构时，它就不再是一段提示词，而是一套可以被 Agent 长期复用的上下文工程。