Designing a Workflow Skill
A 6-phase process for creating a workflow-based skill from scratch.
Phase 1: Define Scope
Entry: You have a task domain in mind (e.g., "audit smart contracts", "triage findings").
Actions:
-
Draft the
descriptionfirst — this is the most important field. Claude decides whether to activate a skill based solely on thedescriptionin frontmatter. Third-person voice, include trigger keywords and exclusions. Test it: would this description cause the skill to activate for the right requests and stay silent for wrong ones? -
Write the "When to Use" section. List 4-6 specific scenarios where the skill applies. These scope the LLM's behavior after activation — be concrete: "when auditing Solidity for reentrancy" not "when doing security."
-
Write the "When NOT to Use" section. List 3-5 scenarios where a different approach is better. Name the alternative: "use Semgrep for simple pattern matching" not "not for simple cases." These help the LLM redirect once active, but do not affect whether the skill activates.
-
Define 3-5 essential principles. These are non-negotiable rules that apply to every invocation. Ask: "What mistake would ruin the output if the LLM made it?" Each principle guards against a specific failure mode.
Exit: You have a draft description, When to Use, When NOT to Use, and essential principles.
Phase 2: Choose Pattern
Entry: Phase 1 complete. You understand the skill's scope.
Actions:
-
Count the distinct tasks the skill handles. One task? Multiple independent tasks? A sequence of dependent steps?
-
Map to a pattern using this decision tree:
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
└─ Unsure
└─ Start with Linear Progression, refactor if needed
-
Read the pattern description in
references/workflow-patterns.md. Study the structural skeleton. -
Validate the choice. Does your skill's workflow naturally fit the skeleton? If you're forcing it, try a different pattern.
Exit: Pattern selected and validated against your skill's structure.
Phase 3: Design Phases
Entry: Phase 2 complete. Pattern selected.
Actions:
-
List every step the skill must perform, in execution order.
-
Group steps into phases. Each phase should have a single responsibility. A phase that does two unrelated things should be split.
-
For each phase, define:
- Entry criteria: What must be true before this phase starts?
- Actions: Numbered list of specific steps.
- Exit criteria: What artifact or state proves this phase is complete?
-
Identify gates (if using Safety Gate pattern). Where must execution pause for user confirmation? Gates go between analysis and action, never within either.
-
Add a verification phase at the end. What checks confirm the overall output is correct?
-
Check dependencies. Can any phases run in parallel? Must any phases always run in sequence? Document these constraints.
Exit: Complete phase list with entry/exit criteria for each phase.
Phase 4: Assign Tools
Entry: Phase 3 complete. Phases designed.
Actions:
-
For each action in each phase, identify the tool it needs:
- Finding files -> Glob
- Searching content -> Grep
- Reading files -> Read
- Creating files -> Write
- Editing files -> Edit
- Running commands -> Bash
- User confirmation -> AskUserQuestion
- Delegating work -> Task
- Tracking steps -> TaskCreate/TaskUpdate/TaskList
-
Compile the unique tool list. This becomes your
allowed-toolsin frontmatter. -
Audit for least privilege. Remove any tool not actually used. Ask: "If I removed this tool, would any instruction break?"
-
Check for Bash misuse. Any action using Bash for file operations (grep, find, cat) should use the dedicated tool instead.
-
For agents, repeat this process for the agent's tool list. Agent tools are specified with
tools:notallowed-tools:.
See references/tool-assignment-guide.md for the complete tool selection matrix.
Exit: Validated tool list for each component (skill, agents).
Phase 5: Write Content
Entry: Phase 4 complete. Tools assigned.
Actions:
-
Start with SKILL.md skeleton:
Frontmatter (name, description, allowed-tools) Essential Principles When to Use / When NOT to Use Pattern-specific routing or workflow Quick Reference Tables Reference Index Success Criteria -
Write reference files first. These are the foundation that SKILL.md summarizes and links to.
-
Write workflow files. Each workflow follows the phase structure from Phase 3.
-
Write SKILL.md last. It summarizes and routes to the reference and workflow files.
-
Check line counts:
- SKILL.md: under 500 lines
- Reference files: under 400 lines each
- Workflow files: under 300 lines each
-
Verify progressive disclosure: SKILL.md contains only what's needed for every invocation. Details are in linked files.
See references/progressive-disclosure-guide.md for the splitting heuristic.
Exit: All content files written, line counts within limits.
Phase 6: Self-Review
Entry: Phase 5 complete. All files written.
Actions:
-
Run the review checklist in
workflows/review-checklist.md. -
Check anti-patterns against
references/anti-patterns.md. Scan for each one. -
Validate file references. Every path in SKILL.md must resolve to an existing file.
-
Test the description. Read it in isolation — this is the only thing Claude uses to decide activation. Would it cause the skill to activate for the right requests and stay silent for wrong ones?
-
Check for hardcoded paths. Search for
/Users/,/home/, any absolute path. -
Verify frontmatter. Valid YAML, kebab-case name, description present, tools list matches actual usage.
-
Read SKILL.md as if you've never seen it. Is the execution order unambiguous? Could an LLM follow it without your context?
Exit: All checks pass. Skill is ready for submission.