designing-workflow-skills

# 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." </principle> <principle name="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) </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`. Neve...