Claude skills, MCP, and knowing which one to use.

I use Claude constantly for writing insights like this, writing code, for incident analysis, for drafting client deliverables. At some point the repeat instructions piling up in every chat become a productivity tax, and you start looking at the tooling Anthropic actually built to solve that. That is where skills and MCP come in, and where most people get confused about which one to reach for.

Most people building Claude automations run into the same wall: they start with skills, realize they need live data, bolt on an MCP server, and then wonder why the whole thing is fragile and they blow through a million tokens in a short period. The answer is not that skills or MCP are wrong. It is that they solve different problems, and conflating them creates a mess that is hard to debug and harder to maintain.

This is the mental model I use when scoping out agentic AI work, both for internal tooling and for client engagements. Skills handle how Claude thinks and executes. MCP handles what Claude can see and touch. Get that separation right from the start and everything else follows cleanly.

The three primitives

Anthropic gives you three distinct tools for extending Claude's capability. Each occupies a different layer of the stack.

These three layers compose, they do not compete. A well-built agentic system will often use all three: projects hold background context, skills define the execution logic, MCP provides live data access. The mistake is treating them as interchangeable.

Skills in depth

A skill is not a prompt. It is a file-system artifact: a folder containing a SKILL.md file and optionally a references/ directory and a scripts/ directory. Drop the folder into ~/.claude/skills/ and Claude discovers it automatically. No configuration file. No registration step.

# Minimal skill
csv-cleaner/
  SKILL.md

# Full skill with references and scripts
incident-reporter/
  SKILL.md
  references/
    severity-guide.md
    escalation-matrix.md
  scripts/
    parse-logs.py
    calculate-mttr.py

The YAML frontmatter block at the top of SKILL.md controls when a skill activates. Claude scans all available skills and scores each description against your prompt. The highest-scoring skill fires. If nothing clears the threshold, Claude responds normally. This means your description is not documentation. It is the activation mechanism, and it needs to be explicit to the point of being almost embarrassingly specific about trigger phrases.

---
name: incident-reporter
description: |
  Generates structured incident reports from raw on-call logs, alert
  data, or freeform incident notes. Use this skill whenever the user
  says "write up the incident", "create a postmortem", "draft the
  incident report", or provides a raw timeline and asks for a
  structured output. Also activates when the user pastes alert
  data and asks for a summary.

  Do NOT use for: general log analysis, SLO reviews, or capacity
  planning tasks — those have separate skills.
---

## Overview
This skill transforms raw incident data into a structured postmortem
following the DURESS framework...

When to add scripts

Plain English instructions handle judgment, formatting, and language tasks cleanly. But some tasks require actual computation: calculating running averages, parsing XML, resizing images in a batch. That is when you add a scripts/ directory.

The division is clean in practice: scripts handle computation, instructions handle judgment. Your SKILL.md tells Claude exactly which script to run, with what arguments, and how to interpret the output. The script does the math. Claude does the writing.

MCP in depth

MCP (Model Context Protocol) is a connectivity layer. It has nothing to do with how Claude executes a task. It is purely about what external systems Claude can interact with during that execution. Think of it as giving Claude a set of tools: a calendar tool, a database query tool, an email send tool. Skills tell Claude what to do; MCP tools give Claude the ability to do it.

MCP servers expose a defined set of tools (list_events, create_task, query_db, send_email) and Claude decides when and how to call them. You write an MCP server once and any agent or skill can use it. That is the key architectural advantage at scale: MCP tools are reusable across skills. Your New Relic MCP server that queries alert data can be used by your incident reporter skill, your SLO review skill, and your capacity planning skill without duplicating a line of code.

Running your own MCP server

MCP servers are lightweight HTTP or stdio processes. You can build one in Python or TypeScript in an afternoon. Each tool you expose follows the same pattern: a name, a description Claude uses to decide when to call it, an input schema, and the implementation.

from mcp.server import Server
from mcp.types import Tool, TextContent
import httpx

app = Server("newrelic-mcp")

@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="query_alerts",
            description="Query open alerts from New Relic for a given service",
            inputSchema={
                "type": "object",
                "properties": {
                    "service_name": {"type": "string"},
                    "severity":    {"type": "string", "enum": ["critical", "warning"]}
                }
            }
        )
    ]

@app.call_tool()
async def call_tool(name, arguments):
    if name == "query_alerts":
        # hit New Relic API, return results
        data = await fetch_newrelic_alerts(**arguments)
        return [TextContent(type="text", text=str(data))]

Skills vs MCP: the honest decision matrix

The question I get most often is: should I build this as a skill or as an MCP server? The answer depends on what the task actually needs.

What this actually costs

This is the part people skip until the bill shows up. The architecture choices you make have a direct token cost, and a bloated MCP setup can burn through budget 10x faster than a clean skill-only workflow for the same task.

Here is a realistic comparison for a single incident report generation, using current API pricing (Haiku 4.5 at $1.00/$5.00 per million tokens):

Same output. 10x the cost. At 50 runs a day on a team, that is the difference between $12.50/month and $103.50/month on Haiku alone. Scale that to Sonnet and the numbers hurt more. The discipline of keeping each layer doing only its job is not just architectural cleanliness, it is budget discipline.

Managing skills at scale

One skill is simple. Ten skills start to conflict. At twenty skills, without deliberate architecture, you will have activation collisions, ambiguous triggers, and skills that fire in the wrong context. This is the multi-skill orchestration problem, and it gets worse the more you build.

Claude's selection mechanism is straightforward: it reads all available skill descriptions, scores each against your request, and activates the highest-scoring match. If two skills have overlapping trigger phrases, the wrong one will sometimes win. If descriptions are too vague, nothing fires. If they are too broad, everything fires.

Three rules for a conflict-free skill library

State management across sessions

Context windows are finite. For long-running projects like a multi-week observability rollout, an ongoing audit, or a book written chapter by chapter, Claude forgets what happened in the previous session. The standard workaround is a context log pattern baked into the skill itself.

## Session continuity

At the start of every session, read context-log.md to understand
what was completed last time, what is pending, and what decisions
were made.

At the end of every session, append a summary to context-log.md
with:
- What was completed this session
- What is blocked and why
- What should happen next
- Any decisions made that affect future sessions

This is the shift handover pattern from incident response. The incoming responder reads the chart, knows exactly what happened, and picks up without losing context. Your skill does the same thing. It reads its own notes from the previous session before it does anything else.

MCP at scale: one server per domain

The equivalent management problem for MCP is different. Instead of activation conflicts, you get tool name collisions, authentication sprawl, and versioning headaches. The cleanest architecture keeps MCP servers scoped tightly.

Common mistakes I keep seeing

These are not theoretical. They are patterns I have run into repeatedly, both in my own builds and in client engagements where someone handed me a broken automation to fix.

How to know if your skill is actually working

This is the part of the docs nobody writes. You drop a SKILL.md into your skills directory, send a message that should trigger it, and Claude responds. But did the skill fire, or did Claude just happen to do something similar on its own? Here is how to tell, and how to iterate without breaking everything.

Verifying activation

The most direct check: ask Claude explicitly. After any response that should have used a skill, ask "which skill did you use for that?" Claude will tell you the skill name if one activated, or tell you no skill fired. Do this every time you write a new skill until you have confidence in the trigger language.

The second signal is output structure. If your skill specifies a precise output format (specific sections, a particular heading structure, code blocks in a defined order) and the response matches it exactly, the skill fired. If the output is Claude's default style for that kind of task, it probably did not.

Iterating safely

Never edit a live skill description and immediately test it in a real workflow. Keep a test-prompts.md file next to each skill with 5-10 example inputs that should trigger it and 3-5 that should not. Run through that list after every description change before you use it in production. Takes two minutes. Saves a lot of confusion later.

When you are tuning a description that keeps misfiring, change one thing at a time. Add one trigger phrase, test. Add one negative boundary, test. If you rewrite the whole description at once and something breaks, you will not know which change caused it.

# incident-reporter — test prompts

## Should activate
- "write up last night's incident"
- "create a postmortem for the payment service outage"
- "draft the incident report, here's the timeline: [...]"
- "we had a p1 this morning, can you structure it up"

## Should NOT activate
- "what's our current SLO burn rate"
- "review this runbook and tell me what's missing"
- "analyze these logs for anomalies"
- "can you summarize what happened in standup"

Turning your existing prompts into skills in 15 minutes

If you have been using Claude for a while, you already have skills. They just live in your chat history as repeated instructions you paste every time. Here is how to extract them properly.

The whole thing should take 15 minutes for a skill you already know well. The investment pays back on the first time a teammate asks "how do you do that so consistently?" and you can just point them at a file.

The environment split that matters

Skills behave differently depending on where they run, and this affects what you can build.

Claude Code is the command-line interface for developers. Skills here run in your project directory under .claude/skills/ or globally at ~/.claude/skills/. They have full access to the file system, bash, and can execute scripts. This is where you build skills that manipulate files, run Python scripts, or interact with your codebase. MCP servers registered here have access to local tools, local credentials, and local processes. This is the environment for serious automation work.

Claude Desktop (CoWork) is the desktop agent for non-developers. Same SKILL.md format, different execution context. Skills here can interact with your screen and applications through the agent's GUI capabilities, but they cannot run arbitrary bash commands. MCP servers in this context tend to be hosted services rather than local processes.

What this looks like end to end

Here is a concrete example from an SRE context. We needed an incident reporter that could pull live alert data, structure it, and output a formatted postmortem draft. Three layers:

The result: type "write up last night's incident" and Claude pulls the alert data via MCP, calculates the timeline via the script, applies the structure from the skill, and outputs a draft postmortem that follows the team's format. No instructions pasted. No data copied. One command.

Where to start

If you are new to this: start with one skill, no MCP. Find the task you type instructions for most often and encode it. Get comfortable with the SKILL.md format and the activation mechanism. Add MCP when you hit the wall where Claude needs data it cannot see in the conversation.

If you are building for a team: map your skill territories before writing a single file. Define the negative boundaries. Set up a shared ~/.claude/skills/ directory in version control. Build your first MCP server scoped to a single external system. Expand from there.

The primitives are simple. The discipline is in knowing which layer solves which problem and not conflating them when you are under pressure to ship.