Guides the design and structuring of workflow-based Claude Code skills with multi-step phases, decision trees, subagent delegation, and progressive disclosure. Use when creating skills that involve sequential pipelines, routing patterns, safety gates, task tracking, phased
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/designing-workflow-skills
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Guides the design and structuring of workflow-based Claude Code skills with multi-step phases, decision trees, subagent delegation, and progressive disclosure. Use when creating skills that involve sequential pipelines, routing patterns, safety gates, task tracking, phased
📊 Stats
Stars6,227
Forks540
LanguagePython
LicenseCC-BY-SA-4.0
📦 Ships with trailofbits-skills
</> SKILL.md
designing-workflow-skills.SKILL.md
---name: designing-workflow-skills
description: >-
Guides the design and structuring of workflow-based Claude Code skills
with multi-step phases, decision trees, subagent delegation, and
progressive disclosure. Use when creating skills that involve
sequential pipelines, routing patterns, safety gates, task tracking,
phased execution, or any multi-step workflow. Also applies when
reviewing or refactoring existing workflow skills for quality.
allowed-tools: Read Glob Grep TodoRead TodoWrite
---# Designing Workflow Skills
Build workflow-based skills that execute reliably by following structural patterns, not prose.
## Essential Principles
<essential_principles>
<principle name="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 your trigger keywords, use cases, and exclusions in the description. A bad description means wrong activations or missed activations regardless of what the body says.
"When to Use" and "When NOT to Use" sections still serve a purpose: they scope the LLM's behavior once active. "When NOT to Use" should name specific alternatives: "use Semgrep for simple pattern matching" not "not for simple tasks."
**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)
</principle>
<principle name="tools-match-executor">
**Tools must match the executor.**
Skills use `allowed-tools:` in frontmatter. Agents use `tools:` in frontmatter. Subagents get tools from their `subagent_type`. 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 and are useful even for skills that don't explicitly manage tasks.
</principle>
<principle name="progressive-disclosure">
**Progressive disclosure is structural, not optional.**
SKILL.md stays under 500 lines. It contains only what the LLM needs for every invocation: principles, routing, quick references, and links. Detailed patterns go in `references/`. Step-by-step processes go in `workflows/`. One level deep — no reference chains.
</principle>
<principle name="scalable-tool-patterns">
**Instructions must produce tool-calling patterns that scale.**
Every workflow instruction becomes tool calls at runtime. If a workflow searches N files for M patterns, combine into one regex — not N×M calls. If a workflow spawns subagents per item, use batching — not one subagent per file. Apply the 10,000-file test: mentally run the workflow against a large repo and check that tool call count stays bounded. See [anti-patterns.md](references/anti-patterns.md) AP-18 and AP-19.
</principle>
<principle name="degrees-of-freedom">
**Match instruction specificity to task fragility.**
Not every step needs the same level of prescription. Calibrate per step:
- **Low freedom** (exact commands, no variation): Fragile operations — database migrations, crypto, destructive actions. "Run exactly this script."
- **Medium freedom** (pseudocode with parameters): Preferred patterns where variation is acceptable. "Use this template and customize as needed."
- **High freedom** (heuristics and judgment): Variable tasks — code review, exploration, documentation. "Analyze the structure and suggest improvements."
A skill can mix freedom levels. A security audit skill might use high freedom for the discovery phase ("explore the codebase for auth patterns") and low freedom for the reporting phase ("use exactly this severity classification table").
</principle>
</essential_principles>
## 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/
## When NOT to Use
- Simple single-purpose skills with no workflow (just guidance) — write the SKILL.md directly
- Writing the actual domain content of a skill (this teaches structure, not domain expertise)
- Plugin configuration (plugin.json, hooks, commands) — use plugin development guides
- Non-skill Claude Code development — this is specifically for skill architecture
## Pattern Selection
Choose the right pattern for your skill's structure. Read the full pattern description in [workflow-patterns.md](references/workflow-patterns.md).
```
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
```
### Pattern Summary
| Pattern | Use When | Key Feature |
|---------|----------|-------------|
| **Routing** | Multiple independent tasks from shared intake | Routing table maps intent to workflow files |
| **Sequential Pipeline** | Dependent steps, each feeding the next | Auto-detection may resume from partial progress |
| **Linear Progression** | Single path, same every time | Numbered phases with entry/exit criteria |
| **Safety Gate** | Destructive/irreversible actions | Two confirmation gates before execution |
Every workflow skill needs this skeleton, regardless of pattern:
```markdown
---
name: kebab-case-name
description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
allowed-tools: Tool1 Tool2 Tool3 # space-delimited list of tool names
# Optional fields — see tool-assignment-guide.md for full reference:
# disable-model-invocation: true # Only user can invoke (not Claude)
# user-invocable: false # Only Claude can invoke (hidden from / menu)
# context: fork # Run in isolated subagent context
# agent: Explore # Subagent type (requires context: fork)
# model: [model-name] # Switch model when skill is active
# argument-hint: "[filename]" # Hint shown during autocomplete
---
# Title
## Essential Principles
[3-5 non-negotiable rules with WHY explanations]
## When to Use
[4-6 specific scenarios — scopes behavior after activation]
## When NOT to Use
[3-5 scenarios with named alternatives — scopes behavior after activation]
## [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]
```
Skills support three types of string substitutions: dollar-prefixed variables for arguments and session ID, and exclamation-backtick syntax for shell preprocessing. The skill loader processes these before Claude sees the file — even inside code fences — so never use the raw syntax in documentation text. See [tool-assignment-guide.md](references/tool-assignment-guide.md) for the full variable reference and usage guidance.
## Anti-Pattern Quick Reference
The most common mistakes. Full catalog with before/after fixes in [anti-patterns.md](references/anti-patterns.md).
| AP | Anti-Pattern | One-Line Fix |
|----|-------------|-------------|
| AP-1 | Missing goals/anti-goals | Add When to Use AND When NOT to Use sections |
| AP-2 | Monolithic SKILL.md (>500 lines) | Split into references/ and workflows/ |
| AP-3 | Reference chains (A -> B -> C) | All files one hop from SKILL.md |
| AP-4 | Hardcoded paths | Use `{baseDir}` for all internal paths |
| AP-5 | Broken file references | Verify every path resolves before submitting |
| AP-6 | Unnumbered phases | Number every phase with entry/exit criteria |
| AP-7 | Missing exit criteria | Define what "done" means for every phase |
| AP-8 | No verification step | Add validation at the end of every workflow |
| AP-9 | Vague routing keywords | Use distinctive keywords per workflow route |
| AP-11 | Wrong tool for the job | Use Glob/Grep/Read, not Bash equivalents |
| AP-12 | Overprivileged tools | Remove tools not actually used |
| AP-13 | Vague subagent prompts | Specify what to analyze, look for, and return |
| AP-15 | Reference dumps | Teach judgment, not raw documentation |
| AP-16 | Missing rationalizations | Add "Rationalizations to Reject" for audit skills |
| AP-17 | No concrete examples | Show input -> output for key instructions |
| AP-18 | Cartesian product tool calls | Combine patterns into single regex, grep once, then filter |
| AP-19 | Unbounded subagent spawning | Batch items into groups, one subagent per batch |
*AP-10 (No Default/Fallback Route), AP-14 (Missing Tool Justification in Agents), and AP-20 (Description Summarizes Workflow) are in the [full catalog](references/anti-patterns.md). AP-20 is included in the quick reference above due to its high impact.*
## Tool Assignment Quick Reference
Map your component type to the right tool set. Full guide in [tool-assignment-guide.md](references/tool-assignment-guide.md).
- Skills use `allowed-tools:` — agents use `tools:`
- List only tools that instructions actually reference
- Read-only components should never have Write or Bash
## Rationalizations to Reject
When designing workflow skills, reject these shortcuts:
| Rationalization | Why 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. The LLM loses focus past 500 lines. |
| "The description doesn't matter much" | The description is how the skill gets triggered. A bad description means wrong activations or missed activations. |
| "Bash can do everything" | Bash file operations are fragile. Dedicated tools handle encoding, permissions, and formatting better. |
| "The LLM will figure out the tools" | It will guess wrong. Specify exactly which tool for each operation. |
