Skip to main content

怎么写一个 Agent Skill？

· 6 min read

写 Agent Skill 最容易踩的 4 个坑，加一份最小可用的模板。

  1. 最小目录：一个 SKILL.md，Agent 只加载这一份。
  2. 核心定位：description 决定何时调，不是"能做什么"。
  3. 坑一：description 写漂亮话 = 装了个寂寞。
  4. 坑二：SKILL.md 里塞百科，首次加载被拖垮。
  5. 坑三：把 Agent 已经会的事写进去，浪费 token。
  6. 坑四：装太多 Skill = 每轮白付 token。
  7. 结论：Skill 的价值 = 领域知识 + 不可替代的本地动作。

最小可用目录​

只一个文件就能跑：

my-skill/
└── SKILL.md
tip

SKILL.md 必须放在一个独立文件夹下，比如 my-skill/SKILL.md，不能用 my-skill.md 这种扁平文件——后者 Claude Code / Skills Manager 都不会自动加载。

Agent 只加载这一个文件——读 name 和 description 决定何时调，读正文拿到工作流。

最小 SKILL.md：

---
name: my-skill
description: 一句话"做什么" + "何时调用"。
  description 是 Agent 判断要不要调你的唯一信号。
---

## 何时调用
- 用户说 "..."
- 上下文出现 "..."

## 步骤
1. ...
2. ...

扩到 5-6 个文件，能力上天：

my-skill/
├── SKILL.md        # Agent 加载的唯一入口
├── schema.yml      # 强校验：Agent 输出必须符合这个 schema
├── templates/      # 输出文件模板（.drawio / .pptx / HTML ...）
├── examples/       # 输入 → 输出示例（喂给 Agent 当 few-shot）
├── scripts/        # 本地脚本（Python / JS / shell）
└── references/     # 详细文档（按需加载，不进入主 prompt）

Agents365-ai 的 drawio-skill 就是这个范式的标准实现——SKILL.md 只放工作流，详细文档全部塞 references/，主入口永不膨胀。

四件最容易踩的坑​

坑 1：description 写错 = 装了个寂寞​

description 是 Agent 何时调你这个 Skill 的唯一信号。

写法触发率
"强大的 PPT 生成器"几乎不调
"把会议纪要转成 16:9 PPT，当用户说'做个分享'时使用"精确触发

不要写漂亮话，直接写触发场景。

万能模板：

description: 一句话"做什么" + "当用户说... / 当上下文出现... 时使用"。

后半句"当 ... 时使用"是关键，写了触发率立刻拉满。

坑 2：SKILL.md 里塞百科​

SKILL.md 是触发用的入口，不是 README。Agent 不光第一次加载要读，每次调用都会把整个 SKILL.md 塞进主 prompt。

正文控制在 200 行以内——只放"何时调用 + 步骤 + 输出格式"。"字段定义、详细示例、出错处理"全放副文件，SKILL.md 里用 [[文件名]] 引用即可。这是 Anthropic 官方文档 强调的"渐进式披露"原则。

判断哪句该写哪句不该：

写进 SKILL.md别写
"调 schema.yml 校验"（指引 Agent 去做）"打开文件 → 读 JSON → 解析 → 输出结果"（Agent 已经会）
"按需查 templates/<场景>.yaml"（指引路径）"找到 templates 目录下名字叫 xxx 的文件"（Agent 已经会找）

坑 3：把 Agent 已经会的写进去​

❌ "步骤 1: 读取 JSON 文件"
✅ "步骤 1: 调 schema.yml 校验 → 失败时直接报错"

Agent 已经会读 JSON、写文件、跑命令，你写它反而拖慢首次加载速度。Skill 的价值是"领域特定知识 + 不可替代的本地动作"，普通 CRUD 步骤就别教育它了。

坑 4：Skill 不要装太多​

每轮对话 Claude Code 都会把你装的所有 Skill 的 name + description 发给模型。

warning

Anthropic 的 Agent Skills 设计里，每个 Skill 的 name 和 description 会被作为 prompt 的一部分送给模型——这是触发机制的必要前提。SKILL.md 正文只在 Agent 决定调你的时候才加载（这就是"渐进式披露"原则），但 name + description 没有按需加载机制。

后果：

  • 装 20 个 Skill 即便从来不调，每次也都额外吃几百到几千 token
  • description 写得越啰嗦，context 越快爆
  • 装 Skill 上瘾堆到 50+ 时，Agent 真正能用的 context 窗口会被吞掉一大半

清理节奏：每周花 2 分钟翻一遍 ~/.claude/skills/，按这个标准处理——

状态处理
过去一周没调过直接删
偶尔调不是高频留着，每月复查
每天 / 每周都用留着

实操工具：Skills Manager 的全局 / 项目 / 预设三层设计就是解决这个——把 Skill 从"永久装着"变成"按需启用"。

一份合格的 SKILL.md 实例​

---
name: drawio-architecture
description: 生成系统架构图（组件、依赖、调用关系）。
  当用户说"画一下架构 / 拓扑 / 模块依赖"时使用。
---

## 何时调用
- 用户说"画一个系统架构"
- 上下文出现"组件 / 模块 / 服务 / 依赖关系"

## 工作流
1. 解析用户输入，提取 components / edges / groups
2. 按 schema.yml 校验字段
3. 调 scripts/cli.js 生成 .drawio
4. 视觉自检：节点重叠 / 文字截断 → 自动修复
5. 输出文件路径给用户

留意 frontmatter 的 description 不只是"这个 skill 能做什么"，而是**"什么时候调它"**——这一行决定了 Agent 在几十上百个 skill 里翻到它的概率。

Skill vs MCP：用这个判断​

Skill 的价值 = 领域知识 + 不可替代的本地动作

更直接地说——

  • 领域知识：你不想在 prompt 里重复写的内部规范、API 怪癖、专有框架
  • 本地动作：shell 命令、文件操作、需要特定环境才跑得动的脚本
写的 Skill 大部分是应该用
调工具 / 循环执行 / 读文件这不该是 Skill，让 Agent 调 MCP 工具
写 PPT / 出 PDF / 行业规范该写成 Skill
私有仓库操作 / 团队协议该写成 Skill

如果你发现自己写的 SKILL.md 大段在描述"打开 A、做 B、做成 C"——那是普通 prompt 文案，不是 Skill。把它塞到 agents.md 或 system prompt 里就够了，不必动用 Skill 范式。

References​

  1. Anthropic Agent Skills 官方文档 —— Skill 触发 / 加载机制的权威解释
  2. agentskills.io/specification —— Skill 文件结构的标准规范
  3. drawio-skill 实战案例 —— 用画图这件事走完一个完整 Skill 范式流程
  4. Skills Manager —— 多 AI 工具的 Skill 统一管理（中央库 + 工作区 + 预设）
  5. book-to-skill —— 另一种 Skill 范式，把书拆成 Skill
  6. Karpathy 4 条规则 —— SKILL.md 写作同样适用 Simplicity First