Patterns and troubleshooting

These patterns emerged from skills created by early adopters and internal teams. They represent common approaches we've seen work well, not prescriptive templates.

Choosing your approach: problem-first vs. tool-first

Think of it like Home Depot. You might walk in with a problem - "I need to fix a kitchen cabinet" - and an employee points you to the right tools. Or you might pick out a new drill and ask how to use it for your specific job.

Skills work the same way:

• 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 your use case helps you choose the right pattern below.

Pattern 1: Sequential workflow orchestration

Use when: Your users need multi-step processes in a specific order.

Example structure

## Workflow: Onboard New Customer

### Step 1: Create Account
Call MCP tool: `create_customer`
Parameters: name, email, company

### Step 2: Setup Payment
Call MCP tool: `setup_payment_method`
Wait for: payment method verification

### Step 3: Create Subscription
Call MCP tool: `create_subscription`
Parameters: plan_id, customer_id (from Step 1)

### Step 4: Send Welcome Email
Call MCP tool: `send_email`
Template: welcome_email_template

Key techniques

• Explicit step ordering
• Dependencies between steps
• Validation at each stage
• Rollback instructions for failures

Pattern 2: Multi-MCP coordination

Use when: Workflows span multiple services.

Example: Design-to-development handoff

### Phase 1: Design Export (Figma MCP)
1. Export design assets from Figma
2. Generate design specifications
3. Create asset manifest

### Phase 2: Asset Storage (Drive MCP)
1. Create project folder in Drive
2. Upload all assets
3. Generate shareable links

### Phase 3: Task Creation (Linear MCP)
1. Create development tasks
2. Attach asset links to tasks
3. Assign to engineering team

### Phase 4: Notification (Slack MCP)
1. Post handoff summary to #engineering
2. Include asset links and task references

Key techniques

• Clear phase separation
• Data passing between MCPs
• Validation before moving to next phase
• Centralized error handling

Pattern 3: Iterative refinement

Use when: Output quality improves with iteration.

Example: Report generation

## Iterative Report Creation

### Initial Draft
1. Fetch data via MCP
2. Generate first draft report
3. Save to temporary file

### Quality Check
1. Run validation script: `scripts/check_report.py`
2. Identify issues:
   - Missing sections
   - Inconsistent formatting
   - Data validation errors

### Refinement Loop
1. Address each identified issue
2. Regenerate affected sections
3. Re-validate
4. Repeat until quality threshold met

### Finalization
1. Apply final formatting
2. Generate summary
3. Save final version

Key techniques

• Explicit quality criteria
• Iterative improvement
• Validation scripts
• Know when to stop iterating

Pattern 4: Context-aware tool selection

Use when: Same outcome, different tools depending on context.

Example: File storage

## Smart File Storage

### Decision Tree
1. Check file type and size
2. Determine best storage location:
   - Large files (>10MB): Use cloud storage MCP
   - Collaborative docs: Use Notion/Docs MCP
   - Code files: Use GitHub MCP
   - Temporary files: Use local storage

### Execute Storage
Based on decision:
- Call appropriate MCP tool
- Apply service-specific metadata
- Generate access link

### Provide Context to User
Explain why that storage was chosen

Key techniques

• Clear decision criteria
• Fallback options
• Transparency about choices

Pattern 5: Domain-specific intelligence

Use when: Your skill adds specialized knowledge beyond tool access.

Example: Financial compliance

## Payment Processing with Compliance

### Before Processing (Compliance Check)
1. Fetch transaction details via MCP
2. Apply compliance rules:
   - Check sanctions lists
   - Verify jurisdiction allowances
   - Assess risk level
3. Document compliance decision

### Processing
IF compliance passed:
  - Call payment processing MCP tool
  - Apply appropriate fraud checks
  - Process transaction
ELSE:
  - Flag for review
  - Create compliance case

### Audit Trail
- Log all compliance checks
- Record processing decisions
- Generate audit report

Key techniques

• Domain expertise embedded in logic
• Compliance before action
• Comprehensive documentation
• Clear governance

Troubleshooting

Skill won't upload

Error: "Could not find SKILL.md in uploaded folder"

Cause: File not named exactly SKILL.md

Solution

• Rename to SKILL.md (case-sensitive)
• Verify with: ls -la should show SKILL.md

Error: "Invalid frontmatter"

Cause: YAML formatting issue

Common mistakes:

# Wrong - missing delimiters
name: my-skill
description: Does things

# Wrong - unclosed quotes
name: my-skill
description: "Does things

# Correct
---
name: my-skill
description: Does things
---

Error: "Invalid skill name"

Cause: Name has spaces or capitals

# Wrong
name: My Cool Skill

# Correct
name: my-cool-skill

Skill doesn't trigger

Symptom: Skill never loads automatically

Fix

Revise your description field. See The Description Field for good/bad examples.

Quick checklist

• Is it too generic? ("Helps with projects" won't work)
• Does it include trigger phrases users would actually say?
• Does it mention relevant file types if applicable?

Debugging approach

Ask Claude: "When would you use the [skill name] skill?" Claude will quote the description back. Adjust based on what's missing.

Skill triggers too often

Symptom: Skill loads for unrelated queries

Solutions

1. Add negative triggers

description: Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration (use data-viz skill instead).

1. Be more specific

# Too broad
description: Processes documents

# More specific
description: Processes PDF legal documents for contract review

1. Clarify scope

description: PayFlow payment processing for e-commerce. Use specifically for online payment workflows, not for general financial queries.

MCP connection issues

Symptom: Skill loads but MCP calls fail

Checklist

1. Verify MCP server is connected
   • Claude.ai: Settings > Extensions > [Your Service]
   • Should show "Connected" status
2. Check authentication
   • API keys valid and not expired
   • Proper permissions/scopes granted
   • OAuth tokens refreshed
3. Test MCP independently
   • Ask Claude to call MCP directly (without skill)
   • "Use [Service] MCP to fetch my projects"
   • If this fails, issue is MCP not skill
4. Verify tool names
   • Skill references correct MCP tool names
   • Check MCP server documentation
   • Tool names are case-sensitive

Instructions not followed

Symptom: Skill loads but Claude doesn't follow instructions

Common causes

1. Instructions too verbose
   • Keep instructions concise
   • Use bullet points and numbered lists
   • Move detailed reference to separate files
2. Instructions buried
   • Put critical instructions at the top
   • Use ## Important or ## Critical headers
   • Repeat key points if needed
3. Ambiguous language

# Bad
Make sure to validate things properly

# Good
CRITICAL: Before calling create_project, verify:
- Project name is non-empty
- At least one team member assigned
- Start date is not in the past

Advanced technique: For critical validations, consider bundling a script that performs the checks programmatically rather than relying on language instructions. Code is deterministic; language interpretation isn't. See the Office skills (opens in new tab) for examples of this pattern.

1. Model "laziness" Add explicit encouragement:

## Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

Note: Adding this to user prompts is more effective than in SKILL.md

Large context issues

Symptom: Skill seems slow or responses degraded

Causes

• Skill content too large
• Too many skills enabled simultaneously
• All content loaded instead of progressive disclosure

Solutions

1. Optimize SKILL.md size
   • Move detailed docs to references/
   • Link to references instead of inline
   • Keep SKILL.md under 5,000 words
2. Reduce enabled skills
   • Evaluate if you have more than 20 - 50 skills enabled simultaneously
   • Recommend selective enablement
   • Consider skill "packs" for related capabilities