Skip to main content
Teaches design patterns for building workflow-based Claude Code skills with multi-step phases, decision trees, subagent delegation, and progressive disclosure. Includes a review agent for auditing existing skills.

​
Overview

The Workflow Skill Design plugin provides comprehensive guidance for designing, structuring, and reviewing workflow-based Claude Code skills. It teaches five core patterns and includes a review agent for quality auditing. Author: Benjamin Samuels

​
Components

​
Skills

  • designing-workflow-skills - Guides the design and structuring of workflow-based skills with multi-step phases, decision trees, subagent delegation, and progressive disclosure

​
Agents

  • workflow-skill-reviewer - Reviews workflow-based skills for structural quality, pattern adherence, tool assignment correctness, and anti-pattern detection. Produces graded audit report.

​
Five Workflow Patterns

PatternUse WhenKey Feature
RoutingMultiple independent tasks from shared intakeRouting table maps intent to workflow files
Sequential PipelineDependent steps, each feeding the nextAuto-detection may resume from partial progress
Linear ProgressionSingle path, same every timeNumbered phases with entry/exit criteria
Safety GateDestructive/irreversible actionsTwo confirmation gates before execution
Task-DrivenComplex dependencies, partial failure toleranceTaskCreate/TaskUpdate with dependency tracking

​
When to Use

  • Designing a new skill with multi-step workflows or phased execution
  • Creating a skill that routes between multiple independent tasks
  • Building a skill with safety gates (destructive actions requiring confirmation)
  • Structuring a skill that uses subagents or task tracking
  • Reviewing or refactoring an existing workflow skill for quality
  • Deciding how to split content between SKILL.md, references/, and workflows/

​
Installation

/plugin install trailofbits/skills:workflow-skill-design

​
Essential Principles

​
1. Description is the Trigger

The description field is the ONLY thing that controls when a skill activates.
Claude decides whether to load a skill based solely on its frontmatter description. The body of SKILL.md (including “When to Use” and “When NOT to Use” sections) is only read AFTER the skill is already active. Put in description:
  • Trigger keywords
  • Use cases
  • Exclusions
“When to Use” and “When NOT to Use” still matter:
  • They scope Claude’s behavior once active
  • “When NOT to Use” should name specific alternatives: “use Semgrep for simple pattern matching” not “not for simple tasks”

​
2. Numbered Phases

Phases must be numbered with entry and exit criteria.
Unnumbered prose instructions produce unreliable execution order. Every phase needs:
  • A number (Phase 1, Phase 2, …)
  • Entry criteria (what must be true before starting)
  • Numbered actions (what to do)
  • Exit criteria (how to know it’s done)

​
3. Tools Match Executor

Skills use allowed-tools: in frontmatter Agents use tools: in frontmatter Never list tools the component doesn’t use. Never use Bash for operations that have dedicated tools (Glob, Grep, Read, Write, Edit).
Most skills and agents should include TodoRead and TodoWrite in their tool list - these enable progress tracking during multi-step execution.

​
4. Progressive Disclosure

SKILL.md stays under 500 lines. It contains only what Claude needs for every invocation:
  • Principles
  • Routing
  • Quick references
  • Links
Detailed patterns go in references/. Step-by-step processes go in workflows/. One level deep - no reference chains.

​
5. Scalable Tool Patterns

Instructions must produce tool-calling patterns that scale.
Every workflow instruction becomes tool calls at runtime. Apply the 10,000-file test:
  • Mentally run the workflow against a large repo
  • Check that tool call count stays bounded
Anti-patterns:
  • Searching N files for M patterns → N×M calls (bad)
  • One subagent per file → unbounded spawning (bad)
Better:
  • Combine into one regex, grep once, then filter (good)
  • Batch items into groups, one subagent per batch (good)

​
6. Degrees of Freedom

Match instruction specificity to task fragility:
Use for: Fragile operations (database migrations, crypto, destructive actions)Format: Exact commands, no variation
Run exactly this script:
```bash
python migrate.py --confirm

</Tab>

<Tab title="Medium Freedom">
**Use for:** Preferred patterns where variation is acceptable

**Format:** Pseudocode with parameters

```text
Use this template and customize as needed:
1. Read {baseDir}/config.json
2. Extract the 'api' section
3. Validate against schema

​
Pattern Selection

Choose the right pattern for your skill’s structure: 
How many distinct paths does the skill have?
│
+-- One path, always the same
│   +-- Does it perform destructive actions?
│       +-- YES -> Safety Gate Pattern
│       +-- NO  -> Linear Progression Pattern
│
+-- Multiple independent paths from shared setup
│   +-- Routing Pattern
│
+-- Multiple dependent steps in sequence
    +-- Do steps have complex dependencies?
        +-- YES -> Task-Driven Pattern
        +-- NO  -> Sequential Pipeline Pattern

​
Designing a New Skill

1

Define Scope and Goals

  • What problem does this skill solve?
  • What are the expected inputs?
  • What are the expected outputs?
  • When should this skill activate?
2

Choose Pattern

Use the pattern selection decision tree above.
3

Map Phases

Number all phases with:
  • Entry criteria
  • Numbered actions
  • Exit criteria
4

Assign Tools

  • List minimum tools needed
  • Use dedicated tools (Glob, Grep, Read) over Bash
  • Include TodoRead/TodoWrite for progress tracking
5

Split Content

  • SKILL.md: Principles, routing, quick refs (under 500 lines)
  • references/: Detailed patterns
  • workflows/: Step-by-step processes
6

Write Description

Put trigger keywords, use cases, and exclusions in frontmatter description.

​
Reviewing an Existing Skill

The workflow-skill-reviewer agent can audit any skill: 
Review the skill at plugins/my-plugin/skills/my-skill/ for quality issues.
The agent produces a graded audit report:
  • Structural quality - Phases numbered? Entry/exit criteria?
  • Pattern adherence - Matches a recognized pattern?
  • Tool assignment - Tools match executor? Minimum needed?
  • Anti-pattern detection - Hardcoded paths? Reference chains?

​
Anti-Pattern Quick Reference

The most common mistakes:
APAnti-PatternOne-Line Fix
AP-1Missing goals/anti-goalsAdd When to Use AND When NOT to Use sections
AP-2Monolithic SKILL.md (>500 lines)Split into references/ and workflows/
AP-3Reference chains (A → B → C)All files one hop from SKILL.md
AP-4Hardcoded pathsUse {baseDir} for all internal paths
AP-6Unnumbered phasesNumber every phase with entry/exit criteria
AP-7Missing exit criteriaDefine what “done” means for every phase
AP-11Wrong tool for the jobUse Glob/Grep/Read, not Bash equivalents
AP-12Overprivileged toolsRemove tools not actually used
AP-18Cartesian product tool callsCombine patterns into single regex, grep once
AP-19Unbounded subagent spawningBatch items into groups, one subagent per batch
AP-20Description summarizes workflowDescription = triggering conditions only

​
Structural Anatomy

Every workflow skill needs this skeleton: 
---
name: kebab-case-name
description: "Third-person description with trigger keywords"
allowed-tools:
  - [minimum tools needed]
# Optional fields:
# disable-model-invocation: true    # Only user can invoke
# user-invocable: false             # Only Claude can invoke
# context: fork                     # Run in isolated subagent
# agent: Explore                    # Subagent type
---

# Title

## Essential Principles
[3-5 non-negotiable rules with WHY explanations]

## When to Use
[4-6 specific scenarios]

## When NOT to Use
[3-5 scenarios with named alternatives]

## [Pattern-Specific Section]
[Routing table / Pipeline steps / Phase list / Gates]

## Quick Reference
[Compact tables for frequently-needed info]

## Reference Index
[Links to all supporting files]

## Success Criteria
[Checklist for output validation]

​
Tool Assignment Quick Reference

Component TypeTypical Tools
Read-only analysis skillRead, Glob, Grep, TodoRead, TodoWrite
Interactive analysis skillRead, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite
Code generation skillRead, Glob, Grep, Write, Bash, TodoRead, TodoWrite
Pipeline skillRead, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite
Read-only agentRead, Grep, Glob, TodoRead, TodoWrite
Action agentRead, Grep, Glob, Write, Bash, TodoRead, TodoWrite
Key rules:
  • Use Glob (not find), Grep (not grep), Read (not cat)
  • Skills use allowed-tools: — agents use tools:
  • List only tools that instructions actually reference
  • Read-only components should never have Write or Bash

​
Reference Documentation

The skill includes detailed reference files:
  • workflow-patterns.md - 5 patterns with structural skeletons and examples
  • anti-patterns.md - 20 anti-patterns with before/after fixes
  • tool-assignment-guide.md - Tool selection matrix, component comparison, subagent guidance
  • progressive-disclosure-guide.md - Content splitting rules, the 500-line rule, sizing guidelines
Workflows:
  • design-a-workflow-skill.md - 6-phase creation process from scope to self-review
  • review-checklist.md - Structured self-review checklist for submission readiness

​
Success Criteria

A well-designed workflow skill:

​
Rationalizations to Reject

When designing workflow skills, reject these shortcuts:
RationalizationWhy It’s Wrong
”It’s obvious which phase comes next”LLMs don’t infer ordering from prose. Number the phases.
”Exit criteria are implied”Implied criteria are skipped criteria. Write them explicitly.
”One big SKILL.md is simpler”Simpler to write, worse to execute. Claude loses focus past 500 lines.
”The description doesn’t matter much”The description is how the skill gets triggered. Bad description = wrong/missed activations.
”Bash can do everything”Bash file operations are fragile. Dedicated tools handle encoding/permissions better.
”The LLM will figure out the tools”It will guess wrong. Specify exactly which tool for each operation.
  • Skill Improver - Uses workflow patterns for iterative refinement
  • Git Cleanup - Example of Safety Gate pattern
  • Devcontainer Setup - Example of Linear Progression pattern
  • Ask Questions If Underspecified - Example of minimal gated workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us