从零编写Agent Skill：从流程拆解到SKILL.md落地实践

最近我常被问一个问题：“Skill 到底怎么写？”特别是 Claude Code、Codex、Cursor 这一波 Agent 工具流行之后，GitHub 上冒出来大量带 SKILL.md 的仓库，有人做 PPT、有人做数学建模、有人把自己团队的前端规范封装成 skill。但点开这些仓库你会发现：真正告诉你“怎么写”的文档很少，大多数都在直接丢成品。

这篇文章不打算塞给你一个万能模板，而是想把思考过程摊开——从判断一个任务适不适合做 skill，到拆解自己的执行流程，再到写 SKILL.md、放脚本、做测试，以及最后怎么在不同工具里装载和维护它。如果你也想把重复性工作变成 Agent 能复用的能力，这篇应该能给你一套完整的下手路径。

1. Skill最近这么火，到底解决的是哪一类麻烦

先说结论：Skill 的本质，是把“你知道怎么做一件事的方法”打包成 Agent 在特定时刻能读取的文件。它不解决模型会不会写代码的问题，它解决的是“模型每次都要重新被教一遍”的问题。

1.1 上下文按需加载，是 Skill 和传统提示词文件最核心的差别

在没有 Skill 之前，想让 Claude、GPT 这类模型稳定输出，通常会做两件事：要么把规则写进系统提示词，要么把规范放在项目根目录的说明文件里，比如 CLAUDE.md、AGENTS.md。

这个做法有效，但有个代价：这些规则在每次对话时都会占据上下文窗口。如果你只放了十条全局规则还好，一旦放了 50 条，模型真正处理任务时可能已经被“规范文本”分散了注意力，还会互相干扰。

Skill 的做法不一样。它把规则拆成一个个独立文件夹，每个文件夹配一个 description。Agent 先判断用户当前需求匹配哪个描述的技能，匹配上了才加载对应的说明。也就是说，默认情况下 Skill 不占上下文，用到哪份才把哪份的内容拉进来。

这种“按需加载”对实际使用影响很大。我早期把前端规范写进全局规则，结果模型每次写代码都先想一遍那套规范，回答风格都被带偏了。后来改成前端审查 Skill，只有丢给它一段代码要做审查时才触发，效果立刻稳定许多。

1.2 Skill、Agent、MCP/插件，三者的分工并不是一回事

很多朋友在搜索时会混着问“Skill 和 Agent 的区别”“Skill 是不是插件”。我在实际项目里的体会可以简单概括成一句话：Agent 是干活的工人，Skill 是这个工人脑子里的一套操作手册，而 MCP、插件、工具是工人手上的扳手和电钻。

所以你会发现它们不是替代关系，而是配合关系。Skill 本身可能只是文字，它不负责执行操作；真正执行时，还是 Agent 决定调用哪个 MCP 工具来读数据库、发请求、操作文件。Skill 管的是“怎么组织和执行这些工具”的流程经验，而不是工具本身。

1.3 不是所有任务都适合做成 Skill，先做一次判断

我踩过最典型的坑，是把所有任务都往里塞。后来发现，适合做成 Skill 的任务通常有三个特点：

• 流程相对固定，每次都按差不多相同的步骤走。
• 输出格式明确，有一套可重复的交付标准。
• 涉及一些模型仅凭常识很难完整掌握的领域知识或组织规范。

举几个我正在用的例子：生成周报、审查前端组件是否符合团队规范、把代码仓库变化整理成发布说明、把会议纪要拆成行动项、按照特定模板生成 PPT 大纲。

不适合的也有：需要实时联网查最新数据的（应该交给搜索工具，而不是写死在 Skill 里）；需要 Agent 自由探索、目标本身都不明确的研究型任务；以及每次输出都追求随机感、不需要模板的创意发散任务。

如果一件事你连“第一句话先做什么、第二句做什么”都说不清，那 Skill 也帮不了你。可以先不急着建文件，先把这件事跳过。

2. 动手前先把你的“手艺”拆成能教给模型的三张草稿

写 Skill 最容易踩的坑，是一打开编辑器就开始敲 SKILL.md。这个顺序通常是错的。Skill 本质上是把你脑子里的隐性经验变成显性步骤，如果你自己都想不清楚步骤，写出来的文件只会是一堆正确的废话。

我自己的习惯是，先打三张草稿，不碰正式格式。

2.1 草稿一：写清楚“什么场景下会用到这个 Skill”

这是最容易被忽略但最关键的一步。因为它直接决定了你后续 description 怎么写，而 description 又决定 Agent 会不会在正确的时候触发这个 Skill。

你可以用一句话回答：用户发出什么问题、处于什么场景、提供什么材料，我希望 Agent 调用这个 Skill？

例如：“当用户给我一段多人聊天记录或会议录音转写，并要求做会议总结、提取待办事项时使用。”

如果这个场景描述得太宽，比如“需要辅助写作时使用”，那 Agent 可能什么事都来碰一下这个 Skill，结果什么都套不好。如果太窄，比如“当用户提到’会议纪要‘这四个字时使用”，那用户换成“帮我理一下刚才讨论的结论”时，Skill 就不会被触发。

2.2 草稿二：把你自己的执行步骤一条条写下来，不追求优雅

这一步很反直觉：不是先想模型该干什么，而是先想“如果我自己来干这件事，我会依次做什么”。

以“把代码提交记录整理成周报”为例，我自己的真实流程可能是：

1. 先看时间范围，确定哪些提交属于本周。
2. 把 Git 提交信息按功能模块归类，不能只看 commit message 的字面意思，还要结合分支名看它属于哪个需求。
3. 关联到对应 Issue 或任务单，确认有没有延期的项。
4. 把重复的“修 bug”“优化代码”合并成有业务价值的表述。
5. 标出风险项、待办、下周计划。

这些步骤看起来是常识，但如果你不写出来，模型不知道你背后有这么多“潜规则”。它很可能直接把所有 commit message 原样罗列出来，给你一份“fix typo”“update readme”的垃圾周报。

写草稿时不要追求词藻，想到什么写什么，越具体越好。你甚至可以把自己平时在文档里复制粘贴的固定开头、固定结尾都写上，后面都能用。

2.3 草稿三：收集一个好例子和一个坏例子

两张草稿之后，我会再准备一组“正反样本”。正面样本用来告诉模型“做到这样算合格”，反面样本用来告诉模型“千万别做成这样”。

比如周报任务，正面样本是一份按“目标 - 进展 - 风险 - 下周计划”结构写出来的周报，里面每个结论都有数据支撑；反面样本是一份把所有 commit 原样粘贴、没有把代码工作转译成业务进展的周报。

这两份样本是我在调试 Skill 时最有用的工具。模型输出跑偏时，我把坏样本贴给模型对比，让它找出自己的输出和坏样本的相似之处，比单纯说“请规范一点”有效得多。

3. SKILL.md的骨架：路由、执行说明和素材，写法和常见误区

三张草稿准备好之后，再去看 SKILL.md，你会发现它其实不复杂。以目前社区里使用最广的 Claude Code Agent Skills 目录格式为例，一个标准 Skill 文件夹大致长这样：

code复制skills/
  weekly-report/
    SKILL.md
    scripts/parse_git_log.py
    templates/weekly-report-template.md
    examples/good-example.md
    examples/bad-example.md

3.1 最前面的 frontmatter 决定了 Agent 会不会“看见”这个 Skill

SKILL.md 开头是 YAML 格式的 frontmatter，一般至少包含 name 和 description 两个字段。

markdown复制---
name: weekly-report
description: 当用户要求生成工作周报、项目周报或本周总结时使用。支持输入 Git 提交记录、Issue/任务列表、聊天记录或工作手记；输出包含本周完成、风险阻塞、下周计划、关键产出的 Markdown 周报。
---

name 建议用 kebab-case 这种机器友好的写法，比如 weekly-report、code-review。不要用中文，也不要带空格，否则在部分工具里引用路径时容易出问题。

description 才是真正的主角。它负责“触发路由”。写的时候不只是给人类看，更是给 Agent 做语义判断用的。我建议至少包含三层信息：

• 什么时候用：描述触发场景。
• 能处理什么输入：有哪些材料格式。
• 输出大概长什么样：让 Agent 在调用前就知道调用结果是否符合预期。

有些实现还支持在 frontmatter 里声明 allowed-tools 或额外元数据，用来限制 Skill 可调用的工具。这个取决于你使用的工具版本，不是所有平台都支持，但保留在 frontmatter 里通常是安全的，不会被误解析。

3.2 正文字写的不是“读物”，而是“可以照着执行的流程”

正文是给 Agent 执行的，不是给你同事做的培训手册。这意味着每句话都要有操作性。

以周报 Skill 为例，正文里不应该写“请认真总结本周工作”，因为这是废话。应该写：

1. 如果用户提供了 Git 仓库路径，运行 scripts/parse_git_log.py 获取近 7 天的提交结构化列表；脚本不可用时，直接从用户消息中提取提交记录。
2. 将提交记录按功能模块聚合，把“fix: 修复订单状态跳转错误”这类信息转成“修复订单流程状态跳转 bug，避免用户下单后页面异常”，不要把 commit message 原样堆砌。
3. 输出按“本周完成 / 风险与阻塞 / 下周计划 / 关键产出”四段组织，每段必须有具体信息，没有信息时写“暂无”，不要编造。

正文中还要给出“必须/禁止”的边界。模型经常会在信息不足时脑补，所以我会特意加一条：“只允许使用输入材料中出现的项目名、指标和负责人；涉及未知信息时标注[待确认]。”

3.3 模板、脚本、参考样例不是附属品，它们是 Skill 的肌肉

很多初学者只在 SKILL.md 里写一大段文字，不给任何结构化模板。但真实经验是：给模型一张空表格，比在描述里写十句“按表格输出”更有效。

比如周报 Skill 里，我会在 templates/weekly-report-template.md 放一份半成品：

markdown复制## 本周完成
- [项目A] 完成 XX 功能开发，状态：已上线（提交记录：xxxx）
- [项目B] 修复 XX 问题，影响范围：支付页面

## 风险与阻塞
- [风险] XX 接口依赖第三方排期，预计晚两天
- [阻塞] 暂无

## 下周计划
- [项目A] 补全 XX 模块的测试用例
- [项目C] 启动 XX 方案的技术预研

## 关键产出
- 代码提交记录、需求文档链接

你能明显感觉到，模型拿到这个半成品后输出的稳定性比只给字段名高很多。原因是模板减少了解释成本，也减少了模型自由发挥的空间。

脚本的作用则是替模型完成“文本模型不擅长但脚本很擅长”的步骤。比如从原始 Git log 里筛时间范围、统计文件变更，这些操作如果靠模型阅读文本再做，费时又容易错。让 Skill 里的脚本先跑一遍，输出一个结构化 JSON，再交给模型做最终整理，效率和准确度都会明显提升。

3.4 Skill 文件也会吃 token，内容不是越全越好

这里必须提醒一个反直觉的点：很多人以为 Skill 写得越细越好，但实际上一旦 Skill 被触发，它的正文、模板、示例文件都可能被放进上下文。如果塞了 2 万字参考资料，模型处理任务时会被大量无关细节干扰，反而降低完成度。

我的经验是：Skill 正文部分控制在 400 到 800 行以内算正常，参考资料能不放就不放，需要时通过脚本按需读取，而不是一股脑写进 SKILL.md。

4. 一个能直接抄的实例：把“写周报”从口头约定变成 Skill

这里我用“周报”做完整演示，因为这个任务几乎每个职场人都遇到过，需求明确，适合普通技术从业者直接复现。

4.1 先按场景拆流程，再生成 SKILL.md

假设我每个周五要做研发周报，输入材料包括：本周 Git 提交记录、Issue 列表、若干工作群聊天记录。输出要求是 Markdown 格式，带“本周完成/风险与阻塞/下周计划/关键产出”。

按照第 2 节的三张草稿拆法，我把个人流程翻译成以下 Skill 文件：

markdown复制---
name: weekly-report
description: 当用户要求写工作周报、项目周报、本周总结或周进度反馈时使用。支持输入 Git 提交记录、Issue 列表、任务清单或聊天记录；输出包含本周完成、风险与阻塞、下周计划、关键产出的 Markdown 周报。如果用户给出的是一个时间段，优先使用该时间段而不是默认近 7 天。
---

# 周报生成 Skill

## 执行步骤

1. 识别报告周期：
   - 如果用户明确说本周，默认使用最近 7 天（上周五到本周四）；
   - 其他情况按用户给定时间范围处理。

2. 收集输入材料：
   - 用户直接粘贴的提交记录、Issue 或聊天记录；
   - 如果用户提供了仓库路径，可运行 `scripts/parse_git_log.py` 获取近 7 天提交；
   - 不要自行访问用户没有提供的链接或文件。

3. 聚合信息：
   - 先把原始材料分类为“完成 / 进行中 / 风险 / 下周计划”；
   - 将提交记录转成业务描述，例如“update order status”转成“修复订单状态同步问题”；
   - 同类工作合并，不逐条罗列。

4. 打开模板 `templates/weekly-report-template.md`，按模板填充内容。

5. 检查：
   - 是否使用了未在输入中出现的指标？
   - 是否有重要阻塞项漏掉？
   - 每条“完成”是否都给了可验证的依据（提交号、Issue 号、文档链接）？

## 输出格式

参照模板输出 Markdown，不要输出多余的分析过程。

## 禁止事项

- 禁止把 commit message 逐字堆砌；
- 禁止编造负责人、完成时间、性能指标；
- 信息缺失时写“暂无”或“[待确认]”。

这里的关键是第 3、4 步。很多周报 Skill 只写了“请生成一份周报”，然后让模型自己输出，格式和颗粒度全凭运气。我在正文里直接指定了“打开模板”，让模板去承载大部分格式要求。

4.2 编写一个辅助脚本，处理模型不擅长的时间过滤

产品里 scripts/parse_git_log.py 是一个很短的脚本，它做的事情比模型肉眼读 Git log 准确得多：

python复制#!/usr/bin/env python3
"""读取近 N 天的 git 提交记录，输出结构化 JSON。"""
import subprocess
import json
import sys
from datetime import datetime, timedelta

if len(sys.argv) > 1:
    since_arg = sys.argv[1]
else:
    since_arg = "7 days ago"

cmd = [
    "git", "log",
    "--since=" + since_arg,
    "--pretty=format:%h|%an|%ad|%s",
    "--date=iso"
]
output = subprocess.check_output(cmd, text=True)
items = []
for line in output.strip().splitlines():
    if not line:
        continue
    commit_id, author, date_str, subject = line.split("|", 3)
    items.append({
        "commit_id": commit_id,
        "author": author,
        "date": date_str,
        "subject": subject
    })

print(json.dumps(items, ensure_ascii=False, indent=2))

这样模型拿到的是一个干净的 JSON，而不是几百行杂乱的 git log。脚本本身没有魔法，但它把“文本处理”变成“结构化数据处理”，出错概率会小很多。

4.3 本地快速验证：这个 Skill 到底有没有被正确触发

写完不是结束，第一轮验证必须用固定输入做回归。

我通常会准备一个测试文件，里面是模拟的周报输入，比如几段 commit 记录、两条 Issue 描述和一段聊天讨论。然后直接对当前项目里的 Agent 发起请求：“帮我根据这些材料写一份周五周报。”

观察时机：Agent 是否提示加载了 weekly-report Skill？如果没加载，检查 description 是否和用户说法匹配；如果加载了但输出格式还是乱，则检查正文和模板是否有冲突。

这个过程可能要重复三到五次。不要怕输出不满意，每轮只修一个问题：这一轮只调 description，下一轮只调输出格式，再下一轮才调整内容颗粒度。一次改太多，你根本无法判断是哪个改动真正起了作用。

5. 把同一个 Skill 放进 Claude Code、Codex 和 Cursor 的实操差异

同一个 Skill 能不能跨平台用？我的结论是：文件尽量通用，目录位置按平台调整。

目前社区里最常见的格式是“文件夹里放一个带 frontmatter 的 SKILL.md”，这个格式在 Claude Code 里是原生支持的，Codex 系工具也越来越多地采用类似约定。但不同工具对目录位置、加载方式的定义并不完全一致，所以需要看实际情况来做小量适配。

5.1 Claude Code 的目录结构相对成熟

Claude Code 里的 Skill 一般放在两个位置：项目级是 .claude/skills/<skill-name>/SKILL.md，用户级是 ~/.claude/skills/<skill-name>/SKILL.md。

差别在于可见范围。放项目级，只有这个仓库会加载；放用户级，你在不同项目里都能用同一套 Skill。如果这个 Skill 和公司内部规范绑定，就放项目级，避免泄漏到其他项目；如果只是个人写作习惯、周报格式这种通用能力，放用户级更方便。

放进目录后，需要新开会话或执行 /skills 之类的命令刷新列表，不同版本的行为不完全一样。建议改完目录后先重启一次 Agent 交互，确认 Skill 出现在可发现列表再测试。

5.2 Codex 系工具：重点看对 SKILL.md 和 AGENTS.md 的加载策略

Codex 类工具目前更核心的文件是 AGENTS.md，但近期版本也开始支持通过 skills 或类似机制加载 Markdown 技能文件。如果你用的是较新版本，常见做法是把 Skill 目录放到项目下或用户配置的 skills 目录下，然后在说明里声明“当需要某类任务时读取 skills/<name>/SKILL.md”。

我建议在 Codex 里部署时先量力而行：把同一个 SKILL.md 先用一个典型场景测试，不要一次性放十几个技能。因为不同实现的前置 field 解析、加载时机未必完全兼容，先跑通一个再复制到其他技能。

5.3 Cursor 类工具：不一定有原生 SKILL.md，但可以借壳

Cursor 的官方体系里，用户常用的是 .cursor/rules 和自定义命令。社区里说的“把操作变成 Skill”，目前主流做法其实是把可复用的操作步骤写成一个 .cursor/rules 文件，或用斜杠命令把它触发出来。

兼容做法是把同一个内容复制成两份组织方式：

• 项目内建 .cursor/rules 文件，把执行流程填进去，让 Cursor 在匹配规则时读取。
• 保留原有的 SKILL.md 目录结构，方便以后迁移到 Claude Code 或 Codex。

换句话说，不要把 Skill 理解成只能绑定某一个产品。它更像是“一套内容资产”，哪个平台支持原生的就读原生，不支持的就把内容改一个壳子挂上去。

6. 测试、修错和进化：我的 Skill 维护心得

Skill 写完之后，最花时间的不是开发，而是修错和迭代。这部分我分享几个高频问题。

6.1 排查时最容易忽略的，是看看 Skill 到底有没有被加载

当模型输出不符合预期时，先别急着改正文。第一步应该确认“它到底有没有读到你的 Skill”。

在带日志模式的 Agent 工具里，你会发现它通常会在加载某个技能时打印一行路径。如果没有任何加载记录，问题多半出在 description 上。这时候去调整描述里的触发词，比你一遍一遍优化正文有效得多。

6.2 触发不准、格式不稳、输出过度：三种失败模式对应三种修法

这里想强调的是“禁止事项”的价值。模型的默认行为是尽量回答全面，但 Skill 往往只希望它输出某个固定格式。缺少“不要输出什么”的 Skill，就像新员工干活时热情过度，虽然活儿干了，但给了一堆老板不想要的内容。

6.3 迭代时的好习惯：一次只改一个变量

Skill 的维护很像调参，但很多人的调参方式是全盘推翻重写。这样做的问题在于，你永远不知道是哪个改动导致结果变好或变差。

我做周报 Skill 时，第一版只写了目标说明，没加模板，输出结构松散；第二版只加了模板，格式稳定了，但内容还是经常把“修复订单状态”写成“修复 bug”；第三版加了禁止事项和“把 commit message 转成业务描述”的示例，才算真正稳定。

每一次改动后，用同一份测试输入做回归，直到输出稳定。这个循环听起来笨，但确实是最快的方式。

6.4 不要什么都自己写，学会从公开 Skill 库“拆”经验

最后说一个省力技巧：如果你对某个领域不熟，先去公开的 Skill 仓库里找同类实现。GitHub 上有不少开源的 skill 集，里面覆盖了代码审查、PPT 生成、前端规范、数学建模等场景。看十个同类 Skill，就能总结出该领域常见的输入输出格式、容易踩坑的约束点和触发描述措辞。

拆 Skill 时重点看三样东西：

• 它的 description 怎么描述触发场景；
• 它在正文里如何规定输出格式；
• 它在“禁止事项”里排除了哪些情况。

这部分经验是可以迁移的。即便你不直接复制别人的 Skill，通过拆解也能积累大量常见的写作范式。

我自己最后的体会是：Skill 和普通文档最大的区别，是它必须为一个“不那么可靠”的执行者服务。模型不是不会做事，而是不知道你心里的默认标准是什么。写 Skill 的过程，其实是在把那些“你觉得理所当然的事”一条一条翻译成机器能理解、能执行的规则。等到这个翻译完成，你得到的不仅是一个文件夹，而是一套可以反复复用、跨平台携带的做事方法。