Agent Skills 不完全指南

小蜗1号
228 阅读6分钟

此前在浏览 GitHub 一周热榜时，注意到了 Agent Skills，便关注了一下。当时正值 1 月初，许多 IDE 和 Agent 的 CLI 工具对其支持尚不成熟。

上周浏览掘金时，发现已有不少文章介绍这一概念，加之越来越多的工具开始支持，于是整理了一些使用经验，分享给刚接触的同学，希望能帮助大家少走弯路。

Skills 到底是什么？

先简单科普一个概念：Skills 到底是什么？

简而言之，Skill 就是一个 SOP（Standard Operating Procedure，标准作业程序）。

它不仅仅是一个工具包，更是一套过程知识（Procedural Knowledge）。它告诉 Agent 在特定场景下应当如何思考、遵循什么步骤、参考什么标准来把事情做好。

它和 MCP（Model Context Protocol）并不相同，最大的区别在于 上下文加载方式。

和 MCP 的一个直观对比

举个例子：

  • 你写了一个 MCP Server
  • 然后把它配置到 Host 中
  • 那么在 Agent 初始化时：
    • 所有工具
    • 以及对应的参数 JSON Schema 都会一次性注入到上下文中

如果你接入的 MCP 比较多，很容易出现一个问题：任务还没开始，上下文已经消耗了一大截。

而 Skills 采用的是“渐进式披露（Progressive Disclosure）”，机制上更为高效，官方定义为三个阶段：

  1. Discovery（发现阶段）

    • 只加载 name 和 description（约 100 tokens）
    • Agent 仅感知“我具备什么能力”及“何时使用它”，不占用多余上下文

  2. Activation（激活阶段）

    • 当用户请求与 Skill 描述（description）匹配时
    • 例如：

      从这个 PDF 中提取文本并总结

    • Agent 决定激活对应 Skill，此时才会全量加载 SKILL.md 的正文指令

  3. Execution（执行阶段）

    • Agent 根据 Skill 正文中的指示
    • 按需加载 具体的 references/ 文档或执行 scripts/ 代码
    • 任务完成后释放上下文

img

更详细的机制可以直接看官方文档： 👉 agent-skills/overview

Skills 对日常工作的意义

那么，Skills 对日常开发或写作有什么实际价值？

简单来说：

Skill = 可执行的说明书

举几个常见场景：

  • 代码审查规范
  • 团队内部的文档书写规范
  • API 调用约定
  • 项目初始化流程
  • 发布 Checklist

这些内容如果只写在 Wiki 里，很难被 Agent “正确且稳定地使用”；但如果整理成 Skill，就可以在合适的时候被加载和执行。

示例：中文写作规范 Skill

下面用一个 中文写作规范 Skill 来举例。

此前读过阮一峰老师编写的 👉 中文技术文档的写作规范

这套规范非常好，但实际写作中容易凭感觉，难以完全遵守。

于是它就非常适合作为一个 Skill，用来约束 Agent 的输出。

Skill 目录结构

一个推荐的 Skill 目录结构如下：

chinese-article-writing/  <-- 注意：目录名必须与 SKILL.md 中的 name 字段完全一致
├── SKILL.md              # 必须：元数据 + 使用说明
├── scripts/              # 可选：可执行脚本
├── references/           # 可选：参考文档
└── assets/               # 可选：模板、资源文件

在这个例子中：

  • scripts/ 和 assets/ 并不需要
  • references/ 非常重要，用于存放写作规范的具体条目

编写 SKILL.md（元数据）

SKILL.md 顶部必须包含 YAML 格式的元数据（Frontmatter）。

根据官方规范，这里有两个硬性约束需要注意：

  1. name 必须与文件夹名称完全一致
  2. name 只能包含小写字母、数字和连字符（-），且不能以连字符开头或结尾（不支持大写或空格）

例如官方文档中的示例：

---
name: pdf-processing # 合法
description: Extract text and tables from PDF files...
license: Apache-2.0
metadata:
  version: '1.0'
---

更完整的规范可以参考： 👉 agentskills.io/specificati…

中文写作 Skill 的元数据示例

我们定义 chinese-article-writing/SKILL.md 的头部信息：

---
name: chinese-article-writing
description: 用于指导和规范中文文章、技术文档、技术分享内容的写作风格、结构与语言表达。
---

这里 description 非常重要，额外强调几点：

  • 这是 给 Agent 在 Discovery 阶段看的
  • 要用 第三人称 描述
  • 不要写“这是一个……的 Skill”
  • 要回答清楚一个问题：

用户在做什么事情时，应该用这个 Skill？

一个不太好的例子：

name: 文章书写助手
description: 中文文档、文章、技术分享等内容的书写规范。

这个描述对 Agent 来说太泛了，很难和具体用户意图匹配。

SKILL.md 正文结构建议

虽然 Skill 对正文结构没有强制要求，但强烈建议至少包含这两个部分：

## When to use this skill

## How to use this skill

结合中文写作规范，可以这样来写：

# 中文文章书写助手（chinese-technical-writing Skill）

本技能用于指导中文文章的书写，解决“不知道如何写、只能凭感觉写”的问题。请在生成或修改文章时参考并遵守。

## When to use this skill

当用户需要以下任务时，使用本技能：

- 编写中文技术文章、博客或技术分享
- 规范或润色已有中文文档
- 统一文章风格与结构
- 提高文章的专业性与可读性

## How to use this skill

1. 明确文章类型与目标读者
2. 确定整体语气和风格
3. 按目录顺序应用对应写作规范
4. 在生成或修改内容时持续对照规范调整

## 中文写作规范

中文技术文档的通用写作规范。

### 目录

1. [标题](./references/title.md)
2. [文本](./references/text.md)
3. [段落](./references/paragraph.md)
4. [数值](./references/number.md)
5. [标点符号](./references/marks.md)
6. [文档体系](./references/structure.md)

references 目录

最后一步：

这样：

  • 初始化阶段：只加载 name / description
  • 用户请求润色文章 → 激活 Skill
  • 遇到具体规则 → 按需加载对应 reference
  • 完成润色 → 结束流程

Skills 和 MCP 的关系（总结）

很多人可能对此感到困惑，所以单独总结一下：

  1. 不是互斥，而是互补

    • Skill 可以明确说明：在什么情况下调用某个 MCP 工具
    • MCP 负责“连接真实世界”
    • Skill 负责“教模型把事情做好”

  2. 加载方式不同，Token 消耗不同

    • MCP：初始化即加载
    • Skill：按需加载

  3. 信任模型的程度不同

    • Skill：

      我通过 SKILL.md 告诉你怎么做，我相信你能做好

    • MCP：

      我必须把所有步骤、参数、边界条件都明确下来，由我来控制执行

最后

本文旨在 抛砖引玉。

关于 Skills 其实还有很多可以深入的方向，比如：

  • 团队级 Skill 设计
  • Skill 与 Prompt / System Message 的边界
  • Skill 的版本管理
  • 如何设计“高命中率”的 description

限于篇幅，也为了留出思考空间，后续有机会再作分享。

如果文中有理解不准确的地方，也非常欢迎补充和讨论 🙌

上述的完整 Skill 示例我上传到了my-skills 仓库，可以点击以阅读进行查看。

avatar
文章
阅读
粉丝