tools-only 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 CriteriaWrite 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.