Charles Wu for seekdb

Posted on Apr 29

How to Write Workflow Skills: Patterns and Best Practices Distilled from 7 Top Projects

#agents #ai #llm #tutorial

Five patterns distilled from Skills at OpenAI, Google Labs, obra, and more.

What Is a Skill?

A Skill is a folder centered around a SKILL.md file, using YAML frontmatter + Markdown body format. When an LLM determines a Skill is needed, it invokes the skill tool to load it. The entire content of SKILL.md is injected into the conversation context as a tool-result, and the LLM autonomously decides how to execute the instructions.

my-skill/
├── SKILL.md          # Main file (required)
├── scripts/          # Executable scripts (optional)
├── references/       # Detailed reference docs (optional, load on demand)
├── resources/        # Templates, checklists, etc. (optional)
└── examples/         # Examples (optional)

Key Mechanism: A Skill is essentially “knowledge injection” — it doesn’t dynamically generate new tools. Instead, it injects instruction text into the LLM’s context, and the LLM executes those instructions using existing tools (bash, read, edit, etc.).

Frontmatter: The “Facade” That Determines Whether a Skill Gets Loaded

Required Fields

How You Write description Determines Load Rate

# Good description — includes trigger phrases and keywords
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".

# Good description - defines temporal position
description: >
  Use when implementing any feature or bugfix, before writing
  implementation code

# Bad description - too vague
description: Helps with deployment stuff

Core Principles:

List trigger phrases: Write in the things users might actually say (“deploy my app”, “push this live”)
Define temporal position: Explain “before/after what” (e.g., “before writing implementation code”)
Include product keywords: If covering a large platform, list all product names

Optional Extended Fields

Extended fields observed across the 7 Skills:

Five Patterns (Author’s Synthesis)

Pattern 1: Linear Workflow

Applicable Scenario: Operations with clear steps like deployment, installation, or migration.

Representative: openai/skills — vercel-deploy1

Structure:

# Title
## Prerequisites
## Quick Start (Main flow: Step 1 → 2 → 3)
## Fallback
## Troubleshooting

Key Techniques:

Decision Rule: If your Skill can be described as “first do A, then do B, finally do C”, use the Linear pattern.

Pattern 2: Decision Tree + Load-on-Demand

Applicable Scenario: Large platform selection, product navigation, problem diagnosis.

Representative: openai/skills — cloudflare-deploy2

Structure:

# Title
## Authentication (auth prerequisite)
## Quick Decision Trees
### "I need to run code" (classified by user intent)
### "I need to store data"
### "I need AI/ML"
## Product Index

Key Techniques:

Decision Rule: If your Skill covers a knowledge domain with 10+ branches, each with extensive detailed documentation, use the Decision Tree pattern.

Advanced: The same knowledge domain can be split into two Skills:

Navigation type (cloudflare): Selection only, no operations
Operational type (cloudflare-deploy): Includes auth, commands, troubleshooting

Pattern 3: Loop Iteration

Applicable Scenario: TDD, code review, design review — processes requiring repeated execution.

Representative: obra/superpowers — test-driven-development3

Structure:

# Title
## The Iron Law (core principles that cannot be violated)
## Red-Green-Refactor (loop body)
### RED — Write a failing test
### Verify RED — Confirm it actually fails
### GREEN — Write minimal code
### Verify GREEN — Confirm it passes
### REFACTOR — Clean up
### Repeat (back to RED)
## Common Rationalizations
## Verification Checklist (exit conditions)

Key Techniques:

Decision Rule: If your Skill requires the LLM to repeatedly execute a “do → verify → improve” cycle, use the Iteration pattern.

Pattern 4: Baton Loop (Cross-Session Persistence)

Applicable Scenario: Long-term projects requiring multiple iterations across sessions.

Representative: google-labs-code/stitch-skills — stitch-loop4

Structure:

# Title
## Overview (baton mode overview)
## The Baton System (baton file specification)
## Execution Protocol (6-step execution protocol)
### 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 ⚠️ (Critical!)
## File Structure Reference
## Orchestration Options

Key Techniques:

Decision Rule: If your Skill needs to persist across multiple sessions or requires multiple Agents to collaborate, use the Baton Loop pattern.

Differences from Pattern 3:

Pattern 5: Multi-Phase + Checkpoints + Skill Orchestration

Applicable Scenario: Complex multi-week processes requiring Go/No-Go decisions at key milestones.

Representative: deanpeters/Product-Manager-Skills — discovery-process5

Structure:

# Title
## Key Concepts (+ anti-patterns)
## Phase 1: Frame the Problem
### Activities (which sub-Skills to invoke)
### Outputs (phase deliverables)
### Decision Point 1 (checkpoint: YES/NO + time impact)
## Phase 2-6... (repeated structure)
## Complete Workflow (end-to-end timeline)
## Common Pitfalls
## References (list of cited sub-Skills)

Key Techniques:

Decision Rule: If your Skill spans multiple days/weeks with clear phase divisions and Go/No-Go decision points, use the Multi-Phase pattern.

Special Pattern: Thinking Framework (Controlling “How the LLM Thinks”)

Applicable Scenario: Security audits, code review, architecture analysis — scenarios requiring deep thinking.

Representative: trailofbits/skills — audit-context-building6

Structure:

# Title
## Purpose (positioning: controls thinking mode, not behavior)
## When to Use / When NOT to Use
## Rationalizations
## Phase 1: Initial Orientation
## Phase 2: Ultra-Granular Function Analysis (core)
### Per-Function Checklist
### Cross-Function Flow Analysis
### Output Requirements (format + quantitative thresholds)
### Completeness Checklist
## Phase 3: Global System Understanding
## Stability Rules (anti-hallucination rules)
## Non-Goals (explicitly forbidden actions)

Key Techniques:

Decision Rule: If your Skill requires deep analysis rather than quick execution — controlling “thinking quality” rather than “operational steps” — use the Thinking Framework pattern.

Universal Writing Techniques

Four Tactics to Prevent LLM Laziness

Three Effective Teaching Methods

Three Principles for Safety and Boundaries

Three-Layer Knowledge Architecture

Layer 1: Frontmatter (~100 tokens) → LLM scans all Skills’ descriptions to decide whether to load
Layer 2: SKILL.md body (<5K tokens) → Core instructions, decision trees, process steps
Layer 3: references/ and resources/ (load on demand) → Detailed docs, examples, checklists; LLM reads via read tool as needed

Token Budget (Rule of Thumb):

Which Pattern Should You Use?

What does your Skill need to do?
│
├─ Execute an operation with clear steps
│ └─ → Pattern 1: Linear Workflow
│
├─ Help users choose the right direction among many options
│ └─ → Pattern 2: Decision Tree + Load-on-Demand
│
├─ Repeatedly execute "do → verify → improve" in a single session
│ └─ → Pattern 3: Loop Iteration
│
├─ Sustain a long-term project across multiple sessions
│ └─ → Pattern 4: Baton Loop
│
├─ Span multiple days/weeks with phase divisions and Go/No-Go decisions
│ └─ → Pattern 5: Multi-Phase + Checkpoints
│
└─ Require LLM to perform deep analysis rather than quick execution
  └─ → Special Pattern: Thinking Framework

Quick-Start Templates

Minimal Viable Skill (Linear Pattern)

---
name: my-skill
description: "[One-sentence description of what it does + when to trigger]"
---

# Skill Name

[One-sentence description of core principles + safe defaults]

## Prerequisites
- [Prerequisite 1]
- [Prerequisite 2]

## Steps

### Step 1: [Action]
[Specific command]

### Step 2: [Action]
[Specific instruction]

### Step 3: [Action]
[Specific instruction]

## Troubleshooting
| Issue | Solution |
|-------|----------|
| [Problem 1] | [Solution] |

Loop Iteration Skill Template

---
name: my-loop-skill
description: [Description of what it does + when to trigger]
---

# Skill Name

## Core Principle
[The iron law]

## The Loop

### Phase A - [Action]
[Specific instruction]

### Verify A
[Verification command]

### Phase B - [Action]
[Specific instruction]

### Verify B
[Verification command]

### Repeat
Back to Phase A.

## Rationalizations
| Excuse | Reality |
|--------|---------|
| "[Excuse 1]" | [Rebuttal] |

## Completion Checklist
- [ ] [Condition 1]
- [ ] [Condition 2]