designing-workflow-skills

Structural design patterns and principles for reliable multi-step Claude Code workflow skills. Build workflow-based skills that execute reliably by following structural patterns, not prose. 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." Unnumbered prose instructions produce unreliable execution order.