Skill design feels open-ended until you've built three of them. Then the patterns start repeating. Most working skills sit in one of five recognizable shapes — and most broken skills are using the wrong shape for the problem they're trying to solve.
Here's the catalog, with the symptom that calls for each and the symptom that means you've picked wrong.
The five shapes at a glance
| Shape | Use when | Sign you picked wrong |
|---|---|---|
| Sequential workflow | The user needs a multi-step process executed in a specific order | The steps aren't really ordered — they're just a list |
| Multi-MCP coordination | The workflow spans multiple services with handoffs | One MCP would have been enough |
| Iterative refinement | Output quality improves with passes until a threshold is met | You're iterating for cosmetic reasons; one pass would do |
| Context-aware selection | Same outcome, different tools depending on context | The "context" is just a single if statement |
| Domain-specific intelligence | The skill adds judgment beyond tool access | The judgment is generic, not really domain-specific |
A skill rarely needs more than one shape. If you're stacking three of them in a single SKILL.md, you're probably looking at three skills.
1. Sequential workflow
The default shape. The user describes an outcome ("onboard a new customer"), and the skill encodes the exact order of operations: create account → set up payment → create subscription → send welcome email. Each step has a tool call, parameters, and a dependency on the previous step's output.
What makes it work: explicit step ordering, named dependencies between steps, validation at each stage, rollback instructions when something fails partway through.
When not to use it: if the steps can run in any order, you're imposing order that doesn't exist. The user asks for step 3 first and the skill either refuses or silently runs step 1, when they didn't want that.
2. Multi-MCP coordination
Same shape as sequential, but spans multiple external services. A design-to-development handoff: export from Figma, upload to Drive, create tasks in Linear, post to Slack. The skill's job is to know which service handles which phase and how data flows between them.
What makes it work: clear phase separation, named data handoffs ("the asset URLs from Phase 2 go into the task descriptions in Phase 3"), validation before moving to the next phase, centralized error handling so a Slack outage doesn't roll back the Linear tasks.
When not to use it: if every phase lives in one service, you're not coordinating — you're sequencing. The sequential workflow shape is the right pick; you've over-engineered.
3. Iterative refinement
The output gets better with passes. Generate a draft → validate → identify issues → regenerate the affected sections → re-validate. Loop until the quality threshold is met or the iteration cap is hit.
What makes it work: explicit quality criteria (not "looks good" — "passes the validation script"), a regeneration mechanism that doesn't lose context from the original, a stopping rule that prevents infinite loops.
When not to use it: if you're iterating for cosmetic preference rather than measurable quality, one pass would do. The iteration shape costs real tokens per loop; reserve it for cases where the first output is genuinely insufficient.
4. Context-aware tool selection
Same goal, different path depending on context. File storage is the canonical case: large files go to cloud storage, collaborative docs go to Notion, code files go to GitHub, temporary files stay local. The skill is a decision tree that maps context to tool.
What makes it work: clear decision criteria (file size, file type, intended audience), fallback options when the preferred tool fails or isn't available, transparency about the choice — the user gets told why a file went where.
When not to use it: if the "decision tree" is one if statement, you don't need the shape. Inline the choice into a sequential workflow and move on.
5. Domain-specific intelligence
The skill adds expertise the agent wouldn't have by default — compliance rules, regulatory checks, industry-specific validation. Before processing a payment: check sanctions lists, verify jurisdiction allowances, assess risk, document the compliance decision. The skill embeds domain logic that goes beyond what the tools can express.
What makes it work: domain expertise written into the logic (not just "ask the user if it's compliant"), compliance steps that fire before the action (not as an after-the-fact audit), comprehensive documentation of the decision trail.
When not to use it: if the "domain expertise" is generic best practice (use HTTPS, validate inputs), it isn't domain-specific — it's hygiene. Don't dress it up.
How to pick the right shape
Two questions get you most of the way.
- Is the order load-bearing? If yes, sequential (single-service) or multi-MCP (cross-service). If no, look at shapes 3–5.
- Where does the value come from? From running multiple passes (refinement), from picking the right path (context-aware), or from embedded expertise (domain-specific)?
If you can't answer either, you don't have a skill yet — you have a vague intent. Sketch the user's input and the expected output before writing any frontmatter.
When none of the shapes fit
Two cases worth flagging.
- The skill is mostly a knowledge dump. "Here's everything to know about our API." That's a reference file, not a skill — package it as
references/your-api.mdand load it from a thin sequential or context-aware skill. - The skill is one tool call wrapped in a description. No order, no decision, no judgment. Skip the skill; let the agent call the tool directly.
The five shapes aren't a checklist — they're a diagnostic. If you can't fit your skill into one of them, the skill isn't shaped right yet. The fastest way to make a broken skill work is usually to redraw it as a different shape.