AI Skills vs MCP:
Workflow Layer vs Tool Layer

The Fundamental Distinction

Before diving into syntax, get the mental model right. MCP is infrastructure — it's a protocol that lets an AI agent connect to external tools, APIs, and data sources. Skills are behavior — they're reusable workflow definitions that tell the agent how to accomplish a class of tasks. MCP answers "what can you reach?" Skills answer "how do you work?"

A good analogy: MCP is like a USB port standard — it defines how devices connect. Skills are like macros or scripts — they encode a sequence of operations into a reusable unit. You need the ports to be able to plug anything in; you write the macros to stop repeating yourself.

What Are Skills, Exactly?

In the Claude Code and Claude Agent ecosystem, a Skill is a named, reusable workflow that can be triggered by a slash command. Skills live in a project's CLAUDE.md file (or a global ~/.claude/CLAUDE.md for cross-project skills) and are loaded automatically when an agent session starts in that directory.

Think of Skills as the difference between raw capability and packaged expertise. An agent with access to bash, file read/write, and git tools has raw capability. A "deploy" Skill that runs tests, bumps the version, commits, and pushes with the right message format — that's packaged expertise. The agent knows the steps; you don't have to spell them out every time.

Skills are also documentation. A well-written CLAUDE.md is a contract between the team and the AI: here is how we do things here, here are the patterns we use, here are the commands that matter. New team members and new agent sessions both benefit.

Creating Skills in CLAUDE.md

A Skill definition in CLAUDE.md uses a markdown header starting with a slash, followed by a description of what the agent should do when that command is invoked. The format is intentionally human-readable — it's prose, not code.

# CLAUDE.md — project root

## /review
Review the staged changes for correctness, security issues, and style
consistency with the existing codebase. Output a bulleted list of
findings. Flag anything that looks like a security vulnerability first,
then logic issues, then style. Be concise — one line per finding.

## /deploy
Deploy the current branch to staging:
1. Run `npm test` — abort if tests fail
2. Run `npm run build`
3. Commit any build artifacts
4. Push to origin
5. Notify in Slack #deployments channel via the Slack MCP tool
6. Report the deploy URL

## /sync-docs
Update the API documentation to match the current source code.
Read all TypeScript files in src/, extract exported functions with
their JSDoc comments, and regenerate docs/api.md. Preserve the
existing intro section at the top of docs/api.md.

Skills can reference other skills, call MCP tools by name, run shell commands, read files, and chain multiple operations. The agent interprets the skill description using its full reasoning capability — you're writing intent, not imperative code.

A Real CLAUDE.md Structure

A production CLAUDE.md typically has three sections: project context (what this codebase is), development conventions (how we write code here), and skills (commands the agent should understand). Here's a realistic example:

# CLAUDE.md

## Project
This is a TypeScript/Node.js API serving a fintech SaaS product.
The stack: Express, Prisma ORM, PostgreSQL, Redis for caching.
Deployment: Kubernetes on GKE. CI: GitHub Actions.

## Conventions
- All database queries go through the repository layer in src/repos/
- Never use raw SQL — always Prisma
- Error types live in src/errors/; use them, don't invent new strings
- All routes must have integration tests in tests/integration/
- Commit format: <type>(<scope>): <subject> — no period at end
- Types must be explicit — no implicit any

## /ship <description>
Prepare the current work for review:
1. Run `npx tsc --noEmit` — fix any type errors first
2. Run `npm test` — fix failing tests
3. Run `npm run lint -- --fix`
4. Stage all changes except .env files
5. Create a commit with the provided description following our format
6. Push to origin on the current branch
7. Create a GitHub PR targeting main with a summary of the changes

## /add-endpoint <name>
Add a new REST endpoint following our conventions:
- Create route file in src/routes/<name>.ts
- Create repository in src/repos/<name>Repo.ts
- Add integration test in tests/integration/<name>.test.ts
- Register the route in src/app.ts
- Export types from src/types/<name>.ts
Use the existing user endpoint (src/routes/users.ts) as a template.

## /audit-security
Perform a security review of the codebase:
1. Check for any raw SQL or unsanitized inputs
2. Check all auth middleware is applied to protected routes
3. Look for secrets hardcoded anywhere (not in env vars)
4. Check CORS configuration in src/app.ts
5. Verify rate limiting on authentication endpoints
6. Report findings with file:line references

Invoking Skills

Once defined in CLAUDE.md, skills are invoked with the slash syntax directly in a conversation or Claude Code session. The agent resolves the command, loads the skill definition, and executes it with any provided arguments.

# In a Claude Code session:

/ship "feat(auth): add OAuth2 PKCE support"

/add-endpoint payments

/review

/audit-security

Skills accept arguments naturally — the agent understands that the text after the command name is the argument, and uses it as context within the skill. You don't define formal parameter schemas; the model interprets intent.

Skills Calling MCP Tools

The real power comes when Skills orchestrate MCP tools as steps. An MCP server might expose a "send_slack_message" tool, a "create_github_issue" tool, and a "query_database" tool. A Skill can call all three in sequence as part of a larger workflow.

## /incident-response <service> <severity>
Handle a production incident for the given service:
1. Use the GitHub MCP tool to check for recent PRs merged to <service>
2. Use the database MCP tool to query error_logs for the last 30 minutes
3. Use the Slack MCP tool to post an incident thread in #incidents:
   - Service name, severity, timestamp
   - Recent deploys (from step 1)
   - Error summary (from step 2)
   - Your initial hypothesis
4. Create a GitHub issue via the GitHub MCP tool titled
   "[INCIDENT] <service> - <date>" with full details
5. Assign the issue to the on-call person from the Pagerduty MCP tool

This is a Skill that coordinates four different MCP servers (GitHub, database, Slack, PagerDuty) into a single workflow. Without Skills, you'd either call each tool manually or write a script. With Skills, the agent understands the intent and executes the sequence with full context.

Scope: Project vs Global vs Agent Skills

Skills can live at different scopes. A project CLAUDE.md in the repository root applies only to that project. A global CLAUDE.md at ~/.claude/CLAUDE.md applies to all Claude Code sessions. When both exist, they're merged — project skills take precedence for name conflicts.

For autonomous agents built with the Claude Agent SDK, Skills can also be provided programmatically at session initialization. This lets you dynamically compose skill sets based on the task context — a customer support agent gets different skills than a code review agent, even though both run on the same underlying model.

// Agent SDK — programmatic skill injection
const agent = new ClaudeAgent({
  systemPrompt: baseSystemPrompt,
  skills: [
    {
      name: 'review',
      description: 'Review code changes for correctness and security',
      instructions: reviewSkillInstructions,
    },
    {
      name: 'deploy',
      description: 'Deploy the current branch to staging',
      instructions: deploySkillInstructions,
    }
  ],
  mcpServers: [githubMCP, slackMCP, dbMCP],
});

MCP vs Skills: When to Use Which

Now that you understand both, the decision tree is straightforward:

A Complete Example: Both Together

Here's how a production setup combines MCP and Skills into a cohesive developer experience. The MCP layer provides tool access; the Skills layer provides workflow shortcuts.

# claude_desktop_config.json — MCP servers
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "..." }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "POSTGRES_URL": "postgresql://..." }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": { "SLACK_BOT_TOKEN": "xoxb-..." }
    }
  }
}

# CLAUDE.md — Skills that use those MCP tools

## /pr-review <pr-number>
Review a pull request thoroughly:
1. Use GitHub MCP to fetch PR #<pr-number> diff and description
2. Use GitHub MCP to get the PR's CI check results
3. Use postgres MCP to check if any changed schema files need migrations
4. Review: correctness, security, test coverage, naming, performance
5. Post a review comment via GitHub MCP with findings grouped by severity
6. If critical issues found, request changes; otherwise approve

## /weekly-report
Generate this week's engineering report:
1. Use GitHub MCP to list PRs merged this week
2. Use postgres MCP to query feature_flags for any that shipped
3. Use postgres MCP to check error_rate from monitoring table (last 7d)
4. Use Slack MCP to post a formatted summary to #eng-updates
   Format: ## Week of <date> / Shipped / Metrics / Next week

Key Takeaways

MCP and Skills are complementary, not competing. MCP is a protocol standard that expands the agent's reach — it solves the connectivity problem. Skills are behavior definitions that expand the agent's repertoire — they solve the repetition problem. Use MCP to connect to the tools your team already uses. Use Skills to encode how your team uses them.

The best AI-augmented workflows use both: a curated set of MCP servers that give the agent access to the systems that matter, combined with a CLAUDE.md that teaches the agent the workflows that make your team productive. The result is an AI collaborator that understands your stack and knows how to work within it — not a general-purpose assistant that needs to be re-taught every session.