MCP

Model Context Protocol connects Claude to services like Notion, Linear, GitHub. Provides data access in real time and is what Claude CAN do it.

Skills

This the knowledge and teaches claude how to use the connected service effectively. It captures custom workflows and best practices, telling Claude HOW it should do it.

Structure

skills-folder-name/ #must be lowercase separated by hyphens (kebab case))
- SKILL .md #frontmatter and instructions
- scripts/ #optional executable code like Python or Bash
- references/ #optional specialized documentation loaded on-demand (detailed docs)
- assets/ #optional temaplates, fonts, or icons used in output

SKILL .md

# YAML frontmatter (how Claude decides whether to load the skill) and always loads into Claude's system prompt
___
name: your-skill-name
description: What id does. Use when [user asks for specific phrases]
metadata:
author: David Shatsky
version: 1.0.0
___

# Your Skill Name

# Instructions

# Step 1: [First Major Step]

Clear explanation of what happens. Formula = [What it does] + [When to use it] + [Key capabilities]
Example: python scripts/fetch_data.py --project-id PROJECT_ID.
Expected output: [describe what success looks like].

(Add more steps as needed, keeping them specific and actionable)

# Examples

User says:

• "Set up a new marketing campaign".

Actions:

1. Fetch existing campaigns via MCP.

2. Create new campaign with provided parameters.

Result:

• Campaign created with confirmation link.

# Troubleshooting / Common Issues

Error: [Common error message, API error, or MCP connection failure].

Cause: [Why it happens].

Solution: [How to fix, e.g., Verify MCP server is running].

# References (Optional)

Before writing queries, consult references/api-patterns.md for rate limiting guidance and pagination patterns.

Testing/Validation Lifecycle

1. Compare baseline request without skills against with skill. Track tool calls, token consumption, and required clarifying question

2. Ensure the skill only loads at the right times. Test obvious tasks vs unrelated topics to ensure it stays dormant.

3. Verify outputs. Make sure that the API calls succeed, tool sequences complete without user corrections, and edge cases are handled.

Archetype Map

1. Sequential Workflow Orchestration
   use for strict processes like customer onboarding

2. Multi-MCP Coordination
   Cross platform workflows like handoffs from design-to-dev

3. Iterative Refinement
   draft -> check -> refine
   output quality improves using localized validation scripts until threshold is met

4. Context-Aware Selection
   analyzing file size and deciding whether to route to local storage MCP or cloud storage MCP

5. Domain-Specific Intelligence
   embedding specific rules for checking details