Designing Workflow Skills
Build workflow-based skills that execute reliably by following structural patterns, not prose. This is a meta-skill: it teaches skill architecture, not domain expertise.
Overview
Workflow skills are SKILL.md files that guide an agent through multi-step, phased, or routed execution. Reliability comes from structure—numbered phases, entry/exit criteria, tool assignment, and progressive disclosure—not from prose that assumes the LLM will infer ordering or intent.
This skill covers five workflow patterns, twenty anti-patterns, tool assignment rules, and a six-phase creation process. Detailed references live one hop deep in references/ and workflows/.
Essential Principles
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—including "When to Use" and "When NOT to Use"—is only read AFTER activation. Put trigger keywords, use cases, and exclusions in the description. A bad description means wrong or missed activations regardless of body content. "When NOT to Use" should name specific alternatives: "use Semgrep for simple pattern matching" not "not for simple tasks."
Phases must be numbered with entry and exit criteria. Unnumbered prose produces 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), and exit criteria (how to know it's done).
Tools must match the executor. Skills use allowed-tools: in frontmatter. Agents use tools: in frontmatter. Subagents get tools from their subagent_type. Never list tools the component doesn't use. Never use Bash for operations that have dedicated tools (Glob, Grep, Read, Write, Edit). Most skills and agents should include TodoRead and TodoWrite for progress tracking during multi-step execution.
Progressive disclosure is structural, not optional. SKILL.md stays under 500 lines. It contains only what the LLM needs for every invocation: principles, routing, quick references, and links. Detailed patterns go in references/. Step-by-step processes go in workflows/. One level deep—no reference chains (A → B → C). All files are one hop from SKILL.md.
Instructions must produce tool-calling patterns that scale. Every workflow instruction becomes tool calls at runtime. If a workflow searches N files for M patterns, combine into one regex, not N×M calls. If a workflow spawns subagents per item, use batching, not one subagent per file. Apply the 10,000-file test: mentally run the workflow against a large repo and check that tool call count stays bounded. See AP-18 and AP-19 in the anti-pattern table below.
Match instruction specificity to task fragility. Calibrate per step:
- Low freedom (exact commands, no variation): Fragile operations—database migrations, crypto, destructive actions. "Run exactly this script."
- Medium freedom (pseudocode with parameters): Preferred patterns where variation is acceptable. "Use this template and customize as needed."
- High freedom (heuristics and judgment): Variable tasks—code review, exploration, documentation. "Analyze the structure and suggest improvements."
- A skill can mix freedom levels. A security audit skill might use high freedom for discovery and low freedom for reporting.
When to Use
- Designing a new skill with multi-step workflows or phased execution
- Creating a skill that routes between multiple independent tasks
- Building a skill with safety gates (destructive actions requiring confirmation)
- Structuring a skill that uses subagents or task tracking
- Reviewing or refactoring an existing workflow skill for quality
- Deciding how to split content between SKILL.md,
references/, and workflows/
When NOT to Use
- Simple single-purpose skills with no workflow (just guidance)—write the SKILL.md directly
- Writing the actual domain content of a skill—this teaches structure, not domain expertise
- Plugin configuration (plugin.json, hooks, commands)—use plugin development guides
- Non-skill agent development—this is specifically for skill architecture
Prerequisites
- Familiarity with SKILL.md frontmatter fields (
name, description, allowed-tools)
- Access to the skill's target codebase or domain context
- Pattern, anti-pattern, tool-assignment, and progressive-disclosure guidance in this skill (companion files are not required)
Procedure
Phase 1: Select a Pattern
Entry criteria: You know the skill's purpose and have a rough scope.
- Determine how many distinct execution paths the skill has using the decision tree below.
- Read the pattern table in this phase before committing to a pattern.
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
| Pattern |
Use When |
Key Feature |
| Routing |
Multiple independent tasks from shared intake |
Routing table maps intent to workflow files |
| Sequential Pipeline |
Dependent steps, each feeding the next |
Auto-detection may resume from partial progress |
| Linear Progression |
Single path, same every time |
Numbered phases with entry/exit criteria |
| Safety Gate |
Destructive/irreversible actions |
Two confirmation gates before execution |
| Task-Driven |
Complex dependencies, partial failure tolerance |
TaskCreate/TaskUpdate with dependency tracking |
Exit criteria: A pattern name is chosen and its skeleton from the pattern table above has been reviewed.
Phase 2: Write the Frontmatter
Entry criteria: Pattern is selected.
- Write
name in kebab-case.
- Write
description in third person with specific trigger keywords. This is the ONLY field that controls activation. Never summarize workflow steps in the description (AP-20).
- List
allowed-tools (space-delimited). Include only tools the instructions actually reference. Use the tool assignment matrix below. Include TodoRead and TodoWrite for multi-step skills.
- Add optional fields only if needed:
disable-model-invocation: true — only user can invoke (not Claude)
user-invocable: false — only Claude can invoke (hidden from / menu)
context: fork — run in isolated subagent context
agent: Explore — subagent type (requires context: fork)
model: [model-name] — switch model when skill is active
argument-hint: "[filename]" — hint shown during autocomplete
Exit criteria: Frontmatter is complete with correct tool list and trigger-optimized description.
Phase 3: Write the Body
Entry criteria: Frontmatter is complete.
- Write
## Essential Principles — 3–5 non-negotiable rules with WHY explanations.
- Write
## When to Use — 4–6 specific scenarios that scope behavior after activation.
- Write
## When NOT to Use — 3–5 scenarios with named alternatives.
- Write the pattern-specific section (routing table, pipeline steps, phase list, or gates).
- Write
## Quick Reference — compact tables for frequently-needed info.
- Write
## Reference Index — links to all supporting files in references/ and workflows/.
- Write
## Success Criteria — checklist for output validation.
- Keep total under 500 lines. Move details to
references/, step-by-step processes to workflows/.
Exit criteria: Body is complete, under 500 lines, and all file references resolve.
Phase 4: Assign Tools
Entry criteria: Body is written and you know which operations the skill performs.
- Map component type to tool set using the matrix below.
- Remove any tool not actually referenced in the instructions (AP-12).
- Verify read-only components never include
Write or Bash.
- Use Glob (not
find), Grep (not grep), Read (not cat)—always prefer dedicated tools (AP-11).
| Component Type |
Typical Tools |
| Read-only analysis skill |
Read, Glob, Grep, TodoRead, TodoWrite |
| Interactive analysis skill |
Read, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite |
| Code generation skill |
Read, Glob, Grep, Write, Bash, TodoRead, TodoWrite |
| Pipeline skill |
Read, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite |
| Read-only agent |
Read, Grep, Glob, TodoRead, TodoWrite |
| Action agent |
Read, Grep, Glob, Write, Bash, TodoRead, TodoWrite |
Exit criteria: Tool list is minimal, correct, and matches the executor type.
Phase 5: Check Anti-Patterns
Entry criteria: Skill is drafted.
- Review all 20 anti-patterns in the table below.
- Run through the quick reference table below for the most common mistakes.
- Fix any violations found.
| AP |
Anti-Pattern |
One-Line Fix |
| AP-1 |
Missing goals/anti-goals |
Add When to Use AND When NOT to Use sections |
| AP-2 |
Monolithic SKILL.md (>500 lines) |
Split into references/ and workflows/ |
| AP-3 |
Reference chains (A → B → C) |
All files one hop from SKILL.md |
| AP-4 |
Hardcoded paths |
Use {baseDir} for all internal paths |
| AP-5 |
Broken file references |
Verify every path resolves before submitting |
| AP-6 |
Unnumbered phases |
Number every phase with entry/exit criteria |
| AP-7 |
Missing exit criteria |
Define what "done" means for every phase |
| AP-8 |
No verification step |
Add validation at the end of every workflow |
| AP-9 |
Vague routing keywords |
Use distinctive keywords per workflow route |
| AP-11 |
Wrong tool for the job |
Use Glob/Grep/Read, not Bash equivalents |
| AP-12 |
Overprivileged tools |
Remove tools not actually used |
| AP-13 |
Vague subagent prompts |
Specify what to analyze, look for, and return |
| AP-15 |
Reference dumps |
Teach judgment, not raw documentation |
| AP-16 |
Missing rationalizations |
Add "Rationalizations to Reject" for audit skills |
| AP-17 |
No concrete examples |
Show input → output for key instructions |
| AP-18 |
Cartesian product tool calls |
Combine patterns into single regex, grep once, then filter |
| AP-19 |
Unbounded subagent spawning |
Batch items into groups, one subagent per batch |
| AP-20 |
Description summarizes workflow |
Description = triggering conditions only, never workflow steps |
Exit criteria: No anti-pattern violations remain.
Phase 6: Self-Review
Entry criteria: Anti-patterns are fixed.
- Load
workflows/review-checklist.md and run through the full structured self-review.
- Verify every file reference resolves (no broken links).
- Verify no hardcoded paths—all internal paths use
{baseDir}.
- Run the 10,000-file test: mentally execute the workflow against a large repo and confirm tool call count stays bounded.
- Confirm the description would trigger correctly for the intended use cases and NOT trigger for excluded cases.
Exit criteria: All checklist items pass.
Structural Anatomy
Every workflow skill needs this skeleton, regardless of pattern:
---
name: kebab-case-name
description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
allowed-tools: Tool1 Tool2 Tool3
---
# Title
## Essential Principles
[3-5 non-negotiable rules with WHY explanations]
## When to Use
[4-6 specific scenarios — scopes behavior after activation]
## When NOT to Use
[3-5 scenarios with named alternatives — scopes behavior after activation]
## [Pattern-Specific Section]
[Routing table / Pipeline steps / Phase list / Gates]
## Quick Reference
[Compact tables for frequently-needed info]
## Reference Index
[Links to all supporting files]
## Success Criteria
[Checklist for output validation]
Skills support string substitutions: dollar-prefixed variables for arguments and session ID, and exclamation-backtick syntax for shell preprocessing. The skill loader processes these before Claude sees the file—even inside code fences—so never use the raw syntax in documentation text. See the tool assignment matrix in Phase 4 for the full variable reference.
Rationalizations to Reject
| Rationalization |
Why It's Wrong |
| "It's obvious which phase comes next" |
LLMs don't infer ordering from prose. Number the phases. |
| "Exit criteria are implied" |
Implied criteria are skipped criteria. Write them explicitly. |
| "One big SKILL.md is simpler" |
Simpler to write, worse to execute. The LLM loses focus past 500 lines. |
| "The description doesn't matter much" |
The description is how the skill gets triggered. A bad description means wrong or missed activations. |
| "Bash can do everything" |
Bash file operations are fragile. Dedicated tools handle encoding, permissions, and formatting better. |
| "The LLM will figure out the tools" |
It will guess wrong. Specify exactly which tool for each operation. |
| "I'll add details later" |
Incomplete skills ship incomplete. Design fully before writing. |
Pitfalls
Description summarizes the workflow instead of stating trigger conditions. The description is a trigger, not a summary. Write "Use when reviewing code for security vulnerabilities, injection risks, and auth bypass" not "This skill runs a 5-phase security audit with static analysis and reporting."
Unnumbered phases cause out-of-order execution. LLMs do not infer sequence from prose structure. Every phase must have an explicit number, entry criteria, and exit criteria.
Reference chains (A → B → C) lose context. Each hop forces the LLM to reload context. All reference files must be exactly one hop from SKILL.md. If a reference needs to reference another file, inline the content instead.
Hardcoded paths break portability. Use {baseDir} for all internal paths. Never hardcode ~ or /home/... paths in skill files.
Overprivileged tool lists cause unintended actions. A read-only analysis skill with Bash can accidentally execute destructive commands. List only the tools the instructions actually reference.
Cartesian product tool calls don't scale. If a workflow searches N files for M patterns, writing N×M individual calls will exhaust context on large repos. Combine into a single regex or batch operation. Apply the 10,000-file test.
Unbounded subagent spawning exhausts resources. If a workflow spawns one subagent per file, a 10,000-file repo will hang. Batch items into groups and spawn one subagent per batch.
String substitution syntax leaks into documentation. The skill loader processes $variable and !`command` syntax before Claude sees the file, even inside code fences. Never use the raw syntax when documenting it—escape or describe it indirectly.
Verification
After designing a workflow skill, verify:
Frontmatter check:
Select-String -Path "SKILL.md" -Pattern "^name:" | ForEach-Object { $_.Line }
Select-String -Path "SKILL.md" -Pattern "^description:" | ForEach-Object { $_.Line }
Select-String -Path "SKILL.md" -Pattern "^allowed-tools:" | ForEach-Object { $_.Line }
Confirm name is kebab-case, description contains trigger keywords (not workflow summary), and allowed-tools lists only used tools.
Line count check (must be under 500):
(Get-Content "SKILL.md").Count
File reference resolution:
Select-String -Path "SKILL.md" -Pattern '\[.*?\]\((references|workflows)/.*?\.md\)' -AllMatches |
ForEach-Object { $_.Matches } |
ForEach-Object { $_.Groups[1].Value + "/" + $_.Value } |
ForEach-Object { if (-not (Test-Path $_)) { Write-Output "BROKEN: $_" } }
Output should be empty—no broken references.
Hardcoded path check:
Select-String -Path "SKILL.md" -Pattern 'C:\\Users\\|/home/|/Users/' |
ForEach-Object { Write-Output "HARDCODED: $($_.LineNumber): $($_.Line)" }
Output should be empty (unless documenting a specific machine path by design).
Reference chain check: Manually open each file in references/ and workflows/ and confirm none link to another reference file. All links must point back to SKILL.md or external URLs only.
Success criteria checklist:
Reference Index
| Topic |
Content |
When to use |
| Workflow patterns |
5 patterns with structural skeletons and examples |
Phase 1: before selecting a pattern (table above) |
| Anti-patterns |
20 anti-patterns with before/after fixes |
Phase 5: before reviewing the draft (table above) |
| Tool assignment |
Tool selection matrix, component comparison, subagent guidance |
Phase 4: when assigning tools |
| Progressive disclosure |
Content splitting rules, the 500-line rule, sizing guidelines |
Phase 3 / Essential Principle 4 |
| Creation process |
6-phase creation from scope to self-review |
Phases 1–6 in this skill |
| Self-review |
Structured checklist for submission readiness |
Phase 6 and Verification below |
Related Skills
- progressive-disclosure-guide — Content splitting rules and the 500-line rule
- tool-assignment-guide — Tool selection matrix and subagent guidance
- anti-patterns — Full catalog of 20 anti-patterns with fixes
1---
2name: designing-workflow-skills
3description: "Architects workflow SKILL.md files with numbered phases, routing/safety-gate/task-driven patterns, tool assignment, and progressive disclosure. Use when building or reviewing a multi-step skill structure rather than its domain content. Not for Cursor skill scaffolding (create-skill) or hermes-agent in-repo authoring (hermes-agent-skill-authoring)."
4version: 1.0.1
5metadata:
6 source: https://skillmd.com/skills/kayforkind/designing-workflow-skills
7---
8
9# Designing Workflow Skills
10
11Build workflow-based skills that execute reliably by following structural patterns, not prose. This is a meta-skill: it teaches skill architecture, not domain expertise.
12
13## Overview
14
15Workflow skills are SKILL.md files that guide an agent through multi-step, phased, or routed execution. Reliability comes from structure—numbered phases, entry/exit criteria, tool assignment, and progressive disclosure—not from prose that assumes the LLM will infer ordering or intent.
16
17This skill covers five workflow patterns, twenty anti-patterns, tool assignment rules, and a six-phase creation process. Detailed references live one hop deep in `references/` and `workflows/`.
18
19## Essential Principles
20
211. **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—including "When to Use" and "When NOT to Use"—is only read AFTER activation. Put trigger keywords, use cases, and exclusions in the description. A bad description means wrong or missed activations regardless of body content. "When NOT to Use" should name specific alternatives: "use Semgrep for simple pattern matching" not "not for simple tasks."
22
232. **Phases must be numbered with entry and exit criteria.** Unnumbered prose produces 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), and exit criteria (how to know it's done).
24
253. **Tools must match the executor.** Skills use `allowed-tools:` in frontmatter. Agents use `tools:` in frontmatter. Subagents get tools from their `subagent_type`. Never list tools the component doesn't use. Never use Bash for operations that have dedicated tools (Glob, Grep, Read, Write, Edit). Most skills and agents should include `TodoRead` and `TodoWrite` for progress tracking during multi-step execution.
26
274. **Progressive disclosure is structural, not optional.** SKILL.md stays under 500 lines. It contains only what the LLM needs for every invocation: principles, routing, quick references, and links. Detailed patterns go in `references/`. Step-by-step processes go in `workflows/`. One level deep—no reference chains (A → B → C). All files are one hop from SKILL.md.
28
295. **Instructions must produce tool-calling patterns that scale.** Every workflow instruction becomes tool calls at runtime. If a workflow searches N files for M patterns, combine into one regex, not N×M calls. If a workflow spawns subagents per item, use batching, not one subagent per file. Apply the 10,000-file test: mentally run the workflow against a large repo and check that tool call count stays bounded. See AP-18 and AP-19 in the anti-pattern table below.
30
316. **Match instruction specificity to task fragility.** Calibrate per step:
32 - **Low freedom** (exact commands, no variation): Fragile operations—database migrations, crypto, destructive actions. "Run exactly this script."
33 - **Medium freedom** (pseudocode with parameters): Preferred patterns where variation is acceptable. "Use this template and customize as needed."
34 - **High freedom** (heuristics and judgment): Variable tasks—code review, exploration, documentation. "Analyze the structure and suggest improvements."
35 - A skill can mix freedom levels. A security audit skill might use high freedom for discovery and low freedom for reporting.
36
37## When to Use
38
39- Designing a new skill with multi-step workflows or phased execution
40- Creating a skill that routes between multiple independent tasks
41- Building a skill with safety gates (destructive actions requiring confirmation)
42- Structuring a skill that uses subagents or task tracking
43- Reviewing or refactoring an existing workflow skill for quality
44- Deciding how to split content between SKILL.md, `references/`, and `workflows/`
45
46## When NOT to Use
47
48- Simple single-purpose skills with no workflow (just guidance)—write the SKILL.md directly
49- Writing the actual domain content of a skill—this teaches structure, not domain expertise
50- Plugin configuration (plugin.json, hooks, commands)—use plugin development guides
51- Non-skill agent development—this is specifically for skill architecture
52
53## Prerequisites
54
55- Familiarity with SKILL.md frontmatter fields (`name`, `description`, `allowed-tools`)
56- Access to the skill's target codebase or domain context
57- Pattern, anti-pattern, tool-assignment, and progressive-disclosure guidance in this skill (companion files are not required)
58
59## Procedure
60
61### Phase 1: Select a Pattern
62
63**Entry criteria:** You know the skill's purpose and have a rough scope.
64
651. Determine how many distinct execution paths the skill has using the decision tree below.
662. Read the pattern table in this phase before committing to a pattern.
67
68```
69How many distinct paths does the skill have?
70|
71+-- One path, always the same
72| +-- Does it perform destructive actions?
73| +-- YES -> Safety Gate Pattern
74| +-- NO -> Linear Progression Pattern
75|
76+-- Multiple independent paths from shared setup
77| +-- Routing Pattern
78|
79+-- Multiple dependent steps in sequence
80 +-- Do steps have complex dependencies?
81 +-- YES -> Task-Driven Pattern
82 +-- NO -> Sequential Pipeline Pattern
83```
84
85| Pattern | Use When | Key Feature |
86|---------|----------|-------------|
87| **Routing** | Multiple independent tasks from shared intake | Routing table maps intent to workflow files |
88| **Sequential Pipeline** | Dependent steps, each feeding the next | Auto-detection may resume from partial progress |
89| **Linear Progression** | Single path, same every time | Numbered phases with entry/exit criteria |
90| **Safety Gate** | Destructive/irreversible actions | Two confirmation gates before execution |
91| **Task-Driven** | Complex dependencies, partial failure tolerance | TaskCreate/TaskUpdate with dependency tracking |
92
93**Exit criteria:** A pattern name is chosen and its skeleton from the pattern table above has been reviewed.
94
95### Phase 2: Write the Frontmatter
96
97**Entry criteria:** Pattern is selected.
98
991. Write `name` in kebab-case.
1002. Write `description` in third person with specific trigger keywords. This is the ONLY field that controls activation. Never summarize workflow steps in the description (AP-20).
1013. List `allowed-tools` (space-delimited). Include only tools the instructions actually reference. Use the tool assignment matrix below. Include `TodoRead` and `TodoWrite` for multi-step skills.
1024. Add optional fields only if needed:
103 - `disable-model-invocation: true` — only user can invoke (not Claude)
104 - `user-invocable: false` — only Claude can invoke (hidden from `/` menu)
105 - `context: fork` — run in isolated subagent context
106 - `agent: Explore` — subagent type (requires `context: fork`)
107 - `model: [model-name]` — switch model when skill is active
108 - `argument-hint: "[filename]"` — hint shown during autocomplete
109
110**Exit criteria:** Frontmatter is complete with correct tool list and trigger-optimized description.
111
112### Phase 3: Write the Body
113
114**Entry criteria:** Frontmatter is complete.
115
1161. Write `## Essential Principles` — 3–5 non-negotiable rules with WHY explanations.
1172. Write `## When to Use` — 4–6 specific scenarios that scope behavior after activation.
1183. Write `## When NOT to Use` — 3–5 scenarios with named alternatives.
1194. Write the pattern-specific section (routing table, pipeline steps, phase list, or gates).
1205. Write `## Quick Reference` — compact tables for frequently-needed info.
1216. Write `## Reference Index` — links to all supporting files in `references/` and `workflows/`.
1227. Write `## Success Criteria` — checklist for output validation.
1238. Keep total under 500 lines. Move details to `references/`, step-by-step processes to `workflows/`.
124
125**Exit criteria:** Body is complete, under 500 lines, and all file references resolve.
126
127### Phase 4: Assign Tools
128
129**Entry criteria:** Body is written and you know which operations the skill performs.
130
1311. Map component type to tool set using the matrix below.
1322. Remove any tool not actually referenced in the instructions (AP-12).
1333. Verify read-only components never include `Write` or `Bash`.
1344. Use Glob (not `find`), Grep (not `grep`), Read (not `cat`)—always prefer dedicated tools (AP-11).
135
136| Component Type | Typical Tools |
137|---------------|---------------|
138| Read-only analysis skill | Read, Glob, Grep, TodoRead, TodoWrite |
139| Interactive analysis skill | Read, Glob, Grep, AskUserQuestion, TodoRead, TodoWrite |
140| Code generation skill | Read, Glob, Grep, Write, Bash, TodoRead, TodoWrite |
141| Pipeline skill | Read, Write, Glob, Grep, Bash, AskUserQuestion, Task, TaskCreate, TaskList, TaskUpdate, TodoRead, TodoWrite |
142| Read-only agent | Read, Grep, Glob, TodoRead, TodoWrite |
143| Action agent | Read, Grep, Glob, Write, Bash, TodoRead, TodoWrite |
144
145**Exit criteria:** Tool list is minimal, correct, and matches the executor type.
146
147### Phase 5: Check Anti-Patterns
148
149**Entry criteria:** Skill is drafted.
150
1511. Review all 20 anti-patterns in the table below.
1522. Run through the quick reference table below for the most common mistakes.
1533. Fix any violations found.
154
155| AP | Anti-Pattern | One-Line Fix |
156|----|-------------|-------------|
157| AP-1 | Missing goals/anti-goals | Add When to Use AND When NOT to Use sections |
158| AP-2 | Monolithic SKILL.md (>500 lines) | Split into `references/` and `workflows/` |
159| AP-3 | Reference chains (A → B → C) | All files one hop from SKILL.md |
160| AP-4 | Hardcoded paths | Use `{baseDir}` for all internal paths |
161| AP-5 | Broken file references | Verify every path resolves before submitting |
162| AP-6 | Unnumbered phases | Number every phase with entry/exit criteria |
163| AP-7 | Missing exit criteria | Define what "done" means for every phase |
164| AP-8 | No verification step | Add validation at the end of every workflow |
165| AP-9 | Vague routing keywords | Use distinctive keywords per workflow route |
166| AP-11 | Wrong tool for the job | Use Glob/Grep/Read, not Bash equivalents |
167| AP-12 | Overprivileged tools | Remove tools not actually used |
168| AP-13 | Vague subagent prompts | Specify what to analyze, look for, and return |
169| AP-15 | Reference dumps | Teach judgment, not raw documentation |
170| AP-16 | Missing rationalizations | Add "Rationalizations to Reject" for audit skills |
171| AP-17 | No concrete examples | Show input → output for key instructions |
172| AP-18 | Cartesian product tool calls | Combine patterns into single regex, grep once, then filter |
173| AP-19 | Unbounded subagent spawning | Batch items into groups, one subagent per batch |
174| AP-20 | Description summarizes workflow | Description = triggering conditions only, never workflow steps |
175
176**Exit criteria:** No anti-pattern violations remain.
177
178### Phase 6: Self-Review
179
180**Entry criteria:** Anti-patterns are fixed.
181
1821. Load `workflows/review-checklist.md` and run through the full structured self-review.
1832. Verify every file reference resolves (no broken links).
1843. Verify no hardcoded paths—all internal paths use `{baseDir}`.
1854. Run the 10,000-file test: mentally execute the workflow against a large repo and confirm tool call count stays bounded.
1865. Confirm the description would trigger correctly for the intended use cases and NOT trigger for excluded cases.
187
188**Exit criteria:** All checklist items pass.
189
190## Structural Anatomy
191
192Every workflow skill needs this skeleton, regardless of pattern:
193
194```markdown
195---
196name: kebab-case-name
197description: "Third-person description with trigger keywords — this is how Claude decides to activate the skill"
198allowed-tools: Tool1 Tool2 Tool3
199---
200
201# Title
202
203## Essential Principles
204[3-5 non-negotiable rules with WHY explanations]
205
206## When to Use
207[4-6 specific scenarios — scopes behavior after activation]
208
209## When NOT to Use
210[3-5 scenarios with named alternatives — scopes behavior after activation]
211
212## [Pattern-Specific Section]
213[Routing table / Pipeline steps / Phase list / Gates]
214
215## Quick Reference
216[Compact tables for frequently-needed info]
217
218## Reference Index
219[Links to all supporting files]
220
221## Success Criteria
222[Checklist for output validation]
223```
224
225Skills support string substitutions: dollar-prefixed variables for arguments and session ID, and exclamation-backtick syntax for shell preprocessing. The skill loader processes these before Claude sees the file—even inside code fences—so never use the raw syntax in documentation text. See the tool assignment matrix in Phase 4 for the full variable reference.
226
227## Rationalizations to Reject
228
229| Rationalization | Why It's Wrong |
230|-----------------|----------------|
231| "It's obvious which phase comes next" | LLMs don't infer ordering from prose. Number the phases. |
232| "Exit criteria are implied" | Implied criteria are skipped criteria. Write them explicitly. |
233| "One big SKILL.md is simpler" | Simpler to write, worse to execute. The LLM loses focus past 500 lines. |
234| "The description doesn't matter much" | The description is how the skill gets triggered. A bad description means wrong or missed activations. |
235| "Bash can do everything" | Bash file operations are fragile. Dedicated tools handle encoding, permissions, and formatting better. |
236| "The LLM will figure out the tools" | It will guess wrong. Specify exactly which tool for each operation. |
237| "I'll add details later" | Incomplete skills ship incomplete. Design fully before writing. |
238
239## Pitfalls
240
241- **Description summarizes the workflow instead of stating trigger conditions.** The description is a trigger, not a summary. Write "Use when reviewing code for security vulnerabilities, injection risks, and auth bypass" not "This skill runs a 5-phase security audit with static analysis and reporting."
242
243- **Unnumbered phases cause out-of-order execution.** LLMs do not infer sequence from prose structure. Every phase must have an explicit number, entry criteria, and exit criteria.
244
245- **Reference chains (A → B → C) lose context.** Each hop forces the LLM to reload context. All reference files must be exactly one hop from SKILL.md. If a reference needs to reference another file, inline the content instead.
246
247- **Hardcoded paths break portability.** Use `{baseDir}` for all internal paths. Never hardcode `~` or `/home/...` paths in skill files.
248
249- **Overprivileged tool lists cause unintended actions.** A read-only analysis skill with `Bash` can accidentally execute destructive commands. List only the tools the instructions actually reference.
250
251- **Cartesian product tool calls don't scale.** If a workflow searches N files for M patterns, writing N×M individual calls will exhaust context on large repos. Combine into a single regex or batch operation. Apply the 10,000-file test.
252
253- **Unbounded subagent spawning exhausts resources.** If a workflow spawns one subagent per file, a 10,000-file repo will hang. Batch items into groups and spawn one subagent per batch.
254
255- **String substitution syntax leaks into documentation.** The skill loader processes `$variable` and `` !`command` `` syntax before Claude sees the file, even inside code fences. Never use the raw syntax when documenting it—escape or describe it indirectly.
256
257## Verification
258
259After designing a workflow skill, verify:
260
2611. **Frontmatter check:**
262 ```powershell
263 Select-String -Path "SKILL.md" -Pattern "^name:" | ForEach-Object { $_.Line }
264 Select-String -Path "SKILL.md" -Pattern "^description:" | ForEach-Object { $_.Line }
265 Select-String -Path "SKILL.md" -Pattern "^allowed-tools:" | ForEach-Object { $_.Line }
266 ```
267 Confirm `name` is kebab-case, `description` contains trigger keywords (not workflow summary), and `allowed-tools` lists only used tools.
268
2692. **Line count check (must be under 500):**
270 ```powershell
271 (Get-Content "SKILL.md").Count
272 ```
273
2743. **File reference resolution:**
275 ```powershell
276 Select-String -Path "SKILL.md" -Pattern '\[.*?\]\((references|workflows)/.*?\.md\)' -AllMatches |
277 ForEach-Object { $_.Matches } |
278 ForEach-Object { $_.Groups[1].Value + "/" + $_.Value } |
279 ForEach-Object { if (-not (Test-Path $_)) { Write-Output "BROKEN: $_" } }
280 ```
281 Output should be empty—no broken references.
282
2834. **Hardcoded path check:**
284 ```powershell
285 Select-String -Path "SKILL.md" -Pattern 'C:\\Users\\|/home/|/Users/' |
286 ForEach-Object { Write-Output "HARDCODED: $($_.LineNumber): $($_.Line)" }
287 ```
288 Output should be empty (unless documenting a specific machine path by design).
289
2905. **Reference chain check:** Manually open each file in `references/` and `workflows/` and confirm none link to another reference file. All links must point back to SKILL.md or external URLs only.
291
2926. **Success criteria checklist:**
293 - [ ] Has When to Use AND When NOT to Use sections
294 - [ ] Uses a recognizable pattern (routing, pipeline, linear, safety gate, or task-driven)
295 - [ ] Numbers all phases with entry and exit criteria
296 - [ ] Lists only the tools it actually uses (least privilege)
297 - [ ] Keeps SKILL.md under 500 lines with details split into companion reference and workflow files
298 - [ ] Has no hardcoded paths (uses `{baseDir}`)
299 - [ ] Has no broken file references
300 - [ ] Has no reference chains (all links one hop from SKILL.md)
301 - [ ] Includes a verification step at the end of the workflow
302 - [ ] Has a description that triggers correctly (third-person, specific keywords)
303 - [ ] Includes concrete examples for key instructions
304 - [ ] Explains WHY, not just WHAT, for essential principles
305
306## Reference Index
307
308| Topic | Content | When to use |
309|------|---------|--------------|
310| Workflow patterns | 5 patterns with structural skeletons and examples | Phase 1: before selecting a pattern (table above) |
311| Anti-patterns | 20 anti-patterns with before/after fixes | Phase 5: before reviewing the draft (table above) |
312| Tool assignment | Tool selection matrix, component comparison, subagent guidance | Phase 4: when assigning tools |
313| Progressive disclosure | Content splitting rules, the 500-line rule, sizing guidelines | Phase 3 / Essential Principle 4 |
314| Creation process | 6-phase creation from scope to self-review | Phases 1–6 in this skill |
315| Self-review | Structured checklist for submission readiness | Phase 6 and Verification below |
316
317## Related Skills
318
319- **progressive-disclosure-guide** — Content splitting rules and the 500-line rule
320- **tool-assignment-guide** — Tool selection matrix and subagent guidance
321- **anti-patterns** — Full catalog of 20 anti-patterns with fixes