Skill 解决的不是知识问题

大模型通常知道“怎样制作演示文稿”或“怎样检查一个网站”，但知道方法不等于每次都能稳定执行。实际任务还包含环境约束、工具选择、操作顺序、风险边界和验收标准，这些信息很难靠一句提示词完整表达。

Skill 是一组可被 Agent 按需加载的任务说明和配套资源。它不为模型增加新的基础能力，也不会自动授予工具权限；它做的是把一类任务的可靠工作方法保存下来。

以网站维护为例，一个 Skill 可以明确要求：

  1. 修改前检查 Git 状态，避免覆盖已有改动
  2. 先阅读项目现有组件和样式，再决定实现方式
  3. 对代码块、表格和导航执行窄屏检查
  4. 运行类型检查与生产构建
  5. 只有在用户明确授权后才推送远程仓库

这些规则组合起来，才构成一套可重复执行的工程流程。

Skill 与相邻概念的边界

概念回答的问题典型内容
Prompt这一次要完成什么目标、输入、输出要求
ToolAgent 能执行什么操作文件读写、终端、浏览器、API
Skill这类任务应该怎样完成流程、约束、资源、验收
Plugin如何分发一组扩展能力Skill、工具和连接器的组合

工具提供执行能力，Skill 约束执行方法。一个 PDF 工具可能只负责读取和写入文件，而 PDF Skill 会进一步规定何时渲染页面、如何检查字体、怎样避免破坏书签，以及交付前需要验证什么。

Skill 也不是权限系统。即使说明中写着“上传文件”，Agent 仍然只能使用当前环境已经提供且允许调用的工具。

一个 Skill 的最小结构

最简单的 Skill 只需要一个文件：

website-audit/
└── SKILL.md

任务变复杂后，再按需加入资源：

website-audit/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
│   └── check-overflow.mjs
├── references/
│   └── browser-matrix.md
└── assets/
    └── report-template.md
  • SKILL.md 保存触发描述和核心流程
  • scripts/ 保存需要确定性、重复执行的程序
  • references/ 保存只在特定场景中读取的详细资料
  • assets/ 保存模板、图片和最终输出会使用的素材
  • agents/openai.yaml 可提供面向界面的名称、简介和默认提示

目录不是功能清单。没有实际用途的文件夹不应为了“看起来完整”而创建。

SKILL.md 中最重要的两部分

触发描述

文件顶部使用 YAML frontmatter 声明名称和描述：

---
name: website-audit
description: 检查静态网站的响应式布局、可访问性、构建结果和浏览器交互。适用于发布前复检、页面溢出排查和前端回归测试。
---

支持 Skill 发现的 Agent 会先看到名称和描述，再判断当前任务是否相关。因此，描述需要同时回答：

  • 这项 Skill 能做什么
  • 用户通常会怎样提出这类请求
  • 哪些相似任务不属于它

“帮助处理网站”过于宽泛；“检查静态网站的响应式布局和发布前回归”更容易正确触发。

执行说明

正文应该使用明确、可操作的步骤：

# Website audit

1. 读取项目配置、路由和全局样式
2. 运行类型检查与生产构建
3. 在 1440、1024、768、390 和 320 像素宽度下检查核心路由
4. 记录控制台错误、损坏图片和页面横向溢出
5. 验证菜单、筛选器、对话框和键盘操作
6. 修复后重复执行检查

高质量说明描述的是决策和验收，而不是把常识写成长篇教程。

为什么需要渐进加载

如果把 API 文档、示例、模板和所有边界条件全部塞进 SKILL.md，每次触发都会占用大量上下文，其中多数内容与当前任务无关。

更合理的方式是分层加载：

  1. Agent 始终只看到 Skill 的名称和描述
  2. Skill 命中任务后，读取 SKILL.md
  3. 流程需要某项细节时，再打开对应 references/
  4. 需要确定性执行时，直接运行 scripts/

这种方式被称为渐进式披露。它让核心流程保持短小，也降低无关信息干扰当前推理的概率。

哪些内容应该写成脚本

判断标准不是“能否用代码实现”，而是“是否值得确定性复用”。

适合进入 scripts/ 的任务包括：

  • 批量转换或校验文件
  • 检查固定格式与目录结构
  • 收集页面溢出、损坏链接和控制台错误
  • 根据稳定输入生成标准化输出

不适合脚本化的部分包括：

  • 根据业务语境判断文章是否准确
  • 选择最合适的视觉层级
  • 分析一次性、开放性的需求

脆弱且重复的步骤应该降低自由度；需要判断和创造的步骤应保留适当空间。

一个可用 Skill 的验收清单

触发是否准确

  • 描述是否包含具体任务和典型触发场景
  • 是否会与范围更宽的 Skill 发生冲突
  • 不相关请求是否可能误触发

流程是否可执行

  • 每一步是否能在当前工具环境中完成
  • 高风险操作是否要求确认
  • 是否说明遇到缺失输入或失败时怎样处理

资源是否合理

  • 重复逻辑是否已经脚本化
  • 详细资料是否从主文件中拆出
  • 同一知识是否在多个文件中重复维护

结果是否可验证

  • 是否定义构建、渲染、测试或人工检查
  • 是否能区分“文件已生成”和“任务已完成”
  • 修复后是否要求重新运行验证

常见反例

把 Skill 写成百科全书

模型已经拥有通用知识。长篇复制官方文档只会增加上下文成本。Skill 应优先保存环境特有、流程特有和容易遗漏的信息。

只写理想路径

“生成文件并交付”没有覆盖依赖缺失、构建失败、权限不足和用户已有修改。可靠流程必须说明失败后的处理方式。

用说明代替验证

要求“注意响应式布局”不等于真的检查过 320 像素宽度。能自动验证的部分应尽量转化为命令或脚本。

把错误经验固化

Skill 会稳定地重复规则，因此过时或错误的说明比一次性错误更危险。Skill 应像代码一样经过真实任务测试和持续维护。

什么时候值得创建 Skill

一类任务同时具有重复性、明确流程和质量风险时，Skill 的收益最高。例如：

  • 生成并复检演示文稿
  • 保留格式地编辑 Word 文档
  • 审查 GitHub Pull Request
  • 构建并验证静态网站
  • 按企业规范生成报告

一次性问答、纯探索讨论或每次路径完全不同的任务，通常不需要单独创建 Skill。

结论

Skill 的价值不在于让模型“知道更多”，而在于把触发条件、执行方法、工具资源和验收标准组织成可维护的能力单元。

好的 Skill 应该短、准、可执行、可验证。它保留真正影响结果的工程经验，同时把脚本、参考资料和素材放在各自合适的位置。这样，一次成功完成任务的方法才能成为下一次可以可靠复用的工作流。