MCP connection issues

2. Be more specific

# Too broad
description: Processes documents

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

3. Clarify scope

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

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 for examples of this pattern.

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