How Do You Write a Workflow Skill? Patterns and Best Practices Distilled from 7 Top-Tier Projects

Posted on In Views: Word count in article: 1.1k Reading time ≈ 4 mins.
This article analyzes line by line 7 production-grade Skills from teams such as OpenAI, Google Labs, obra, and Trail of Bits, distilling 5 workflow Skill design patterns—linear process, decision tree, iterative loop, baton loop, and multi-phase checkpoints—along with general writing techniques for keeping the LLM from slacking off.

Prologue

The article shared today drew a far hotter response than expected on ATA, the internal tech-sharing platform at Alibaba and Ant Group. It shows that when people try to turn their own complex workflows/SOPs into Skills at work, they often hit a wall—not knowing how to write them, and then finding the finished Skill doesn’t behave as expected.

Screenshot of the workflow Skill article's popularity on the ATA platform

In this article, the expert Qing Fu analyzes 7 of the most top-tier Skill cases and, based on that analysis, summarizes 5 design patterns for workflow Skills. With the author Qing Fu’s permission, we’re sharing the article here.

This article is based on a line-by-line analysis of 7 production-grade Skills from teams including OpenAI, Google Labs, obra, Trail of Bits, and Dean Peters, distilling five reusable Skill design patterns, writing techniques, and cautionary lessons.

1. What Is a Skill

A Skill is a folder whose core is the SKILL.md file, written in the format of YAML frontmatter + Markdown body. When the LLM judges that a particular Skill is needed, it calls the skill tool to load it.

The key mechanism: a Skill is essentially “knowledge injection”—it doesn’t dynamically generate new tools; it injects instruction text into the LLM’s context, and the LLM uses the tools it already has (bash, read, edit, etc.) to carry out those instructions.

Skill file structure

2. Frontmatter: The “Facade” That Decides Whether a Skill Gets Loaded

Field Role Example
name Unique identifier, lowercase hyphenated test-driven-development
description The most critical—the LLM uses it to decide whether to load See comparison below

Core principles: list trigger phrases, define temporal positioning, and include product keywords.

3. Five Core Design Patterns

Five core design patterns

Pattern 1: Linear Process

When to use: operations with clear steps, such as deployment, installation, and migration. Representative: openai/skills — vercel-deploy (77 lines).

Structure: Prerequisites → Quick Start → Fallback → Troubleshooting.

Linear process pattern

Key techniques: safe defaults, concrete commands, timeout hints, fallback plans, negative instructions.

Pattern 2: Decision Tree + On-Demand Loading

When to use: selecting from large platforms, product navigation, problem diagnosis. Representative: openai/skills — cloudflare-deploy (224 lines).

Structure: Authentication → Quick Decision Trees (classified by user intent) → Product Index.

Decision tree pattern

Key techniques: user-intent classification (use the user’s language rather than technical jargon), tree navigation, progressive disclosure (main file 7KB, references/ expanded on demand).

Pattern 3: Iterative Loop

When to use: TDD, code review, design review, and other processes that need to run repeatedly. Representative: obra/superpowers — test-driven-development (371 lines).

Structure: Iron Law → Red-Green-Refactor (the loop body) → Common Rationalizations (a rebuttal table) → Verification Checklist.

Iterative loop pattern

Key techniques: a firm tone, Good/Bad comparisons, a rationalization-rebuttal table (anticipating 12 excuses the LLM might use to slack off), a verification checklist, and human fallback.

Pattern 4: Baton Loop (Cross-Session Persistence)

When to use: long-running projects with many iterations. Representative: google-labs-code/stitch-skills — stitch-loop (203 lines).

A six-step execution protocol: Read the Baton → Consult Context → Generate → Integrate → Update Documentation → Prepare the Next Baton (the crucial step!).

Baton loop pattern

The key: the file is the state (next-prompt.md serves as the baton), so the LLM doesn’t need to remember “where I left off last time.”

Pattern 5: Multi-Phase + Checkpoints + Skill Orchestration

When to use: complex multi-week processes that need Go/No-Go decisions at key junctions. Representative: deanpeters/discovery-process (502 lines).

Structure: Phase Activities → Outputs → Decision Point (YES/NO + time impact).

Multi-phase checkpoint pattern

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

When to use: scenarios requiring deep thought, such as security audits and code review. Representative: trailofbits/skills — audit-context-building (302 lines).

Key techniques: thinking tools (first principles, 5 Whys, 5 Hows), quantified thresholds (“at least 3 invariants per function”), and anti-hallucination rules.

4. General Writing Techniques

Four Weapons to Keep the LLM from Slacking Off

Four weapons to keep the LLM from slacking off

Weapon Principle
Firm tone LLMs comply more readily with imperative phrasing
Rationalization-rebuttal table Anticipate the LLM’s self-justification paths and block them off
Quantified thresholds Give hard minimum standards
Negative instructions Explicitly say “don’t do X”

A Three-Layer Architecture for Organizing Knowledge

Three-layer architecture for organizing knowledge

  • Layer 1: Frontmatter (~100 tokens) → the LLM scans the description of every Skill
  • Layer 2: SKILL.md body (<5K tokens) → core instructions
  • Layer 3: references/ and resources/ (loaded on demand) → detailed documentation

5. A Decision Tree for Choosing a Pattern

Decision tree for choosing a pattern

1
2
3
4
5
6
7
What does your Skill need to do?
├─ Perform an operation with clear steps → Pattern 1: Linear Process
├─ Help the user choose among many options → Pattern 2: Decision Tree + On-Demand Loading
├─ Repeatedly run "do → verify → improve" within a single session → Pattern 3: Iterative Loop
├─ Advance a long-running project across multiple sessions → Pattern 4: Baton Loop
├─ Span multiple days/weeks with Go/No-Go decisions → Pattern 5: Multi-Phase + Checkpoints
└─ Need the LLM to analyze deeply → Special Pattern: Thinking Framework

6. Quick-Reference Table for the 7 Skills Analyzed in This Article

# Skill Source Pattern Lines Essence in One Sentence
1 vercel-deploy OpenAI Linear 77 The minimal yet complete Skill template
2 cloudflare-deploy OpenAI Linear + Decision Tree 224 Progressive disclosure for a large platform
3 cloudflare OpenCode Pure Decision Tree 211 Navigational vs. operational
4 test-driven-development obra Iterative Loop 371 Block off every escape route for a slacking LLM
5 stitch-loop Google Labs Baton Loop 203 The file is the state, across sessions
6 discovery-process Dean Peters Multi-Phase + Checkpoints 502 The orchestrator pattern
7 audit-context-building Trail of Bits Thinking Framework 302 Control “how” the LLM thinks

Reference links:
[1] openai/skills vercel-deploy: https://github.com/openai/skills/tree/main/skills/.curated/vercel-deploy
[2] openai/skills cloudflare-deploy: https://github.com/openai/skills/tree/main/skills/.curated/cloudflare-deploy
[3] obra/superpowers TDD: https://github.com/obra/superpowers/tree/main/skills/test-driven-development
[4] google-labs stitch-loop: https://github.com/google-labs-code/stitch-skills/tree/main/skills/stitch-loop
[5] deanpeters discovery-process: https://github.com/deanpeters/Product-Manager-Skills
[6] trailofbits audit: https://github.com/trailofbits/skills
[7] Agent Skills open standard: https://agentskills.io/
[8] anthropics/skills: https://github.com/anthropics/skills