LLM 工作流 Skill 编写指南：结构、触发机制与 6 种设计模式

my-skill/
├── SKILL.md              # 必需：Skill 主文件
├── scripts/              # 可选：可执行脚本
├── references/           # 可选：详细参考资料，按需读取
├── resources/            # 可选：模板、清单、配置样例
└── examples/             # 可选：输入输出示例

---
name: test-driven-development
description: Use when implementing any feature or bugfix, before writing implementation code.
---

---
name: vercel-deploy
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".
---

---
name: deploy-helper
description: Helps with deployment stuff.
---

---
name: product-discovery-process
description: Use to guide a multi-stage product discovery workflow with research, synthesis, decision checkpoints, and handoff artifacts.
type: workflow
best_for:
  - new product exploration
  - validating ambiguous product ideas
  - multi-week discovery projects
estimated_time: 2-6 weeks
---

# Vercel Deployment

## Prerequisites

- Confirm the project has a valid package manager configuration.
- Confirm the user wants a preview deployment unless production is explicitly requested.

## Quick Start

### Step 1: Install CLI

```bash
npm install -g vercel

vercel link

vercel --yes

线性流程 Skill 的重点不是“把步骤列出来”这么简单，而是要减少模型猜测空间。

| 技巧 | 写法 | 作用 |
|---|---|---|
| 安全默认值 | 默认 preview，不默认 production | 避免模型执行高风险操作 |
| 具体命令 | 每一步都给出可复制命令 | 模型不需要自己拼命令 |
| 超时设置 | 明确 `600000ms` 之类的时间 | 避免长任务被过早中断 |
| 降级方案 | CLI 失败时改用脚本或手动步骤 | 不让流程卡死 |
| 负面指令 | `Do not curl the deployed URL to verify` | 明确禁止无意义或危险操作 |

线性流程适合短小 Skill。一个优秀的部署 Skill 可以只有几十行，但必须覆盖成功路径、失败路径和安全边界。

### 模式 2：决策树 + 按需加载

当 Skill 面对的是一个大平台或复杂知识域，线性步骤就不够了。比如 Cloudflare 这类平台有 Workers、Pages、R2、D1、KV、Queues、AI Gateway 等多个产品，用户往往不会直接说产品名，而是说“我想跑一段后端代码”“我需要存文件”“我需要做边缘缓存”。

这类 Skill 应该先帮助模型识别用户意图，再导航到正确产品。

```mermaid
flowchart TD
    A[用户需求] --> B{用户想做什么}
    B --> C[运行代码]
    B --> D[存储数据]
    B --> E[处理 AI/ML]
    B --> F[部署网站]

    C --> C1[边缘函数: Workers]
    C --> C2[容器或长期任务: Containers / Workflows]

    D --> D1[对象文件: R2]
    D --> D2[关系型数据: D1]
    D --> D3[键值数据: KV]

    E --> E1[模型调用网关: AI Gateway]
    E --> E2[边缘推理: Workers AI]

    F --> F1[静态站点: Pages]
    F --> F2[全栈应用: Pages + Functions]

# Cloud Platform Navigator

## Authentication

Explain how to check login status and required credentials.

## Quick Decision Trees

### "I need to run code"

- Edge request handling → Workers
- Long-running workflows → Workflows
- Containerized services → Containers

### "I need to store data"

- Object storage → R2
- Relational database → D1
- Key-value access → KV

## Product Index

| Product | Use when | Reference |
|---|---|---|
| Workers | Edge compute | references/workers.md |
| R2 | Object storage | references/r2.md |
| D1 | SQL database | references/d1.md |

# Test-Driven Development

## The Iron Law

Never write implementation code before there is a failing test.

## Red-Green-Refactor

### RED — Write a failing test

Create the smallest test that captures the desired behavior.

### Verify RED

Run the test and confirm it fails for the expected reason.

### GREEN — Write minimal code

Implement only enough code to pass the test.

### Verify GREEN

Run the test suite and confirm the new test passes.

### REFACTOR

Clean up duplication and naming without changing behavior.

## Common Rationalizations

| Excuse | Reality |
|---|---|
| "This is too simple to test" | Simple code still needs executable behavior documentation |
| "I'll add tests after implementation" | That is not TDD |

## Completion Checklist

- [ ] Every behavior change started with a failing test
- [ ] The failing test failed for the expected reason
- [ ] All tests pass
- [ ] Refactoring did not change behavior

project/
├── roadmap.md             # 总路线图
├── context.md             # 项目上下文
├── decisions.md           # 已做决策
├── outputs/               # 每轮产物
└── next-prompt.md         # 下一轮接力棒

# Stitch Loop

## Overview

This workflow uses files as persistent state between sessions.

## The Baton System

The baton file is `next-prompt.md`. It must contain:
- current objective
- relevant context files
- completed work
- next concrete action
- stopping condition

## Execution Protocol

### Step 1: Read the Baton

Read `next-prompt.md` before doing any work.

### Step 2: Consult Context Files

Read the referenced files only when needed.

### Step 3: Generate

Complete the current unit of work.

### Step 4: Integrate

Write outputs into the expected project files.

### Step 5: Update Documentation

Record decisions and remaining tasks.

### Step 6: Prepare the Next Baton

This step is mandatory. Create or update `next-prompt.md` so another session can continue.

## Phase 1: Frame the Problem

### Activities

- Run stakeholder interview
- Collect existing assumptions
- Define decision constraints

### Outputs

- Problem statement
- Known assumptions
- Open questions

### Decision Point 1

Question: Is the problem specific enough?

- YES → Move to Phase 2
- NO → Spend 2-3 more days refining the problem

## Phase 2: User Research

### Activities

Use these skills:
- `interview-planning`
- `research-synthesis`
- `persona-mapping`

### Outputs

- Interview guide
- Research notes
- Pattern summary
- Evidence table

# Audit Context Building

## Purpose

Build deep understanding before identifying vulnerabilities or proposing fixes.

## When to Use

Use for security review, complex codebase orientation, and high-risk reasoning tasks.

## When NOT to Use

Do not use for quick syntax fixes or simple refactors.

## Phase 1: Initial Orientation

Map the repository structure, entry points, data flows, and trust boundaries.

## Phase 2: Ultra-Granular Function Analysis

For each important function, identify:
- invariants
- assumptions
- inputs
- outputs
- side effects
- failure modes

## Phase 3: Global System Understanding

Connect function-level behavior into system-level flows.

## Stability Rules

Never reshape evidence to match an earlier assumption.

## Non-Goals

Do not report vulnerabilities before context building is complete.
Do not propose fixes during the analysis phase.

## Output Format

Return the analysis using this structure:

### Summary

One paragraph explaining the key behavior.

### Evidence

| Claim | Evidence | File |
|---|---|---|

### Open Questions

- Question 1
- Question 2

<Bad>
Write all implementation code first, then add a broad test later.
</Bad>

<Good>
Write one failing test for the smallest behavior, confirm it fails, then implement only enough code to pass.
</Good>

## Safety Defaults

- Always create a preview deployment unless the user explicitly asks for production.
- Never delete remote resources without confirmation.
- Do not expose secrets in logs.
- If credentials are missing, ask the user instead of inventing values.

cloudflare-skill/
├── SKILL.md
└── references/
    ├── workers.md
    ├── pages.md
    ├── r2.md
    ├── d1.md
    └── troubleshooting.md

## Product References

| Product | Use when | File |
|---|---|---|
| Workers | Running code at the edge | references/workers.md |
| Pages | Deploying static or full-stack web apps | references/pages.md |
| R2 | Storing objects and files | references/r2.md |
| D1 | Using SQL at the edge | references/d1.md |

---
name: my-linear-skill
description: Use when the user wants to [完成某类任务]. Trigger for phrases like "[用户可能说法 1]", "[用户可能说法 2]". Default to the safest option unless the user explicitly requests otherwise.
---

# My Linear Skill

## Core Rule

State the non-negotiable rule here. For example: always run in preview mode before production.

## Prerequisites

- Confirm [前置条件 1].
- Confirm [前置条件 2].
- If [缺少必要信息], ask the user before continuing.

## Steps

### Step 1: [动作名称]

```bash
[可直接执行的命令]

[可直接执行的命令]

### 循环迭代 Skill 模板

```markdown
---
name: my-loop-skill
description: Use when the user needs an iterative workflow for [任务类型]. Use before [关键时机], and continue until the completion checklist is satisfied.
---

# My Loop Skill

## Core Principle

[不可违反的核心原则。]

## The Loop

### Phase A — [动作]

[具体指令。]

### Verify A

```bash
[验证命令]

[验证命令]

### 接力棒 Skill 模板

```markdown
---
name: my-baton-skill
description: Use for long-running work that must continue across sessions or agents. Use when the user asks to continue a project, resume work, or coordinate multiple iterations over time.
---

# My Baton Skill

## Core Rule

The baton file is the source of truth. Always read it before work and always update it before stopping.

## File Protocol

| File | Purpose |
|---|---|
| `next-prompt.md` | Current baton and next action |
| `context.md` | Stable project context |
| `roadmap.md` | Remaining work |
| `decisions.md` | Decisions already made |
| `outputs/` | Generated artifacts |

## Execution Protocol

### Step 1: Read the Baton

Read `next-prompt.md`.

### Step 2: Read Context

Read only the context files referenced by the baton.

### Step 3: Execute

Complete the current unit of work.

### Step 4: Integrate

Write outputs to the expected files.

### Step 5: Update Documentation

Update `roadmap.md` and `decisions.md`.

### Step 6: Prepare the Next Baton

This step is mandatory. Update `next-prompt.md` with:
- current state
- completed work
- next task
- required context files
- stopping condition