工作流的 Skill 怎么写?从 7 个顶级 Skill 中提炼的模式与最佳实践

一、Skill 是什么

Skill 是一个文件夹,核心是 SKILL.md 文件,使用 YAML frontmatter + Markdown 正文 的格式。当 LLM 判断需要某个 Skill 时,会调用 skill 工具加载它,SKILL.md 的全部内容会作为 tool-result 注入到对话上下文中,LLM 读到后自主决定怎么执行。

my-skill/├── SKILL.md              # 主文件(必须)├── scripts/              # 可执行脚本(可选)├── references/           # 详细参考文档(可选,按需加载)├── resources/            # 模板、清单等资源(可选)└── examples/             # 示例(可选)

关键机制:Skill 本质是"知识注入"——它不会动态生成新工具,而是把指令文本注入到 LLM 的上下文中,LLM 用已有的工具(bash、read、edit 等)来执行这些指令。

二、Frontmatter:

决定 Skill 是否被加载的"门面"

2.1 必填字段

字段

作用

示例

name

唯一标识符,小写连字符

test-driven-development

description

最关键——LLM 通过它决定是否加载

见下方对比

2.2 Description 的写法决定加载率

# ✅ 好的 description — 包含触发短语和关键词description: Deploy applications and websites to Vercel. Use when the user   requests deployment actions like "deploy my app", "push this live",   or "create a preview deployment".
# ✅ 好的 description — 定义时序位置description: Use when implementing any feature or bugfix, before writing   implementation code
# ❌ 差的 description — 太模糊description: Helps with deployment stuff

核心原则:

  • 列举触发短语:把用户可能说的话写进去("deploy my app"、"push this live")

  • 定义时序位置:说明"在什么之前/之后"使用("before writing implementation code")

  • 包含产品关键词:如果覆盖大平台,把所有产品名列出来

2.3 可选扩展字段

从 7 个 Skill 中观察到的扩展字段:

字段

来源

作用

references

OpenCode cloudflare

声明最重要的参考文档

allowed-tools

Google Labs stitch-loop

声明需要的工具权限

type

Dean Peters discovery-process

声明 Skill 类型(workflow/component)

best_for

Dean Peters discovery-process

最适合的场景列表

scenarios

Dean Peters discovery-process

具体的触发场景示例

estimated_time

Dean Peters discovery-process

预估执行时间

三、5 种核心设计模式

模式 1:线性流程

适用场景:部署、安装、迁移等有明确步骤的操作。

代表:openai/skills — vercel-deploy(77 行)

结构:

# 标题## Prerequisites(前置条件)## Quick Start(主流程:Step 1 → 2 → 3)## Fallback(降级方案)## Troubleshooting(故障排除)

关键技巧:

技巧

示例

为什么有效

安全默认值

"Always deploy as preview, not production"

防止 LLM 做出危险操作

具体命令

每步给出可直接执行的 bash 命令

LLM 不需要猜测

超时提示

"Use a 10 minute (600000ms) timeout"

防止 LLM 因超时中断

降级方案

CLI 失败有 Fallback 脚本

提供 B 计划

负面指令

"Do not curl the deployed URL to verify"

明确禁止不该做的事

适用判断:如果你的 Skill 可以用"先做 A,再做 B,最后做 C"描述,就用线性模式。

模式 2:决策树 + 按需加载

适用场景:大型平台选型、产品导航、问题诊断。

代表:openai/skills — cloudflare-deploy(224 行)

结构:

# 标题## Authentication(认证前置)## Quick Decision Trees(决策树)  ### "I need to run code"(按用户意图分类)  ### "I need to store data"  ### "I need AI/ML"## Product Index(产品索引表)

关键技巧:

技巧

示例

为什么有效

用户意图分类

"I need to run code" 而非 "Compute products"

用用户语言而非技术术语

树形导航

├─ 边缘无服务器函数 → workers/

LLM 快速定位正确产品

渐进式披露

主文件 7KB,references/ 按需展开到几十万字

不浪费上下文窗口

产品索引表

Product → Reference 的映射表

结构化的快速查找

适用判断:如果你的 Skill 覆盖的知识域有 10+ 个分支,且每个分支都有大量详细文档,就用决策树模式。

进阶:同一个知识域可以拆成两个 Skill——

  • 导航型(cloudflare):只做选型,不涉及操作

  • 操作型(cloudflare-deploy):包含认证、命令、故障排除

模式 3:循环迭代

适用场景:TDD、代码审查、设计评审等需要反复执行的流程。

代表:obra/superpowers — test-driven-development(371 行)

结构:

# 标题## The Iron Law(铁律——不可违反的核心原则)## Red-Green-Refactor(循环体)  ### RED — 写失败的测试  ### Verify RED — 验证确实失败  ### GREEN — 写最少的代码  ### Verify GREEN — 验证确实通过  ### REFACTOR — 清理  ### Repeat(回到 RED)## Common Rationalizations(借口反驳表)## Verification Checklist(退出条件)

关键技巧:

技巧

示例

为什么有效

强硬语气

"Delete it. Start over."

LLM 倾向于"灵活变通",强硬语气提高遵从率

Good/Bad 对比

用 <Good> 和 <Bad> 标签包裹代码示例

对比教学效果最好

借口反驳表

预判 LLM 可能的 12 种偷懒借口并逐一反驳

堵死所有逃避路径

验证清单

8 项 checklist 作为循环退出条件

确保质量达标才能结束

人类兜底

"ask your human partner"

不确定时交给人

适用判断:如果你的 Skill 需要 LLM 反复执行"做→验证→改进"的循环,就用迭代模式。

模式 4:接力棒循环(跨 Session 持久化)

适用场景:多次迭代的长期项目,需要跨多个 session 持续工作。

代表:google-labs-code/stitch-skills — stitch-loop(203 行)

https://github.com/google-labs-code/stitch-skills/tree/main/skills/stitch-loop

结构:

# 标题## Overview(接力棒模式概述)## The Baton System(接力棒文件规范)## Execution Protocol(6 步执行协议)  ### Step 1: Read the Baton(读接力棒)  ### Step 2: Consult Context Files(查阅上下文)  ### Step 3: Gen…
— 以上为试看内容(约 40%),开通会员后阅读全文 —