designing-workflow-skills

Follow the six-phase process: define scope with a trigger-focused description, choose one of five workflow patterns using the decision tree, design numbered phases with entry and exit criteria, assign least-privilege tools, write content with progressive disclosure, then self-review against the checklist.

Use the decision tree: a single non-destructive path maps to Linear Progression, destructive actions to Safety Gate, multiple independent tasks to Routing, dependent sequential steps to Sequential Pipeline, and complex dependencies with partial failure tolerance to Task-Driven.

Activation is controlled solely by the frontmatter description field, not the SKILL.md body. Write the description in third person with specific trigger keywords and exclusions, and never summarize workflow steps in it, since Claude treats it as an executive summary.

SKILL.md should stay under 500 lines, ideally 200-400. Beyond that threshold LLM attention degrades. Move detailed patterns into references/ files (under 400 lines each) and step-by-step processes into workflows/ files (under 300 lines each), all one hop from SKILL.md.

Common mistakes include using Bash for file operations instead of dedicated Glob, Grep, and Read tools, listing unused tools that violate least privilege, and confusing allowed-tools (skills) with tools (agents). Also avoid per-file-per-pattern grep loops and one-subagent-per-file spawning.

Skip this structure for simple single-purpose skills with no workflow, which can be written directly as a plain SKILL.md. It also does not cover plugin configuration like plugin.json, hooks, or commands, nor the actual domain content of a skill.