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

模式 4：接力棒循环（跨 Session 持久化）¶

适用场景： 多次迭代的长期项目，需要跨多个 session 持续工作。 代表： google-labs-code/stitch-skills — stitch-loop（203 行） 结构：

## 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（编排方式）

模式 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 列表）

特殊模式：思维框架（控制 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（明确禁止做的事）

四、通用写作技巧¶

防止 LLM 偷懒的 4 种武器¶

教学的 3 种有效方式¶

安全与边界的 3 条原则¶

知识组织的 3 层架构¶

五、模式选择决策树¶

你的 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¶

### 循环迭代 Skill 模板
```yaml
---
name: my-loop-skill
description: [描述 + 触发时机]
---

## 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 目录 2. obra/superpowers — 14 个工作流型 Skill 3. google-labs-code/stitch-skills — 设计到代码的 Skill 4. deanpeters/Product-Manager-Skills — 40+ 产品管理 Skill 5. trailofbits/skills — 安全审计 Skill 6. openclaw/clawhub — Skill 注册中心 精选列表： 1. VoltAgent/awesome-agent-skills — 500+ Skill 索引 2. travisvn/awesome-claude-skills — 精选列表 + Skill vs MCP 对比

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

深度分析¶

1. Skill 本质是"上下文工程"而非"代码生成"¶

本文最核心的洞察是 Skill 的机制定位：Skill 不会动态生成新工具，而是通过 YAML frontmatter + Markdown 正文把指令文本注入 LLM 上下文。这意味着 Skill 设计本质上是上下文工程——如何把领域知识、执行流程、安全边界压缩成精炼的文本，让 LLM 在有限的上下文窗口内做出正确决策。

2. Description 的质量直接决定 Skill 的可用性¶

Description 是 LLM 判断是否加载 Skill 的唯一依据，这在架构上是一个巧妙的"触发器设计"。好的 Description 需要包含三重信息：（1）触发短语——用户可能说的话；（2）时序位置——在什么阶段使用；（3）产品关键词——覆盖范围的边界。这个设计体现了 Agent 系统中"意图识别"与"知识检索"的分离——Description 是索引，正文是内容。

3. 五种模式对应五种认知负荷分配策略¶

4. "防止 LLM 偷懒"是 Skill 设计的独特命题¶

传统系统设计假设执行者是可靠的、顺从的。Skill 设计需要面对一个新命题：LLM 会自我合理化、跳过步骤、降低标准。这要求 Skill 作者预判 LLM 的逃避路径，并通过以下机制应对：强硬语气提高遵从率；借口反驳表堵死合理化借口；量化阈值提供客观衡量标准；人类兜底处理边界情况。这个洞察来自安全审计领域（Trail of Bits），因为在安全场景下"偷懒"的后果最严重。

5. 渐进式披露是大型平台 Skill 的必选项¶

Cloudflare Skill 展示了"主文件 7KB + references/ 按需展开到几十万字"的架构。这种设计的核心洞察是：LLM 的上下文窗口是有限的，但领域知识的总量可能是无限的。通过 Frontmatter 的 description 字段做粗粒度过滤，通过主文件的决策树做中粒度导航，通过 references/ 子文档做细粒度展开，实现了知识组织的分层解耦。

6. 思维框架模式开启"元认知控制"的先河¶

Audit-context-building 模式最独特的地方在于它不是告诉 LLM"做什么"，而是控制 LLM"怎么想"：通过 Stability Rules（反幻觉规则）和 Non-Goals（明确禁止）来约束思维路径，通过量化阈值（每个函数最少 3 个不变量、5 个假设）来设定思维质量标准。这代表了 Skill 设计的一个新方向——从行为控制进化到元认知控制。

7. 知识组织三层架构的 Token 预算约束¶

文章提出的三层架构（Frontmatter ~100 tokens、主文件 2K-5K tokens、参考文档 1K-3K tokens）本质上是一个 Token 预算约束下的知识组织原则。这个约束来自 LLM 上下文窗口的物理限制，也来自"注入内容越多、embedding 衰减越严重"的经验规律。Skill 作者需要在这个预算下做出取舍：什么放主文件、什么放 references/、什么完全依赖 LLM 的内生知识。

实践启示¶

1. 设计新 Skill 前的第一步：选择模式¶

在动手写 Skill 之前，先用决策树判断适合的模式：

• 有明确步骤 → 线性流程
• 需要在选项中导航 → 决策树 + 按需加载
• 需要反复验证 → 循环迭代
• 跨 session 持久化 → 接力棒循环
• 多阶段人工介入 → 多阶段 + 检查点
• 需要深度思考 → 思维框架 错误地选择模式会导致 LLM 行为偏离预期，且难以通过优化 Description 修正。

2. Description 写作的"三重触发"检查清单¶

写完 Description 后，检查是否包含：

• 用户触发短语：把用户可能说的话原文复制进去（"deploy my app"）
• 时序触发：明确"在 X 之前/之后使用"或"当用户说 X 时使用"
• 产品触发：如果涉及平台，把所有相关产品名列出 缺少任何一个维度都会导致 Skill 的触发率下降。

3. 安全默认值是 Skill 设计的默认原则¶

每一个 Skill 都应该回答一个问题："如果 LLM 完全忽略我的指令，损失有多大？"如果大，就必须在 Description 或正文开头明确安全默认值。"Always deploy as preview, not production"是最简洁有力的示范——一句话把风险降到零。

4. 借口反驳表是防止质量退化的有效工具¶

在 Skill 中引入 Rationalizations 或 Common Pitfalls 部分，预判 LLM（和人类）的自我合理化路径：

• "这只是小改动，不需要完整测试"
• "这个错误可以忽略，逻辑上没问题"
• "临时方案，以后再改" 每一条借口都应该有对应的硬性反驳或量化阈值。

5. 主文件行数控制在 200 行以内为佳¶

根据 7 个顶级 Skill 的统计，主文件行数中位数为 224 行（cloudflare-deploy），最精简的是 77 行（vercel-deploy）。超过 300 行的主文件会显著增加 LLM 的阅读负担，建议通过 references/ 拆解。

6. 导航型 Skill 与操作型 Skill 应该分离¶

同一个平台（如 Cloudflare）应该拆成两个 Skill：

• 导航型（cloudflare）：只做选型，提供产品索引和决策树
• 操作型（cloudflare-deploy）：包含认证、命令、故障排除 这符合单一职责原则，也让 LLM 的调用更精准——需要选型时加载导航型，需要执行时加载操作型。

7. 跨 Skill 编排需要"检查点设计"¶

当一个 Skill 需要调用其他 Skill 时（如 discovery-process 调度 10+ 子 Skill），应该在每个子 Skill 调用前后设置检查点：

• Decision Point：Yes/No + 时间影响说明
• Outputs：当前阶段的明确产出物
• Activities：需要调用的子 Skill 列表 这样即使某个子 Skill 失败，也能定位问题并人工介入。

8. 与 agent-skill-writing-practices 的关系¶

本文聚焦于 Skill 的设计模式和写作技巧，而 更侧重于 Skill 在 Agent 系统中的实践应用，包括与 上下文管理 和 多 Agent 协作 的集成。两者结合可以构建完整的 Skill 开发知识体系。

9. 与 Anthropic 14 Skill Patterns Best Practices 的对比¶

是 Anthropic 官方发布的 14 个生产级 Skill 设计模式，强调可复用性和生产就绪。本文的 5 种核心设计模式更偏向分类框架，而 Anthropic 的 14 个模式更偏向具体场景模板。在实际开发中，建议先用本文的决策树定位模式，再用 Anthropic 的模板细化实现。

相关实体¶

• Agent Skills Comprehensive Survey
• Ai Skill Skill Creator 源码拆解
• Yidian Tianxia Context Engineering Agentic Ai
• Rag Chunking Vectorization Rerank Distillation
• Ai Skill Evolution底层逻辑
• MOC

→ 原文存档