看了很多文章依旧不会写 Skill ？ 保姆级攻略请查收！

如果你最近开始频繁和 Agent 协作，很容易遇到一个微妙的问题：它不是完全不会做，而是每次都像第一次做。你刚刚纠正过的格式、提醒过的风险、跑通过的工具顺序，换个任务又要重新解释一遍。

这篇文章想解决的就是这个问题：哪些经验值得从一次聊天里拿出来，沉淀成 Agent 下次可以主动调用的工作方法。Skill 不是把模型训练得更懂你，而是把一类任务的做法写成可复用的流程，让 Agent 少猜、少漏、少返工。

这类问题的本质不是模型”不聪明”，而是任务里的经验没有被沉淀下来。人类同事做熟一件事以后，会形成习惯、检查表和操作路径；Agent 也需要这样的东西——只不过给 Agent 用的不是口头经验，而是结构化的 Skill。

写 Skill 的目的是让 Agent 在同类任务里少猜一点、少漏一步、少重复问一遍背景。你可以把它理解成：把个人或团队反复做过、反复修正过、反复踩坑后总结出来的做法，整理成 Agent 下次可以直接读取和执行的操作手册。

更具体地说，Skill 通常是一个目录。目录里最核心的是 SKILL.md：它告诉 Agent 这个 Skill 适用于什么任务、开始前要读什么、应该按什么顺序做、哪些情况必须停下来确认。目录里还可以放脚本、模板、参考资料和例子。

所以 Skill 不是“把知识灌进模型里”，也不是让模型永久学会某个技能。它更像一个可被 Agent 打开的工作手册：平时只暴露简短说明，真正触发后才把详细流程读进上下文。

一个 Skill 最小可以只有 SKILL.md，但好用的 Skill 往往会把“触发、执行、资料、验证”分开写清楚。

• description：给 Agent 做第一眼匹配。它要说清楚“用户说什么时应该触发这个 Skill”。

• SKILL.md：核心说明书。写触发边界、操作步骤、必须遵守的限制、输出格式和失败处理。

• references/：长规范、API 文档、业务背景、模板。只有执行中需要时才读取。

• scripts/：把稳定、机械、容易出错的动作交给脚本，比如校验、转换、批量生成。

• examples/：放好结果、坏结果和边界样例，让 Agent 能对照判断质量。

• evals/：放最小评测集。每次改 Skill 后，用它检查有没有把原本会做的事情改坏。

理解 Skill，最关键的一点是：Agent 并不是一开始就把所有 Skill、所有参考资料、所有脚本都读进来。那样上下文会很快被塞满，真正当前任务需要的信息反而被淹没。Skill 采用的是渐进式加载：先用很短的信息判断要不要用，再逐层打开更详细的说明。

当用户的任务和 description 匹配时，Agent 才进入第二层，打开 SKILL.md。这一步相当于从“我知道有这个能力”切换到“我知道这件事应该怎么做”。好的 SKILL.md 不会只写原则，而会写清楚动作顺序：先检查什么、读取什么、调用什么工具、遇到权限或失败时怎么处理、最后按什么标准交付。

执行过程中，如果 SKILL.md 发现任务需要更长的背景，才会让 Agent 去读 references/；如果任务里有确定的机械动作，才会运行 scripts/。这就是“渐进”的含义：不是把所有内容一次性放到模型面前，而是在每一步只拿当前必要的信息。

渐进式加载解决的是上下文管理问题。Agent 的上下文不是无限的，塞进去的内容越多，干扰也越多。如果一个文档 Skill 同时包含写作规范、飞书 API、图片上传、排版规则、失败处理和几十个示例，Agent 每次整理一段文字都读完整套资料，反而更容易抓不住当前重点。

所以好的 Skill 会把内容拆成“入口短、主干清楚、资料可追溯、动作可执行”。入口短，才能准确触发；主干清楚，才能稳定执行；资料可追溯，才能在复杂场景里补细节；动作可执行，才能把容易出错的步骤交给脚本或 CLI。

渐进式加载还有一个很实际的价值：它把“写流程”和“跑流程”分开了。复杂、模糊、需要归纳经验的部分，可以交给更强的模型来整理；一旦流程被写成 Skill，后续很多同类任务就可以由更便宜、更快、能力较弱的模型按步骤执行。

所以 Skill 的终点不是“模型自己总结了一套说明”，而是“人把流程约束清楚以后，模型可以稳定照着做”。强模型可以帮你写，弱模型可以帮你跑，但流程的边界、责任和验收标准，最终还是要靠人来定。

不是所有任务都值得 Skill 化。下一步要先选场景，而不是马上动手写。

最容易失败的开局是想写一个”万能助手 Skill”。万能通常意味着边界模糊，边界模糊就意味着 Agent 自由发挥。更稳的起点是挑一个小而真实的场景，它最好满足三个条件：重复出现、容易跑偏、有明确交付物。

一个更稳的判断方法是：先不要写 Skill，拿 3-5 个真实 case 让 Agent 在没有 Skill 的情况下完整跑一遍。你要观察的不是它这次回答得漂不漂亮，而是它是否稳定暴露出同一类问题：总是漏掉某个检查步骤、总是误用同一个工具、总是输出无法验收，或者每次都需要你重新解释同一套口径。

• 需求澄清 — 输入经常模糊，但产出格式可以固定（REQUIREMENT.md、问题清单、风险点）。

• 技术方案生成 — 流程相对稳定，需要统一模块、接口、取舍说明（DESIGN.md、接口表、任务拆解）。

• 飞书文档整理 — 有固定阅读体验和排版要求（可发布文档、摘要、待确认事实）。

• 会议纪要加工 — 信息来源固定，输出可标准化（结论、决策、待办、风险）。

• 代码 Review — 关注点明确，容易形成检查清单（缺陷、风险、测试缺口、建议修改）。

写 Skill 之前，先搜一下有没有现成的。很多常见场景社区已经有人做过，能复用就先复用，能改造就别从空白页开始。

skills.sh 是一个开放的 Agent Skills 目录。你可以按关键词搜（react、testing、docs、review、deploy 等任务词），也可以看 All Time、Trending、Hot 榜单快速判断某个领域有没有成熟 Skill。

如果你经常需要找 Skill，可以先装 find-skills。它本质上是一个元 Skill：不直接帮你写代码或文档，而是教 Agent 怎么发现、筛选、推荐和安装其他 Skill。

安装 find-skills
npx skills add https://github.com/vercel-labs/add-skill --skill find-skills

搜索和安装 Skill
# 按关键词搜索 Skill
npx skills find react performance
npx skills find pr review
npx skills find changelog

# 安装一个 Skill 集合或仓库
npx skills add vercel-labs/agent-skills

# 按详情页提示安装某个 Skill
npx skills add https://github.com/vercel-labs/add-skill --skill find-skills

• 元数据 — Agent 什么时候该想起它？描述不能像口号。

• 触发条件 — 哪些请求必须用，哪些不要用？不能只写”当用户需要时使用”。

• 输入规范 — 需要哪些材料？缺材料怎么办？不能让 Agent 自己猜业务背景。

• 工作流程 — 先做什么后做什么？哪里必须校验？不能只有原则没有动作。

• 输出契约 — 交付物长什么样？不能没有格式也没有示例。

• 失败处理 — 什么情况下要停、重试或问人？不能默认 Agent 会自己判断风险。

• 示例和评测 — 怎么知道它做得对？不能只凭一次演示判断可用。

• 直接用 — 场景高度匹配，来源可信，说明清楚，脚本行为可接受。用 3-5 个真实任务试跑。

• 改造后用 — 大方向匹配，但你有自己的流程、模板、术语或风格。保留核心结构，改 description、示例、输出格式和停止条件。

• 自己写 — 没有合适 Skill，或任务强依赖内部系统、私有流程、安全边界。用现成 Skill 当参考，从最小场景开始写。

大多数时候，你不需要从零写一个 Skill。更省力的做法，是先找一个方向接近的现成版本，再把它改到贴合自己的真实场景。好用的 Skill 往往带着明显的使用痕迹：常用工具是什么、输出格式怎么定、哪些地方必须确认、哪些动作可以直接做，都写得很具体。

• description — 加上你自己或团队常用的说法、关键词、触发场景。

• 触发条件和反例 — 确认不会和其他 Skill 冲突。

• 输入规范 — 加上团队特有的来源（飞书文档、内部系统链接）。

• workflow — 加上团队必须的检查点（如安全审查、术语一致性）。

• 输出格式 — 改成团队模板（标题结构、标签、归档规则）。

• 停止条件 — 加上团队的风险动作边界（如不自动发布、不自动修改权限）。

• 示例 — 换成团队真实 case。

还是用“飞书草稿整理成知识库文章”这个例子。假设你找到一个通用文档润色 Skill，它能改文字，但不知道团队知识库的发布口径；这时不要重写一套，而是先把它改到刚好能覆盖你的真实流程。

1. 先在聊天里完成一次真实任务，不急着抽象，让 Agent 暴露理解偏差和步骤遗漏。

2. 人持续纠偏：哪些地方必须确认、哪些动作不能自动做、哪些输出不算合格，都要在对话中说清楚。

3. 让强模型复盘整段聊天，提炼触发条件、输入要求、固定步骤、失败处理和验收标准。

4. 沉淀 SKILL.md，把长资料放进 references/，把稳定动作做成 scripts/ 或 CLI 示例。

5. 换一个同类任务，让较弱模型按 Skill 执行，看它是否还能完成，不再依赖临场解释。

6. 根据失败点继续改 Skill：补触发边界、补反例、补检查清单，直到它在真实任务里稳定减少返工。

改造后的 description
---
name: team-kb-writer
description: 当团队成员提供飞书草稿、会议纪要或技术方案，并要求整理成可发布的团队知识库文章时使用。先读取原文，提炼读者和目标，按团队模板重组结构，输出飞书文档和待确认事实清单。不自动发布，不自动 @人。
---

改造后的 workflow 可能增加以下步骤：

1. 检查来源文档权限，确认 Agent 可读。

2. 读取原文目录，判断篇幅和章节结构。

3. 按团队模板重组：标题 → 导语 → 正文章节 → 参考资料。

4. 标注待确认事实和缺失来源。

5. 输出到指定知识库空间（不自动发布）。

最小可用骨架
---
name: doc-polisher
description: 当用户提供飞书文档、Markdown 草稿或主题大纲，并要求整理成可发布的中文知识库文章时使用。
---

# 文档润色 Skill

## 触发条件
- 用户要求润色、改写、去 AI 味、整理成知识库文章。
- 用户提供草稿、链接或明确主题。

## 不适用
- 不处理法律、财务、医疗等需要专业审定的最终意见。
- 不凭空补事实；缺资料时先标注假设或追问。

## 工作流程
1. 读取原文或素材。
2. 提炼目标读者、用途和主线。
3. 先重组结构，再改句子。
4. 删除空泛表达、过度口号和模板化结尾。
5. 输出可直接发布的版本，并列出需要人工确认的事实。

## 输出要求
- 标题明确。
- 每节只讲一个问题。
- 结尾给读者下一步能做的动作。

校验 JSON、统计字数、抽取标题、读取飞书文档、更新文档、跑测试——这些动作不要每次让模型重想。能脚本化就脚本化，能用 CLI 就把命令和参数写清楚。

• 每次都执行且参数固定的动作（如读取飞书文档目录、校验 JSON 格式）。

• 涉及多步组合的操作（如先 fetch → 判断结构 → 按 section 精读）。

• 失败后有固定重试或回退路径的动作。

• 需要精确参数、人容易记错的命令。

不要只写”读取文档内容”。更好的写法是直接给出命令、参数选择逻辑和失败处理：

文档 Skill 中的 CLI 示例
# 第一步：读取文档目录，判断结构
lark-cli docs +fetch --api-version v2 --doc "$DOC_URL" --scope outline --max-depth 3

# 第二步：按章节精读目标段落（不要全量 fetch）
lark-cli docs +fetch --api-version v2 --doc "$DOC_URL" --scope section --start-block-id "$HEADING_ID" --detail with-ids

# 第三步：局部更新
lark-cli docs +update --api-version v2 --doc "$DOC_URL" --command block_replace --block-id "$BLOCK_ID" --content "<p>新内容</p>"

# 权限失败时：提示用户执行授权
# lark-cli auth login --scope "docx:document:readonly"

写完第一版 Skill 后，用这个清单检查它是否能投入使用：

• 用户换一种常见说法时，description 仍能触发。

• 缺少必要输入时，Skill 知道该追问、假设还是停止。

• 每个步骤都有明确动作，而不只是原则性描述。

• 输出格式固定，能被人或下一个流程继续使用。

• 至少有 3 个标准样例、2 个边界样例、1 个反例。

• 关键 CLI 或脚本调用有参数示例和失败处理。

• 停止条件明确：缺资料、权限失败、高风险动作、连续失败时有处理路径。

写到这里，Skill 只能算”能跑”。要变成生产力，还要能验证、能修、能退役。

如果一个 Skill 只能靠”我感觉这次不错”来判断质量，它还没进入生产力阶段。真正能跑起来的 Skill，通常都有评测、版本和复盘。

evals.json 示例
{
"skill_name": "team-kb-writer",
"evals": [
    {
      "id": 1,
      "prompt": "把 workspace/kb-drafts/product-launch-notes.md 整理成一篇可发布的团队知识库文章。要求保留原始来源链接，标出待确认事实，不要自动发布到飞书。workspace 放到 team-kb-writer-workspace/iteration-1/。",
      "expected_output": "产出一篇结构化知识库文章，包含标题、导语、章节结构、callout、来源链接、待确认事实清单和发布前检查项，同时保留整理过程的评测记录",
      "assertions": [
        { "id": "a1", "text": "识别出目标读者和发布目标" },
        { "id": "a2", "text": "输出包含标题、导语和清晰的章节结构" },
        { "id": "a3", "text": "保留原始来源链接，没有凭空补事实" },
        { "id": "a4", "text": "列出待确认事实和发布前检查项" },
        { "id": "a5", "text": "没有自动发布、修改权限或 @ 人" }
      ],
      "files": []
    },
    {
      "id": 2,
      "prompt": "workspace/kb-drafts/messy-meeting-notes.md 是一份结构混乱的会议纪要，请整理成团队知识库文章。里面有几处数据没有来源，需要明确标注出来。",
      "expected_output": "将混乱纪要重组为可阅读的知识库文章，并把无来源数据、口径不清的结论和需要人工确认的内容单独列出",
      "assertions": [
        { "id": "a1", "text": "没有照搬原始会议纪要顺序，而是重组为文章结构" },
        { "id": "a2", "text": "识别出缺少来源的数据或结论" },
        { "id": "a3", "text": "把待确认事实单独列出" },
        { "id": "a4", "text": "没有把不确定内容写成确定结论" }
      ],
      "files": []
    },
    {
      "id": 3,
      "prompt": "我改了 team-kb-writer 的 SKILL.md，把待确认事实的规则写得更严格了。请在 team-kb-writer-workspace/iteration-2/ 重跑评测，并和 iteration-1 的结果对比。",
      "expected_output": "在 iteration-2 目录重跑评测，生成新的 grading 和 benchmark，并对比 iteration-1，说明待确认事实识别是否变好、是否引入新的误伤",
      "assertions": [
        { "id": "a1", "text": "创建 iteration-2 目录，而不是覆盖 iteration-1" },
        { "id": "a2", "text": "重新运行评测，非复用 iteration-1 数据" },
        { "id": "a3", "text": "生成 iteration-2 的 benchmark 报告" },
        { "id": "a4", "text": "对比 iteration-1 和 iteration-2 的通过率或失败点" },
        { "id": "a5", "text": "说明规则变严后是否出现误伤" }
      ],
      "files": []
    }
  ]
}

每次失败都是改进的素材：

维护 Skill 时，不要每次遇到问题就重写整份说明。更常见、也更有效的做法，是把真实失败追加成 gotcha：什么情况下不要触发、哪个工具容易误用、哪类输入看起来相似但其实不该走这条流程、连续失败时应该停在哪里。

gotchas 的价值在于它来自真实任务，而不是想象中的完美流程。一个 Skill 越成熟，它不一定越长，但会更清楚地知道哪些路不能走。

你可以把 AI 当成”流程整理搭子”。先把一次完整协作过程交给 AI，让它帮你复盘：哪些步骤是可复用的，哪些判断是场景相关的，哪些资料应该放进 references，哪些动作值得脚本化。

• 模型原生能力已经覆盖该场景。

• 维护成本超过收益。

• 流程已经过时。

• 和新 Skill 大量重叠。

退役不是失败。Skill 太多而且互相打架，Agent 反而更难做对。留下能被复用、能被测试、能被别人接手维护的那部分就好。

• 选一个本周已经重复出现过的 case，最好有真实输入和真实交付物。

• 写一句清楚的 description：什么时候触发、输入是什么、输出是什么。

• 列出 5 步以内的 workflow，并标出哪一步不能省。

• 放 1 个好样例和 1 个反例，避免 Agent 只理解原则。

• 明确停止条件：缺资料、权限失败、高风险动作、事实不确定时怎么处理。

• 用同一个真实 case 跑一遍，记录失败点，再改下一版。