designing-workflow-skills
Structural design patterns and principles for reliable multi-step Claude Code workflow skills.
- Covers five workflow patterns (routing, sequential pipeline, linear progression, safety gate, task-driven) with numbered phases, entry/exit criteria, and decision trees for pattern selection
- Enforces progressive disclosure: SKILL.md stays under 500 lines with details split into
references/andworkflows/directories, one level deep - Provides 20 anti-patterns with before/after fixes, covering unnumbered phases, broken references, hardcoded paths, tool mismatches, and unbounded subagent spawning
- Includes tool assignment matrix matching component types to minimum required tools, plus rationalizations to reject during design
- Emphasizes that skill descriptions control activation (triggering keywords only), phases need explicit exit criteria, and instructions must produce bounded tool-calling patterns at scale
Designing Workflow Skills
Build workflow-based skills that execute reliably by following structural patterns, not prose.
Essential Principles
<essential_principles>
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."
More from trailofbits/skills
ask-questions-if-underspecified
Clarify requirements before implementing. Use when serious doubts arise.
4.2Ksemgrep
>-
3.8Kmodern-python
Configures Python projects with modern tooling (uv, ruff, ty). Use when creating projects, writing standalone scripts, or migrating from pip/Poetry/mypy/black.
3.8Kcodeql
>-
3.6Kinsecure-defaults
Detects fail-open insecure defaults (hardcoded secrets, weak auth, permissive security) that allow apps to run insecurely in production. Use when auditing security, reviewing config management, or analyzing environment variable handling.
3.5Ksecure-workflow-guide
Guides through Trail of Bits' 5-step secure development workflow. Runs Slither scans, checks special features (upgradeability/ERC conformance/token integration), generates visual security diagrams, helps document security properties for fuzzing/verification, and reviews manual security areas.
3.4K