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

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

# ✅ 好的 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

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

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

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

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

# 标题## 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 列表）

# 标题## 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（明确禁止做的事）

第 1 层：Frontmatter（~100 tokens）  → LLM 扫描所有 Skill 的 description，决定是否加载
第 2 层：SKILL.md 正文（<5K tokens）  → 核心指令、决策树、流程步骤
第 3 层：references/ 和 resources/（按需加载）  → 详细文档、示例、清单，LLM 用 read 工具按需读取

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

---name: my-skilldescription: [一句话描述做什么 + 什么时候触发]---
# Skill 名称
[一句话核心原则 + 安全默认值]
## Prerequisites- [前置条件 1]- [前置条件 2]
## Steps
### Step 1: [动作]\`\`\`bash[具体命令]\`\`\`
### Step 2: [动作][具体指令]
### Step 3: [动作][具体指令]
## Troubleshooting| Issue | Solution ||-------|----------|| [问题 1] | [解决方案] |

---name: my-loop-skilldescription: [描述 + 触发时机]---
# Skill 名称
## Core Principle[不可违反的铁律]
## The Loop
### Phase A — [动作][具体指令]
### Verify A[验证命令]
### Phase B — [动作][具体指令]
### Verify B[验证命令]
### Repeat回到 Phase A。
## Rationalizations| Excuse | Reality ||--------|---------|| "[借口 1]" | [反驳] |
## Completion Checklist- [ ] [条件 1]- [ ] [条件 2]