.claude/skills/code-review/SKILL.md

name: code-review

description: Use when the user asks for a "code review" or "PR review".

Review Checklist

1. Does this change have tests?

2. Are there SQL injection risks in any query?

3. Is error handling present on all external calls?

4. Can this be done with half the lines?

- Level 1 (always in context): The name + description — ~30 tokens. Claude knows this skill exists.

- Level 2 (loaded on trigger): The body of SKILL.md — only loaded when you ask for a code review.

This means 100 skills cost about as much context as 1 MCP server with 20 tools.

- Code review checklists (your team's standards)

- Deployment runbooks ("check these 5 things before merging")

- Writing style guides ("we use snake_case, no classes, type hints required")

- Commit message formats, PR templates, changelog generators

- Reading GitHub issues (needs API access)

- Querying databases (needs a connection)

- Sending Slack messages (needs webhook/API)

- Anything that requires live data from outside Claude's session

MCP Servers: The Connection Layer

An MCP (Model Context Protocol) server is a running process that exposes tools, resources, and prompts to Claude. It's the bridge between Claude and the outside world.

// .claude/settings.json

{

"mcpServers": {

"github": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-github"]

}

}

}

- GitHub operations (read PRs, create issues, check CI status)

- Database queries (PostgreSQL, SQLite, etc.)

- Browser automation (Playwright for testing, web scraping)

- Internal APIs (your company's REST/GraphQL endpoints)

- Third-party services (Slack, Jira, Notion, Linear)

- Encoding team conventions (use a Skill instead)

- Documenting processes (a Skill is 100x cheaper in tokens)

- Checkpoint-style instructions ("before deploying, verify X")

Side by Side

| | Skills | MCP Servers |

|---|---|---|

| What it is | Markdown files in a folder | A running process (Node/Python) |

| Token cost | ~30-50 tokens per skill | 5,000-50,000 tokens for tool list |

| External access | None | Full (APIs, databases, browsers) |

| Development time | 5-30 minutes | Hours to days |

| Dependencies | Zero | Node.js or Python runtime |

| Sharing | Copy a folder, or publish to AGI Store | Share config JSON + install instructions |

| Can it do X without Y? | Process without capability | Capability without process |

The Real Pattern: Skills Orchestrate, MCP Executes

The most powerful setups combine both. Here's a real workflow that uses Skills for process and MCP for access:

1. [MCP: GitHub] → Fetches the PR diff, commits, and CI status

2. [Skill: Security] → Checks for: exposed secrets, SQL injection, unsafe eval()

3. [Skill: Style] → Verifies: naming conventions, file structure, no console.log

4. [Skill: Testing] → Confirms: new code has tests, coverage didn't drop

5. [MCP: GitHub] → Posts review summary as a PR comment

The Skills define what to check. The MCP server provides the PR to check and where to post results.

How to Choose: Decision Flowchart

I want to extend Claude Code with...

│

├─ A repeatable checklist or process?

│ └─ SKILL. Write a SKILL.md file.

│

├─ Access to GitHub/Jira/Database/Slack?

│ └─ MCP SERVER. Install and configure one.

│

├─ A process that also needs external data?

│ └─ BOTH. Skill for the process, MCP for the data.

│

├─ Something I want to share with my team?

│ ├─ If it's just instructions → Skill (drop a folder)

│ └─ If it needs a running service → MCP + a shared config

│

└─ Not sure?

└─ Start with a Skill. It's free, takes 5 minutes, and has zero token overhead.

If you later need external data, add an MCP server and reference it from the Skill.

Common Mistake: Using MCP When a Skill Would Do

We see this pattern constantly:

> Developer writes a 200-line Python MCP server that... reads a checklist and formats output.