SKILL.md 怎么写才可复用：一份给 AI Agent 的技能说明书

把能力封装成 Skill，是这两年 Agent 生态里最常见的一种复用方式。但绝大多数人第一次写 SKILL.md 时，都会写成"给同事看的操作手册"——结果是模型每次都要重新猜你的意图。

最近把一个「小红书种草笔记生成」能力做成了 Skill，从起草到同时在两个市场发布，中间踩了几个值得记下来的坑。

一、SKILL.md 的四段结构

一个能被稳定触发的 Skill，目录结构基本固定：

skill-name/
├── SKILL.md          # 必需：元数据 + 指令
├── scripts/          # 可选：可执行脚本
├── references/       # 可选：参考资料
└── examples/         # 可选：输入输出样例

SKILL.md 本身只有两块：开头的 YAML frontmatter，和正文的 Markdown 指令。

---
name: xhs-note-gen
description: 生成小红书风格种草笔记。输入产品名和核心卖点，输出包含场景化开头、真实体验感正文、痛点共鸣点、带 emoji 话题标签的完整笔记。
---

二、description 决定成败

模型不是"读完整个 Skill 再决定用不用"，而是先拿 name 和 description 去和当前诉求做匹配。description 写得含糊，Skill 就永远不会被触发。

有效的 description 有三个特征：

• 写做什么，不写怎么做。"生成小红书种草笔记"是做什么；"调用 generate_note.py 传参"是内部实现，不该出现在这里。
• 带触发词。把用户可能说的说法都列上：种草笔记、写小红书、种草文案、产品推荐文案。
• 长度控制在 200 字内。多数平台的市场页会直接摘这段当简介，太长会被截断。

三、三个具体的坑

1. 指令写成散文，模型执行不稳定

正文里"你应该尽量让语气自然一点"这类描述，模型没法量化。改成可执行的判据：

## 输出要求
- 开头 2 句必须是场景化描述，出现具体时间、地点或动作
- 正文至少 1 处第一人称具体体验（"我用了两周"而非"用过的人都说好"）
- 结尾 5-8 个话题标签，每个以 # 开头，间隔一个空格

2. 脚本路径写死绝对路径

Skill 在本地开发时路径是 /root/workspace/xxx，发布到市场后运行环境完全变了。统一按 Skill 根目录相对路径引用，并在 SKILL.md 里明确写出当前工作目录假设。

3. 没有失败分支

只写"成功路径"的 Skill，一旦脚本报错模型就卡住。至少补一句：脚本执行失败时先检查依赖是否安装，再降级为纯文本生成，不要直接抛给用户。

四、怎么验证它真的可用

不要用"看起来合理"的输入去测。准备三档：

1. 标准输入：产品名 + 3 条卖点，看是否输出完整结构。
2. 极简输入：只说"帮我写个吹风机的种草"，看是否会主动追问缺失信息，而不是编造参数。
3. 越界输入：给一个和种草完全无关的诉求（比如"帮我写个 SQL"），看是否正确不触发。

第三档最容易被忽略，但它是 Skill 被误触发的主要来源。

五、发布后的两件事

Skill 发到市场之后，有两件事必须做：一是补一份真实的输入输出样例，让使用者知道边界在哪；二是记录版本变更点，因为 Skill 的兼容性问题和接口一样，改一个字段就可能让老调用全挂。

这次从起草到双市场发布大概花了一个下午，真正写内容的时间不到三分之一，剩下的都在处理元数据、打包格式和审核要求。把规范摸清楚之后，第二个 Skill 大概二十分钟就能上线。