Agent Skills 101: Tools vs MCP vs Skills

If you've built agents in the past year, you've hit the same wall: the model is smart, but the system around it is fragile.

One integration per tool. One prompt per workflow. Context pasted into chat until things break.

This guide breaks down the three primitives that make agents actually work: Tools, MCP, and Skills. By the end, you'll know exactly when to use each one, and how they fit together.

If you're brand new to Claude Code itself, start with The Ultimate Beginner's Guide to Claude Code and then come back here for the deeper tools/MCP/skills architecture.

TL;DR: The Three Primitives

The key insight: Tools do actions. MCP provides access. Skills encode how to do the job right—and because they're files the agent can read and write, they're self-improving.

What Are Tools?

A tool is a single operation the agent can execute. Think "one step," not "a workflow."

Examples of Tools

• read_file — fetch contents of a file
• create_jira_ticket — create a ticket with given parameters
• run_bash_command — execute a shell command
• search_codebase — find files matching a pattern
• send_slack_message — post to a channel

What Tools Are Good At

Precision: One input → one output. Easy to test and debug.

Control: You know exactly what happened. No ambiguity.

Composability: Tools can be chained. But you still need to define the chain.

Where Tools Break Down

Tools don't encode how to do the job end-to-end. If you rely on tools + prompts alone:

• Sequencing varies ("sometimes it summarizes first, sometimes writes first")
• No definition of done ("is this actually complete?")
• Instructions repeat ("use our format, not that format" — every single time)

Tools answer: "What can I do?"

They don't answer: "What should I do, in what order, with what quality bar?"

What Is MCP (Model Context Protocol)?

MCP is an open protocol introduced by Anthropic in November 2024. It standardizes how AI applications connect to external systems.

The problem it solves: Without MCP, every integration is a custom one-off. Connect Claude to Slack? Custom code. Connect to GitHub? Different custom code. Connect to your database? Yet another integration.

MCP defines a consistent client/server protocol so you build the integration once, and any MCP-compatible AI can use it.

How MCP Works (Technical)

MCP uses JSON-RPC 2.0 for message encoding. All communication happens through three message types:

Request:      { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }
Response:     { "jsonrpc": "2.0", "id": 1, "result": { "tools": [...] } }
Notification: { "jsonrpc": "2.0", "method": "progress", "params": { "percent": 50 } }

MCP Architecture

• Host: The AI application (Claude Desktop, your app)
• Client: Connector within the host that talks to one server
• Server: Service exposing tools, resources, or prompts

Transport Options

1. stdio (Local)

Client spawns server as subprocess. Messages flow through stdin/stdout.

# Server reads from stdin, writes to stdout
[Client] → stdin → [Server Process] → stdout → [Client]

Best for: Local integrations, single-client scenarios, CLI tools.

2. Streamable HTTP (Remote)

Server runs independently. Clients connect via HTTP POST.

curl -X POST https://mcp-server.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: abc123" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", ...}'

Best for: Remote servers, multi-client scenarios, team deployments.

What MCP Servers Expose

• Resources: Data the AI can read (files, database records, API responses)
• Tools: Actions the AI can execute (create ticket, send message, run query)
• Prompts: Pre-built templates for common workflows

Where MCP Stops

MCP gives you access, not method.

It tells you: "Here's how to connect to Slack and what you can do there."

It doesn't tell you: "When writing a status update, pull from these three channels, summarize in this format, and get approval before posting."

That's what Skills are for.

For a step-by-step walkthrough of using MCP tools inside Claude Code, see Section 6: MCP Tools in the Claude Code Beginner's Guide.

What Are Skills?

Skills are reusable workflows that bundle procedural knowledge and assets. They tell the agent how to do a job consistently.

Anthropic's analogy: Building a skill is like assembling an onboarding guide for a new hire. You're capturing procedural knowledge so the agent doesn't reinvent the process every time.

Skill = Method + Resources + Checks

A useful mental model:

Why Skills Don't Bloat Context

Progressive disclosure: Skills use a three-level loading model.

The agent starts with just the description. Full instructions load only when the skill activates. Resource files load only when referenced.

This means you can package extensive institutional knowledge (templates, examples, playbooks) without paying the context cost until it's actually needed.

Pre-Built Skills from Anthropic

Anthropic ships pre-built Agent Skills for common document workflows:

These run in a code execution environment with filesystem access. They're the difference between the LLM returning "here's what your slides should say" and actually producing a .pptx file you can open.

Skills in Claude Code

Claude Code has its own skill system that's filesystem-based and project-local.

If you want a higher-level tour of skills inside the product before diving into directory structure, check out Section 7: Skills in the Claude Code Beginner's Guide.

Skill Directory Structure

SKILL.md Format

---
name: code-review
description: Reviews code for security issues and best practices. Use when reviewing PRs or commits.
allowed-tools: Read, Grep, Glob
---

# Code Review

When reviewing code:

1. **Security scan**: Check for injection vulnerabilities, exposed secrets, unsafe deserialization
2. **Style check**: Verify naming conventions, file organization, comment quality
3. **Logic review**: Trace data flow, identify edge cases, check error handling
4. **Output format**: Use the template in review-template.md

## Common issues to flag
- SQL queries built with string concatenation
- User input passed directly to shell commands
- Missing input validation on API endpoints
- Hardcoded credentials or API keys

Frontmatter Options

Invocation Modes

Default: User invokes with /skill-name, Claude auto-invokes when relevant.

Manual only (disable-model-invocation: true): User must type /skill-name. Claude won't auto-trigger.

Claude only (user-invocable: false): Claude auto-invokes when relevant. Not shown in menu.

Dynamic Content

Skills support variable substitution:

---
name: session-logger
---

Log activity to: logs/${CLAUDE_SESSION_ID}.log

User request: $ARGUMENTS

And shell command injection (output replaces placeholder):

---
name: pr-summary
---

## PR Context
Diff: !`gh pr diff`
Comments: !`gh pr view --comments`

Summarize this PR...

Real-World Use Cases

These examples pair well with the chat modes and scope-plan-execute workflow described in Working With Claude Code and the Chat Modes section.

Use Case 1: Automated Code Review

Without skills: Every code review is different. Sometimes the agent checks security, sometimes style, sometimes neither. Output format varies.

With skills:

---
name: security-review
description: Security-focused code review. Use when reviewing PRs touching auth, payments, or user data.
allowed-tools: Read, Grep, Glob
---

# Security Review

## Checklist
1. [ ] No SQL injection (parameterized queries only)
2. [ ] No command injection (no shell calls with user input)
3. [ ] No exposed secrets (check for hardcoded keys)
4. [ ] Input validation on all external data
5. [ ] Proper authentication checks

## Output format
Use severity levels: CRITICAL, HIGH, MEDIUM, LOW

For each finding:
- File and line number
- Description of issue
- Suggested fix

Result: Every security review follows the same checklist. Output is consistent. Nothing gets missed.

Use Case 2: Meeting Notes → Action Items

The problem: Converting meeting transcripts to action items is tedious and inconsistent.

The skill:

---
name: meeting-processor
description: Convert meeting notes to decisions and action items. Use after meetings.
---

# Meeting Processor

## Steps
1. Extract all decisions made (statements of agreement or conclusion)
2. Extract all action items (tasks assigned to people)
3. Identify open questions (unresolved discussions)
4. Format using action-template.md

## Action item format
Each action item MUST have:
- Clear description (what, not how)
- Owner (single person responsible)
- Due date (if mentioned)

## Quality check
- Every action item has an owner
- No vague items ("follow up on X" → "John to send X proposal to team by Friday")

Use Case 3: Documentation from Code

The skill:

---
name: api-docs
description: Generate API documentation from code. Use when documenting endpoints.
allowed-tools: Read, Grep, Glob
---

# API Documentation Generator

## Process
1. Find all route definitions (Grep for route patterns)
2. For each endpoint, extract:
   - HTTP method and path
   - Request parameters and body schema
   - Response format
   - Authentication requirements
3. Generate markdown using api-doc-template.md

## Include for each endpoint
- Description (what it does, not how)
- Request example (curl command)
- Response example (actual JSON)
- Error cases (4xx/5xx responses)

How Tools, MCP, and Skills Work Together

Example flow:

1. Skill triggers: User asks to "create a weekly status update"
2. Skill loads: Instructions say "pull from #engineering, #product, summarize blockers"
3. MCP connects: Slack MCP server provides access to channels
4. Tools execute: read_channel, search_messages, post_message
5. Skill validates: Check output matches template, has all required sections

Looking Ahead

As skills mature, the boundary between skills and tools will blur. Skills live on the filesystem and can contain executable code—meaning they can perform the same actions tools do, with two key advantages: agents can read skills to understand them, and write to them to self-improve.

The likely trajectory: tools and MCP become thin primitives (read/write, fetch, search), while skills absorb the domain-specific logic.

When to Use What

Use Tools When:

• You need a single, discrete operation
• The action is self-contained (no workflow)
• You're building blocks for higher-level automation

Use MCP When:

• You need to connect to external systems (Slack, GitHub, databases)
• You want integrations that work across AI platforms
• You're building server-based infrastructure

Use Skills When:

• You need consistent, repeatable results
• The task requires multiple steps in a specific order
• You want to capture institutional knowledge
• Output quality matters (templates, checks, examples)

Decision Tree

Common Mistakes

Mistake 1: Using Prompts Instead of Skills

Problem: Pasting the same instructions into every conversation.

Solution: Package it as a skill. Write once, use consistently.

Mistake 2: Stuffing Everything into MCP

Problem: Building complex workflows into MCP servers.

Solution: MCP handles access. Skills handle workflow. Keep them separate.

Mistake 3: No Definition of Done

Problem: Agent produces output, but you don't know if it's complete.

Solution: Add checks to your skill. "Every action item must have an owner."

Mistake 4: Ignoring Progressive Disclosure

Problem: Loading all context upfront, blowing up the context window.

Solution: Use the three-level model. Metadata always. Instructions on trigger. Resources on demand.

Security Considerations

MCP Security

• Validate Origin header on HTTP transports (prevent DNS rebinding)
• Bind to localhost only for local servers (not 0.0.0.0)
• Require explicit user consent for tool invocation
• Implement proper authentication for remote servers

Skill Security

• Use allowed-tools to restrict what a skill can do
• Set disable-model-invocation: true for sensitive operations
• Audit skills from external sources before use
• Skills can include executable code—treat them like dependencies

Quick Reference

MCP Message Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_code",
    "arguments": { "query": "authentication" }
  }
}

Skill File Structure

.claude/skills/my-skill/
├── SKILL.md          # Instructions (required)
├── template.md       # Output template
├── examples/         # Example outputs
└── scripts/          # Validation scripts

Skill Frontmatter

---
name: skill-name
description: When to use this skill
allowed-tools: Read, Grep, Glob
disable-model-invocation: false
user-invocable: true
---

Further Reading

• MCP Specification — Full protocol documentation
• Claude Code Skills Docs — Official skill documentation
• Anthropic Skills Repository — Pre-built skills and examples
• MCP GitHub — Protocol implementation and servers

Frequently Asked Questions