Claude Code Deep Dive: Skills, Agents, MCP Tools — What They Are and How to Build Them

┌─────────────────────────────────────────────┐
│  Claude Code Session                        │
│                                             │
│  ┌───────────────────────────────────────┐   │
│  │ Orchestrator (main conversation)      │   │
│  │ ├─ Skills (Skill tool)          ✅    │   │
│  │ ├─ MCP Tools                    ✅    │   │
│  │ ├─ Bash, Read, Edit, Grep...   ✅    │   │
│  │ │                                     │   │
│  │ ├─ Sub-agent A (Agent tool)           │   │
│  │ │   ├─ MCP Tools               ✅    │   │
│  │ │   ├─ Bash, Read, Edit...     ✅    │   │
│  │ │   └─ Skills                  ❌    │   │
│  │ │                                     │   │
│  │ └─ Sub-agent B (Agent tool)           │   │
│  │     ├─ MCP Tools               ✅    │   │
│  │     └─ Skills                  ❌    │   │
│  └───────────────────────────────────────┘   │
│                                             │
│  MCP Server: my-app    ◄── shared, all see  │
│  MCP Server: database  ◄── shared, all see  │
└─────────────────────────────────────────────┘

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-app",
  version: "1.0.0"
});

// Define a tool
server.tool(
  "get-users",
  { limit: z.number().default(10) },
  async ({ limit }) => {
    const users = await db.query(
      "SELECT * FROM users LIMIT $1", [limit]
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify(users, null, 2)
      }]
    };
  }
);

// Define a resource
server.resource(
  "schema://database",
  "Database schema for reference",
  async () => ({
    contents: [{
      uri: "schema://database",
      text: await db.getSchema()
    }]
  })
);

const transport = new StdioServerTransport();
await server.connect(transport);

from mcp.server.fastmcp import FastMCP
import json

mcp = FastMCP("my-app")

@mcp.tool()
def get_users(limit: int = 10) -> str:
    """Fetch users from the database."""
    users = db.query("SELECT * FROM users LIMIT %s", (limit,))
    return json.dumps(users)

@mcp.tool()
def create_order(product_id: str, quantity: int) -> str:
    """Create a new order."""
    order = order_service.create(product_id, quantity)
    return f"Order {order.id} created successfully"

mcp.run()

{
  "mcpServers": {
    "my-app": {
      "command": "node",
      "args": ["./mcp-server/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Orchestrator spawns 3 parallel agents:
├─ Agent "researcher"  → calls mcp__db__query     ✅ direct
├─ Agent "analyzer"    → calls mcp__db__aggregate  ✅ direct
└─ Agent "reporter"    → calls mcp__slack__post    ✅ direct

.claude/skills/
└── my-skill/
    ├── SKILL.md          ← The prompt (REQUIRED)
    ├── references/       ← Supporting docs
    │   ├── api-guide.md
    │   └── examples.md
    └── scripts/          ← Helper scripts (optional)
        └── helper.py

# My Skill Name

> Short description of what this skill does and when to use it.

## When to Activate

- When the user asks to [specific action]
- When working with [specific technology]
- When the codebase contains [specific patterns]

## Workflow

1. **Step 1** — Read the relevant files
2. **Step 2** — Analyze the current state
3. **Step 3** — Make changes following the rules below

## Rules

- Always use [specific pattern]
- Never modify [protected files]
- Follow [specific convention]

## References

Load `references/api-guide.md` for API documentation.
Load `references/examples.md` for code examples.

# Code Review Skill

## Workflow

1. Read all changed files via `git diff --name-only HEAD~1`
2. For each file, check:
   - Error handling completeness
   - Security vulnerabilities (OWASP Top 10)
   - Performance anti-patterns
   - Test coverage gaps
3. Output a structured review with severity levels

## Output Format

For each finding:
- **File:** path:line_number
- **Severity:** critical | warning | info
- **Issue:** What's wrong
- **Fix:** Suggested code change

## Rules

- Never auto-fix critical issues — flag them for human review
- Ignore style-only issues (formatting, naming preferences)
- Focus on logic errors, security, and correctness

Orchestrator:
  1. Invoke /docs-seeker → gets API docs    (Skill ✅)
  2. Agent(prompt: "Using these docs: {result}, implement the feature")

Agent(prompt: """
  When you need documentation, search with:
  WebSearch("{library} site:context7.com")
  This replaces the /docs-seeker skill.
""")

Agent({
  subagent_type: "tester",
  prompt: "Run the test suite for src/auth/ and report failures",
  description: "Run auth tests"
})

Planner → Developer → Tester → Reviewer
   │          │          │          │
   plan    implement   verify    approve

Orchestrator spawns simultaneously:
├─ Agent("implement user API")     ← owns src/api/users/*
├─ Agent("implement product API")  ← owns src/api/products/*
└─ Agent("write shared types")     ← owns src/types/*

// Agent A sends to Agent B
SendMessage({
  to: "agent-b-name",
  type: "message",
  content: "Auth module is ready. You can now implement the protected routes."
})