skills 用来给 agent 增加可复用能力。AGENTS.md 放常驻项目事实，skill 放按需执行的专业知识、流程、脚本和模板。

我理解一个 skill 至少要回答三个问题：

  • 什么情况下使用它？
  • 使用时按什么步骤做？
  • 需要读取哪些额外参考材料、脚本或模板？

Agent Skills 的核心思想是 progressive disclosure：启动时只暴露 name 和 description；任务命中后再读完整 SKILL.md；更长的参考资料、脚本和模板等到真的需要时再加载。

适合做成 skill

  • Hexo 新文章流程
  • LaTeX 编译和排错流程
  • 发布前检查流程
  • code review checklist
  • changelog 生成
  • 数据处理报告流程

不适合做成 skill

  • 项目简介
  • 构建命令
  • 禁止修改目录
  • API key
  • 一次性提示词

基本结构

一个 skill 是一个目录，最少包含 SKILL.md：

1
SKILL.md

推荐目录结构：

1
2
3
4
5
6
7
8
<skill-name>/
  SKILL.md
  references/
    example.md
  scripts/
    helper.py
  assets/
    template.md

SKILL.md 写触发条件和主流程。references/、scripts/、assets/ 只在需要时再读，不要把所有细节都塞进入口文件。

SKILL.md 格式

SKILL.md 使用 YAML front matter 加 Markdown 正文。最小字段：

1
2
3
4
---
name: skill-name
description: A description of what this skill does and when to use it.
---

字段大致是：

  • name：必填，建议使用小写字母、数字和连字符，和目录名保持一致。
  • description：必填，说明 skill 做什么、什么时候用。
  • license：可选，说明 skill 的许可。
  • compatibility：可选，只在有明确环境要求时写，例如需要特定系统包、网络访问或运行时。
  • metadata：可选，放作者、版本等额外信息。

正文没有固定格式，但最好包含执行任务需要的核心步骤、示例、边界条件和验证方式。

SKILL.md 示例

SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
---
name: hexo-post
description: Use when creating, editing, or reviewing Hexo blog posts, especially front matter, categories, tags, and local build checks.
---

## Workflow

1. Inspect nearby posts before editing.
2. Preserve the existing front matter style.
3. Edit only the requested post unless asked otherwise.
4. Do not touch generated files under `public/`.
5. For Markdown-only changes, mention that no build was run.

description 要写清楚触发场景。agent 通常先看到 skill 名称和 description，真正用的时候才读完整内容。

SKILL.md 不宜过长。入口文件只放每次触发都需要的内容，长规范、错误码、模板说明、历史约定拆到 references/。

description 怎么写

description 决定 skill 会不会被正确触发。它应该写“什么时候用”，不要写“这个 skill 很有用”。

好的写法：

1
description: Use when creating, editing, or reviewing Hexo blog posts, especially front matter, categories, tags, and local build checks.

不好的写法：

1
description: A useful skill for blog writing.

触发描述里应该包含：

  • 任务类型：creating、editing、reviewing、debugging、publishing。
  • 对象范围：Hexo posts、LaTeX documents、release notes、API docs。
  • 关键场景：front matter、build checks、changelog、migration。

Workflow 怎么写

workflow 应该是可执行步骤，不是原则堆叠。

推荐写法：

1
2
3
4
5
6
7
## Workflow

1. Inspect nearby examples before editing.
2. Preserve the existing file structure and naming style.
3. Make the smallest change that satisfies the request.
4. Run the documented validation command when the change affects behavior.
5. Report what changed and whether validation was run.

避免写法：

1
2
3
4
5
## Workflow

- Be careful.
- Write high quality content.
- Follow best practices.

这种句子太抽象，agent 很难稳定执行。

progressive disclosure

skill 的目录结构应该服务于按需加载：

  • metadata：name 和 description，用于发现 skill。
  • instructions：SKILL.md 正文，用于执行主流程。
  • resources：references/、scripts/、assets/，只在任务需要时读取或运行。

写入口文件时，最好明确告诉 agent 什么时候读取哪个资源：

1
2
3
When editing front matter, read `references/frontmatter.md`.
When the build fails with a theme error, read `references/theme-errors.md`.
When generating a new post, use `assets/post-template.md`.

不要写成：

1
See references/ for details.

这种说法太模糊，agent 不知道什么时候该加载哪个文件。

references

references/ 适合放较长、低频、但需要时很重要的材料，例如：

  • front matter 规范
  • 发布检查清单
  • 错误码说明
  • 模板变量说明
  • 项目历史约定

入口文件里只写“什么时候读哪个 reference”，不要把 reference 全文复制进去。

示例：

1
2
When editing front matter, read `references/frontmatter.md`.
When preparing release notes, read `references/release-note-style.md`.

scripts

scripts/ 适合放能减少手工错误的脚本，例如：

  • 生成文章骨架
  • 校验 front matter
  • 提取 changelog
  • 检查链接
  • 转换数据格式

脚本应该小而确定，输入输出清楚。不要把需要 agent 自己判断的大段业务逻辑塞进脚本。

脚本还应该：

  • 自包含，或者清楚写出依赖。
  • 有明确参数和退出码。
  • 报错信息能帮助 agent 判断下一步。
  • 处理常见边界情况。

assets

assets/ 适合放模板、示例文件、固定素材，例如：

  • Markdown 模板
  • LaTeX 模板
  • JSON schema
  • 配置片段
  • 示例请求体

如果模板会被复制到项目里，文件名要直观，内容里不要包含真实凭据。

维护方式

  • 一个 skill 只解决一类任务。
  • 入口文件保持短，复杂细节拆到 references。
  • workflow 只写稳定步骤，临时策略不要长期保留。
  • 示例要能直接复用，不要带真实密钥、账号或私有地址。
  • 如果某个 skill 经常被误触发，优先改 description。
  • skill 应该来自真实任务经验，而不是泛泛总结。
  • 写完后要用真实任务试跑，再根据 agent 的执行轨迹删掉无用步骤、补上遗漏边界。

参考