6 分で読める

Patterns and troubleshooting

6 分で読める

残り 10 分

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

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

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).

Be more specific

# Too broad
description: Processes documents

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

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

Verify MCP server is connected
- Claude.ai: Settings > Extensions > [Your Service]
- Should show "Connected" status
Check authentication
- API keys valid and not expired
- Proper permissions/scopes granted
- OAuth tokens refreshed
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
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

Instructions too verbose
- Keep instructions concise
- Use bullet points and numbered lists
- Move detailed reference to separate files
Instructions buried
- Put critical instructions at the top
- Use ## Important or ## Critical headers
- Repeat key points if needed
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.

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

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

Patterns and troubleshooting

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

Pattern 1: Sequential workflow orchestration

Example structure

Key techniques

Pattern 2: Multi-MCP coordination

Example: Design-to-development handoff

Key techniques

Pattern 3: Iterative refinement

Example: Report generation

Key techniques

Pattern 4: Context-aware tool selection

Example: File storage

Key techniques

Pattern 5: Domain-specific intelligence

Example: Financial compliance

Key techniques

Troubleshooting

Skill won't upload

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

Solution

Error: "Invalid frontmatter"

Error: "Invalid skill name"

Skill doesn't trigger

Fix

Quick checklist

Debugging approach

Skill triggers too often

Solutions

MCP connection issues

Checklist

Instructions not followed

Common causes

Large context issues

Causes

Solutions