What is a Skill
What if your agent could remember how to solve problems it's seen before? That's what a Skill is.
The Problem With Chat Logs
Yesterday you and your agent spent twenty turns working out how to roll back a payment API safely: which region to switch first, how to tell a real recovery from a half-open one, when to stop. It worked, and the knowledge went into a chat log nobody will ever open again.
This morning a teammate hits the same incident. Their agent starts from zero and rediscovers the same lessons, one expensive turn at a time. The knowledge existed. It just wasn't in a form anything could load.
A Skill is that knowledge written down in a form an agent can load by itself: a markdown file that says what the procedure is, and metadata that says when it applies.
What Makes It More Than a Note
Three properties do the work here.
- It's versioned. Each Skill lives in its own git repository, so every edit has an author, a diff, and a way back. You can ask why a step exists and get an answer.
- It's self-selecting. The metadata carries a name, a description, and triggers, so the agent decides when to pull the Skill in. You don't paste it; you don't have to remember it exists.
- It's measured. New versions run against a slice of real traffic and get scored. A version that makes things worse loses and gets discarded, instead of quietly sitting in your prompt for six months.
There's a cost angle too, and it follows directly from chapter A. A Skill loads near the front of the message list where it is cached at $P_{cr}$ from the second turn onward, and it cuts the number of turns a task needs. Cheap tokens, fewer turns — both levers at once.
What One Looks Like
A Skill is a directory containing a SKILL.md, plus any scripts or reference files the procedure needs. The file starts with YAML frontmatter and continues as ordinary markdown:
---
name: api-rollback-runbook
description: Production API rollback runbook — half-open state probing,
multi-region switch order, and SLO burn estimation.
metadata:
version: 4
state: staging
domain: sre
tags: [api, rollback, incident, canary]
---
# api-rollback-runbook
## When to use this
A deploy is live, error rate is climbing, and you are deciding
whether to roll back rather than how to fix forward.
## Probing for half-open state
A rollback often looks recovered while some instances still run
the bad version. Within 3–5 minutes of cutting traffic:
1. Pull a histogram by instance version label; confirm the bad
version's weight is genuinely zero.
2. Probe the same user_id five times in a row; watch for flapping.
3. Compare the version header at edge against origin.
## Multi-region order
Smallest region first, then primary, then the furthest backup.
Never roll back regions in parallel.Notice that it reads like a runbook a competent colleague would write, not like a prompt. That's deliberate: the audience is an agent that already speaks English, so the useful content is the judgement, the ordering, and the traps — not instructions on how to be helpful.
How It Compares
You've probably tried at least one of these already:
| Approach | What it is | Where it falls short |
|---|---|---|
| Prompt library | Snippets you keep in a doc and paste when relevant | You have to remember it exists, and nobody knows which copy is current |
| RAG | Documents chunked and retrieved by similarity | Tuned for answering questions, not executing procedures; retrieval brings back three half-relevant chunks instead of one right one |
| Workflow YAML | Explicit steps and branches in a graph | Rigid — the moment reality differs from the graph, it stalls, and changing it needs an engineer |
| Skill | Versioned markdown procedure plus trigger metadata | Needs enough real trajectories before it's worth writing one |
The honest summary: a Skill sits between a prompt snippet and a workflow. It's more durable and more discoverable than a snippet, and more flexible than a graph — the agent still gets to think, it just doesn't have to think from scratch.
Coming soon: detailed anatomy of a Skill file — the full metadata schema, trigger design, and an authoring guide.
Next, let's look at where Skills actually earn their keep.
什么是 Skill
如果你的 Agent 能记住它以前解决过的问题，那会怎样？Skill 就是这件事。
聊天记录的问题
昨天你和 Agent 花了二十轮，弄清楚怎么安全回滚支付 API：先切哪个 region、怎么分辨真恢复和半开状态、什么时候可以收手。事情办成了，而这些经验进了一份再也不会有人打开的聊天记录。
今天早上同事碰到同一个故障。他的 Agent 从零开始，一轮一轮地把同样的教训重新发现一遍，每一轮都要花钱。经验是存在的，只是没有以任何东西能加载的形式存在。
一个 Skill，就是把这些经验写成 Agent 自己能加载的形态：一个 markdown 文件写清流程是什么，一段元数据说明它什么时候适用。
它凭什么不只是一篇笔记
关键在三个属性。
- 它有版本。每个 Skill 都在自己的 git 仓库里，所以每一次改动都有作者、有 diff、有回退路径。你可以追问某一步为什么存在，而且能得到答案。
- 它自己会被选中。元数据里带着名字、描述和触发条件，所以是 Agent 决定什么时候把它拉进来。你不用粘贴，也不用记着它的存在。
- 它被度量。新版本会在一小部分真实流量上跑并被打分。让效果变差的版本会落选、被淘汰，而不是悄悄在你的 prompt 里躺半年。
还有一个成本角度，而且是 A 章的直接推论。Skill 加载在消息列表靠前的位置，从第二轮起就按 $P_{cr}$ 计费；同时它减少了一个任务需要的轮次。便宜的 token 加更少的轮次，两根杠杆一起动。
它长什么样
一个 Skill 是一个目录，里面有 SKILL.md，以及这个流程需要的脚本或参考文件。文件开头是 YAML frontmatter，往下就是普通 markdown：
---
name: api-rollback-runbook
description: 生产 API 回滚 runbook：半开状态探测、多 region 切换顺序、
以及 SLO 烧损估算。
metadata:
version: 4
state: staging
domain: sre
tags: [api, rollback, incident, canary]
---
# api-rollback-runbook
## 什么时候用它
一次发布已经上线，错误率在往上走，你要决定的是回滚还是往前修。
## 探测半开状态
回滚常见「看起来恢复、其实半开」：一部分实例仍是坏版本。
缩流量后 3–5 分钟内完成：
1. 按实例版本标签拉直方图，确认坏版本权重真实为 0。
2. 对同一个 user_id 连续探测五次，看是否跳变。
3. 对比 edge 与 origin 的版本头。
## 多 region 顺序
先流量最小的 region，再主 region，最后最远的备份 region。
禁止多 region 并行回滚。注意它读起来像一个靠得住的同事写的操作手册，而不像一段 prompt。这是刻意的：读者是一个本来就懂中文的 Agent，所以真正有价值的内容是判断、次序和坑，而不是「请你乐于助人」这类交代。
和其他做法比一比
下面这几种你大概至少试过一种：
| 做法 | 是什么 | 短板在哪 |
|---|---|---|
| Prompt 库 | 攒在文档里、需要时粘贴的片段 | 你得记得它存在，而且没人知道哪份拷贝是最新的 |
| RAG | 把文档切块，按相似度检索 | 它是为回答问题调的，不是为执行流程调的；检索常常捞回三段半相关的，而不是一段对的 |
| 工作流 YAML | 把步骤和分支画成显式的图 | 太死 —— 现实一旦和图不一样就卡住，而改图得找工程师 |
| Skill | 带版本的 markdown 流程，加上触发元数据 | 得先有足够多的真实轨迹，才值得写一条 |
老实说：Skill 的位置在 prompt 片段和工作流之间。它比片段更持久、更容易被找到，又比图更灵活 —— Agent 仍然可以思考，只是不必从零开始想。
即将推出：Skill 文件结构详解 —— 完整的元数据 schema、触发条件设计，以及编写指南。
下一节我们看看 Skill 到底在什么地方真正值这个钱。