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-skill
description: [一句话描述做什么 + 什么时候触发]
---

# Skill 名称

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

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

## Steps

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

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

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

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

---
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]