怎么写专业的 Skill

你有没有过这种经历:给 AI Agent 写了一个 Skill,它能跑,但总是触发不准、执行不稳、隔两天就出 bug?就像做菜——照着网上的菜谱做,味道对,但跟大厨做的差了点什么。

差的那点东西,就是专业性。

我维护过一个 10 万行级别的 Skill(WeWrite 公众号全流程助手),从最初的一个简单脚本迭代到现在。过程中踩过的坑、总结的方法论,今天系统性地分享出来。

先搞清楚:Skill 是什么

30 秒版本:Skill = 给 AI Agent 的工作手册。

不是提示词(prompt),不是 API 文档,而是一份结构化的操作指南,告诉 Agent:

  • 什么时候该被触发(trigger)
  • 怎么一步步完成任务(workflow)
  • 什么情况下会出错以及怎么处理(pitfall)
  • 做完之后怎么验证结果(verification)

一个 Skill 的物理结构长这样:

my-skill/ ├── SKILL.md              # 核心指令(必需) ├── scripts/              # 可执行脚本 │   └── helper.py ├── references/           # 参考文档 │   ├── api.md │   └── best-practices.md └── templates/            # 模板文件    └── output.md

SKILL.md 是唯一必需的文件,其他都是辅助。但专业的 Skill 和入门级 Skill 的差距,恰恰就在这些辅助文件里。

能跑 vs 专业:一个对比

我用两个真实案例来说明差距。

案例 A:入门级 Skill(aihot)

这是一个查询 AI 资讯的 Skill,核心功能正确,结构清晰。它的 frontmatter 长这样:

--- name: aihot description: AI HOT 资讯查询 Skill。当用户想知道"今天 AI 圈有什么"时使用。 ---

工作流部分只有一段核心命令:

since=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ) curl -s "https://aihot.virxact.com/api/public/items?mode=selected&since=$since"

能用吗?完全能用。 239 行代码,11KB 大小,功能完整。

案例 B:专业级 Skill(WeWrite)

同样是完成一个任务,WeWrite 这个公众号写作 Skill 有这些额外的东西:

维度入门级 (aihot)专业级 (WeWrite)
Frontmattername + description完整元数据 + tags + related_skills + version
触发条件一句话描述20+ 触发关键词 + 反向触发词(何时不用)
工作流1 个主路径8 步流水线,每步有输入输出定义
错误处理无每个步骤有 fallback + 已知坑位手册
辅助文件无references/ (7个文档) + scripts/ (5个脚本) + personas/ (人格库)
验证方法手动测试自动化质量检查(禁用词扫描、human-ness 评分)
迭代机制无history.yaml 记录每篇文章的元数据,避免重复

文件大小:11KB vs 103KB+。 不是故意写长,而是每个字节都在解决一个实际问题。

专业 Skill 的五个关键维度

1. Frontmatter:Agent 决定是否加载你的 Skill 的唯一依据

这是最重要也最容易被忽视的部分。

Agent 在加载 Skill 之前,只能看到 frontmatter 里的 name 和 description。 如果这两个字段写得不好,你的 Skill 就像一本没有封面的书——再好也没人打开。

入门级写法:

--- name: my-skill description: 帮我做 X 事 ---

问题:太泛。"帮我做 X 事"可以匹配任何请求,导致过度触发(在不该用的时候被加载)或者触发不准(在该用的时候没被选中)。

专业级写法:

--- name: commit-message-generator description: |  Use when the user wants to generate conventional commit messages based on  staged git changes. Covers feat/fix/docs/refactor/test/chore types.  Triggers on: "commit message", "生成提交信息", "git commit", "提交说明".  Do NOT use for: general text writing, PR descriptions, or changelogs. version: 1.2.0 author: your-name license: MIT metadata:  hermes:    tags: [git, commit, conventional-commits, automation]    related_skills: [github-pr-workflow, github-code-review] ---

关键改进:

  • description ≤ 1024 字符(Hermes 硬性限制),但要把触发条件写清楚
  • 明确反向触发词(Do NOT use for):减少误触发
  • 添加 metadata:tags 用于分类检索,related_skills 用于关联推荐
  • 版本号:方便后续迭代追踪

2. 结构化指令:让 Agent 能"按图施工"

入门级的指令通常是段落式的:

先拉数据,然后处理一下,最后输出结果是 Agent 对"处理一下"的理解可能跟你完全不同。

专业级用分步骤 + 表格 + 代码块的组合。下面是一个工作流片段的写法示例——先定义参数表,再给命令:

参数值说明
端点/api/public/items主数据接口
modeselected精选模式(默认)
since动态计算最近 24 小时
# 计算时间窗口(兼容 macOS 和 Linux) if [[ "$OSTYPE" == "darwin"* ]]; then  since=$(date -u -v-24H +%Y-%m-%dT%H:%M:%SZ) else  since=$(date -u -d '24 hours ago' +%Y-%m-%dT%H:%M:%SZ) fi curl -sH "User-Agent: $UA" \  "https://example.com/api/public/items?mode=selected&since=$since&take=50"

输出格式:JSON 数组,每项包含 {id, title, category, url, published_at}。下一步将输出传入 Step 2 进行过滤。

注意这几个细节:

  • 表格定义参数:Agent 不需要猜
  • 代码块可直接复制运行:不省略任何参数
  • 明确输出格式:下一步知道该怎么接
  • 兼容性处理:macOS 和 Linux 的 date 命令不同

3. 错误处理:专业和业余的分水岭

入门级 Skill 假设一切顺利。专业级 Skill 假设一定会出错。

下面是一段 pitfalls 章节的写法示例——每个坑都按"现象→原因→处理"三段式展开:

Pitfall 1:API 返回空结果

items 数组为空,但 HTTP 状态码是 200。原因:时间窗口内无数据,或 since 参数格式错误。

# 检查返回是否为空 response=$(curl -s "...") count=$(echo "$response" | python3 -c "import sys,json; print(len(json.load(sys.stdin)))") i…
— 以上为试看内容(约 40%),开通会员后阅读全文 —