Source: raw/The-Complete-Guide-to-Building-Skill-for-Claude.pdf. Refresh 2026-05-03 with one model-upgrade gotcha from a Reddit post (raw/reddit-1t26xrj.md, r/ClaudeCode by u/jimmytoan).
Five proven patterns for structuring Claude skills, drawn from early adopters and internal teams at Anthropic. Each pattern fits a different type of problem. Choose based on whether your use case is problem-first (“I need to accomplish X”) or tool-first (“I have MCP connected, teach Claude the best workflows”).
Pattern 1: Sequential Workflow Orchestration
Use when: Users need multi-step processes in a specific order.
Structure each step explicitly with dependencies and validation at each stage. Include rollback instructions for failures.
Key techniques:
- Explicit step ordering
- Dependencies between steps
- Validation at each stage
- Rollback instructions for failures
Practical example: Onboarding a new customer — create account, set up payment, create subscription, send welcome email. Each step depends on the previous one completing successfully.
Pattern 2: Multi-MCP Coordination
Use when: Workflows span multiple services (Figma + Drive + Linear + Slack, etc.).
Break the workflow into phases, one per MCP server. Pass data between phases. Validate before moving to the next phase. Centralize error handling.
Key techniques:
- Clear phase separation
- Data passing between MCPs
- Validation before moving to next phase
- Centralized error handling
Practical example: Design-to-development handoff — export from Figma MCP, upload assets to Drive MCP, create tasks in Linear MCP, notify team via Slack MCP.
Pattern 3: Iterative Refinement
Use when: Output quality improves with iteration (reports, documents, creative content).
Generate an initial draft, run a quality check against explicit criteria, address each issue, regenerate affected sections, re-validate, repeat until the quality threshold is met.
Key techniques:
- Explicit quality criteria
- Iterative improvement loops
- Validation scripts (optional — bundle a check script in scripts/)
- Know when to stop iterating
Practical example: Report generation — fetch data, generate draft, check for missing sections and formatting issues, fix issues, re-validate, finalize.
Pattern 4: Context-Aware Tool Selection
Use when: Same outcome, different tools depending on context.
Build a decision tree into the skill. Check file type, size, or other context signals. Route to the appropriate MCP or storage method. Explain the choice to the user.
Key techniques:
- Clear decision criteria
- Fallback options
- Transparency about choices
Practical example: File storage — large files go to cloud storage MCP, collaborative docs go to Notion/Docs MCP, code files go to GitHub MCP, temporary files stay local.
Pattern 5: Domain-Specific Intelligence
Use when: Your skill adds specialized knowledge beyond tool access.
Embed domain expertise directly in the skill instructions — compliance rules, industry standards, best practices. Check rules before taking action, not after. Document everything.
Key techniques:
- Domain expertise embedded in logic
- Compliance/rules checked before action
- Comprehensive documentation
- Clear governance
Practical example: Financial compliance — before processing a payment, check sanctions lists, verify jurisdiction, assess risk level. Only proceed if compliance passes. Log all checks.
Choosing your approach
- Problem-first (“I need to set up a project workspace”) — your skill orchestrates the right MCP calls in the right sequence. Users describe outcomes; the skill handles the tools.
- Tool-first (“I have Notion MCP connected”) — your skill teaches Claude the optimal workflows and best practices. Users have access; the skill provides expertise.
Most skills lean one direction. Knowing which framing fits helps you choose the right pattern.
Troubleshooting common issues
- Skill won’t upload: Check file is exactly
SKILL.md(case-sensitive), YAML has---delimiters, name is kebab-case - Skill doesn’t trigger: Description is too generic or missing trigger phrases. Ask Claude “When would you use the [skill name] skill?” to test
- Triggers too often: Add negative triggers (“Do NOT use for…”) and clarify scope in description
- Instructions not followed: Instructions may be too verbose, buried, or ambiguous. Put critical instructions at the top, use bullet points, be specific not vague
- MCP connection issues: Verify MCP server status, check API keys, test MCP independently without skill
- Large context / slow responses: Keep SKILL.md under 5,000 words, move detailed docs to references/, reduce enabled skills if over 20-50
- Skill degrades after a model upgrade: [Reddit signal — r/ClaudeCode 2026-05-03] Skills tuned on a less-capable model (e.g., Sonnet 4.6) can produce noticeably worse output on a more-capable model (e.g., Opus 4.7) because more capable models interpret instructions rather than follow them literally — a “use short sentences” guideline that worked with judgment on Sonnet became a hard constraint on Opus, producing choppy, unreadable prose. Mitigation: maintain a small golden set of test prompts and re-run them after every model bump before deploying the skill more widely. Source: u/jimmytoan, “Your SKILL.md is likely 3x more expensive than it needs to be” (Reddit thread; anecdotal, not a controlled benchmark).
Key Takeaways
- Five patterns cover most skill use cases: sequential workflow, multi-MCP coordination, iterative refinement, context-aware selection, domain intelligence
- Choose problem-first vs. tool-first framing before picking a pattern
- Every pattern emphasizes validation at each stage and clear error handling
- The iterative refinement pattern is especially powerful for content creation workflows
- Multi-MCP coordination is the pattern most relevant for marketing automation (connecting multiple services into one workflow) — see Marketing Automation Use Cases
- When skills misbehave, the issue is almost always in the description field or instruction clarity, not the pattern choice
Try It
- Pick one of your current multi-step workflows (e.g., creating a campaign across multiple tools)
- Match it to one of the five patterns above
- Use skill-creator: “Help me build a skill using Pattern [N] for [your workflow]”
- Start with one pattern, get it working, then combine patterns as needed
Related
Open Questions
- Can patterns be combined in a single skill (e.g., multi-MCP + iterative refinement)?
- What’s the practical limit on how many MCP phases Pattern 2 can handle before it becomes unreliable?
- Are there patterns specifically optimized for marketing content workflows?