一、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 必填字段

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 中观察到的扩展字段：

三、5 种核心设计模式

模式 1：线性流程

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

代表：openai/skills — vercel-deploy（77 行）

结构：

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

关键技巧：

适用判断：如果你的 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（产品索引表）

关键技巧：

适用判断：如果你的 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（退出条件）

关键技巧：

适用判断：如果你的 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: Generate（执行任务）
  ### Step 4: Integrate（集成结果）
  ### Step 5: Update Documentation（更新文档）
  ### Step 6: Prepare the Next Baton ⚠️（写下一个接力棒——关键！）
## File Structure Reference（文件协议）
## Orchestration Options（编排方式）

关键技巧：

适用判断：如果你的 Skill 需要跨多个 session 持续工作，或者需要多个 Agent 协作，就用接力棒模式。

与模式 3 的区别：

模式 5：多阶段 + 检查点 + Skill 编排

适用场景：复杂的多周流程，需要在关键节点做 Go/No-Go 决策。

代表：
deanpeters/Product-Manager-Skills — discovery-process（502 行）

结构：

# 标题
## Key Concepts（核心概念 + 反模式）
## Phase 1: Frame the Problem（阶段 1）
  ### Activities（调用哪些子 Skill）
  ### Outputs（阶段产出）
  ### Decision Point 1（检查点：YES/NO + 时间影响）
## Phase 2-6...（重复相同结构）
## Complete Workflow（端到端时间线）
## Common Pitfalls（常见陷阱）
## References（引用的子 Skill 列表）

关键技巧：

适用判断：如果你的 Skill 跨越多天/多周，有明确的阶段划分和 Go/No-Go 决策点，就用多阶段模式。

特殊模式：思维框架（控制 LLM "怎么想"）

适用场景：安全审计、代码审查、架构分析等需要深度思考的场景。

代表：trailofbits/skills — audit-context-building（302 行）

结构：

# 标题
## Purpose（定位：控制思维方式，不是控制行为）
## When to Use / When NOT to Use
## Rationalizations（借口反驳表）
## Phase 1: Initial Orientation（定向扫描）
## Phase 2: Ultra-Granular Function Analysis（逐行分析——核心）
  ### Per-Function Checklist（函数微分析清单）
  ### Cross-Function Flow Analysis（跨函数追踪）
  ### Output Requirements（输出格式 + 量化阈值）
  ### Completeness Checklist（完整性检查）
## Phase 3: Global System Understanding（全局理解）
## Stability Rules（反幻觉规则）
## Non-Goals（明确禁止做的事）

关键技巧：

适用判断：如果你的 Skill 需要 LLM 进行深度分析而非快速执行，需要控制的是"思维质量"而非"操作步骤"，就用思维框架模式。

四、通用写作技巧

4.1 防止 LLM 偷懒的 4 种武器

4.2 教学的 3 种有效方式

4.3 安全与边界的 3 条原则

4.4 知识组织的 3 层架构

第 1 层：Frontmatter（~100 tokens）
  → LLM 扫描所有 Skill 的 description，决定是否加载


第 2 层：SKILL.md 正文（<5K tokens）
  → 核心指令、决策树、流程步骤


第 3 层：references/ 和 resources/（按需加载）
  → 详细文档、示例、清单，LLM 用 read 工具按需读取

Token 预算参考：

五、模式选择决策树

你的 Skill 需要做什么？
│
├─ 执行一个有明确步骤的操作
│  └─ → 模式 1：线性流程
│
├─ 在大量选项中帮用户选择正确的方向
│  └─ → 模式 2：决策树 + 按需加载
│
├─ 在单次会话中反复执行"做→验证→改进"
│  └─ → 模式 3：循环迭代
│
├─ 跨多个 session 持续推进一个长期项目
│  └─ → 模式 4：接力棒循环
│
├─ 跨越多天/多周，有阶段划分和 Go/No-Go 决策
│  └─ → 模式 5：多阶段 + 检查点
│
└─ 需要 LLM 进行深度分析而非快速执行
   └─ → 特殊模式：思维框架

六、快速上手模板

最小可用 Skill（线性模式）

---
name: my-skill
description: [一句话描述做什么 + 什么时候触发]
---


# Skill 名称


[一句话核心原则 + 安全默认值]


## Prerequisites
- [前置条件 1]
- [前置条件 2]


## Steps


### Step 1: [动作]
\`\`\`bash
[具体命令]
\`\`\`


### Step 2: [动作]
[具体指令]


### Step 3: [动作]
[具体指令]


## Troubleshooting
| Issue | Solution |
|-------|----------|
| [问题 1] | [解决方案] |

循环迭代 Skill 模板

---
name: my-loop-skill
description: [描述 + 触发时机]
---


# Skill 名称


## Core Principle
[不可违反的铁律]


## The Loop


### Phase A — [动作]
[具体指令]


### Verify A
[验证命令]


### Phase B — [动作]
[具体指令]


### Verify B
[验证命令]


### Repeat
回到 Phase A。


## Rationalizations
| Excuse | Reality |
|--------|---------|
| "[借口 1]" | [反驳] |


## Completion Checklist
- [ ] [条件 1]
- [ ] [条件 2]

七、参考资源

官方规范

1. Agent Skills 开放标准

https://agentskills.io/

2. anthropics/skills — 官方模板

https://github.com/anthropics/skills/tree/main/template

3. anthropics/skills — 规范文档

https://github.com/anthropics/skills/tree/main/spec

精选仓库

1. openai/skills — OpenAI Codex 官方 Skill 目录

https://github.com/openai/skills

2. obra/superpowers — 14 个工作流型 Skill

https://github.com/obra/superpowers

3.
google-labs-code/stitch-skills — 设计到代码的 Skill

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

4.
deanpeters/Product-Manager-Skills — 40+ 产品管理 Skill

https://github.com/deanpeters/Product-Manager-Skills

5. trailofbits/skills — 安全审计 Skill

https://github.com/trailofbits/skills

6. openclaw/clawhub — Skill 注册中心

https://github.com/openclaw/clawhub

精选列表

1.
VoltAgent/awesome-agent-skills — 500+ Skill 索引

https://github.com/VoltAgent/awesome-agent-skills

2.
travisvn/awesome-claude-skills — 精选列表 + Skill vs MCP 对比

https://github.com/travisvn/awesome-claude-skills

八、本文分析的 7 个 Skill 速查表