工作流的 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 必填字段
字段 | 作用 | 示例 |
| 唯一标识符,小写连字符 |
|
| 最关键——LLM 通过它决定是否加载 | 见下方对比 |
2.2 Description 的写法决定加载率
# ✅ 好的 description — 包含触发短语和关键词description: Deploy applications and websites to Vercel. Use when the userrequests deployment actions like "deploy my app", "push this live",or "create a preview deployment".# ✅ 好的 description — 定义时序位置description: Use when implementing any feature or bugfix, before writingimplementation code# ❌ 差的 description — 太模糊description: Helps with deployment stuff
核心原则:
列举触发短语:把用户可能说的话写进去("deploy my app"、"push this live")
定义时序位置:说明"在什么之前/之后"使用("before writing implementation code")
包含产品关键词:如果覆盖大平台,把所有产品名列出来
2.3 可选扩展字段
从 7 个 Skill 中观察到的扩展字段:
字段 | 来源 | 作用 |
| OpenCode cloudflare | 声明最重要的参考文档 |
| Google Labs stitch-loop | 声明需要的工具权限 |
| Dean Peters discovery-process | 声明 Skill 类型(workflow/component) |
| Dean Peters discovery-process | 最适合的场景列表 |
| Dean Peters discovery-process | 具体的触发场景示例 |
| 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" | 用用户语言而非技术术语 |
树形导航 |
| 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 对比 | 用 | 对比教学效果最好 |
借口反驳表 | 预判 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…