Agent Skills vs MCP Servers vs Rules — Complete Guide

Introduction

Modern AI coding agents like Claude Code, Codex CLI, and Gemini CLI are powerful out of the box. But their real power comes from customization — teaching them your team's conventions, connecting them to your tools, and automating your workflows.

There are three primary ways to extend an AI coding agent:

1. Agent Skills — Markdown instruction files
2. MCP Servers — API endpoints the agent can call
3. Custom Rules — Simple text constraints

Each serves a different purpose. Choosing the right one (or combining them) can dramatically improve your productivity. This guide breaks down exactly when to use each.

What Are Agent Skills?

Agent Skills are Markdown files that encode reusable workflows for AI agents. They follow a structured format with metadata (name, description, triggers) and instructions (goals, steps, output format).

How They Work

When you invoke a skill (via slash command or natural language), the AI agent reads the Markdown file and follows its instructions. The skill becomes part of the agent's context for that task.

---
name: Deploy Checker
description: Validates deployment readiness
triggers: [/deploy-check]
---

## Steps
1. Run the test suite
2. Check for uncommitted changes
3. Verify environment variables
4. Output a go/no-go report

Strengths

• Zero code required — anyone can write Markdown
• Version controlled — lives in your repo, reviewed in PRs
• Portable — works across different AI agents
• Composable — can reference other skills

Limitations

• No external API access — can't call third-party services directly
• No persistent state — each invocation starts fresh
• Text-only — can't process images or binary data during execution

What Are MCP Servers?

MCP (Model Context Protocol) Servers are running processes that expose tools, resources, and prompts to AI agents via a standardized protocol. Think of them as plugins with an API.

How They Work

An MCP server runs locally or remotely, exposing endpoints that the AI agent can call. The agent discovers available tools at startup and invokes them as needed.

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@your-org/db-mcp-server"],
      "env": { "DATABASE_URL": "postgres://..." }
    }
  }
}

Strengths

• Full API access — connect to databases, APIs, cloud services
• Persistent state — maintain connections and caches
• Rich data types — handle binary data, images, structured responses
• Real-time — stream data and react to events

Limitations

• Requires code — need to implement in TypeScript/Python/etc.
• Runtime dependency — must be running for agent to use
• Configuration overhead — environment variables, auth tokens, setup
• Harder to share — dependency management, security considerations

What Are Custom Rules?

Custom Rules are plain text files that set constraints and conventions for the AI agent. They don't encode workflows — they shape behavior.

How They Work

The AI agent reads rule files at startup and applies them to all interactions. They're always-on context, not on-demand tools.

• Claude Code: CLAUDE.md in project root
• Cursor: .cursorrules in project root
• Codex CLI: AGENTS.md (project-level rules section)

## Rules

- Always use TypeScript strict mode
- Prefer functional components over class components
- Use Tailwind CSS, never inline styles
- Run `npm test` before committing
- Never modify files in the `vendor/` directory

Strengths

• Always active — shapes every interaction automatically
• Simple — just text, no structure required
• Team alignment — enforces conventions across all team members
• Low overhead — no installation, no configuration

Limitations

• No logic — can't encode conditional workflows
• No triggers — always on, can't be invoked selectively
• No tools — can't call APIs or run commands on their own
• Easy to conflict — rules can contradict each other

Feature Comparison

When to Use Which?

Use this decision framework:

Use Agent Skills when you want to...

• Automate a repeatable workflow — code review, deployment checks, test generation
• Share best practices — "here's how our team does X"
• Teach complex multi-step procedures — that would be hard to explain each time
• Enable non-technical users — product managers, designers, writers

Use MCP Servers when you need to...

• Connect to external services — databases, APIs, cloud platforms
• Process non-text data — images, binary files, structured data
• Maintain persistent connections — database pools, WebSocket streams
• React in real-time — monitoring, notifications, live data

Use Custom Rules when you want to...

• Enforce coding standards — style guides, naming conventions
• Set boundaries — "never modify production configs"
• Provide project context — architecture decisions, tech stack info
• Align team behavior — ensure consistency across developers

Can They Work Together?

Absolutely — and this is where the real power lies.

Example: Full-Stack Deploy Workflow

1. Custom Rules (CLAUDE.md):

   - Our staging server is at staging.example.com
   - Always run lint before deploying
   - Use semantic versioning
   

2. MCP Server (deployment tools):

   { "deploy": { "command": "npx deploy-mcp-server" } }
   

   
   Exposes: deploy_to_staging(), check_deployment_status(), rollback()
3. Agent Skill (deploy workflow):

   ## Steps
   1. Run lint and tests (respect project rules)
   2. Bump version (semantic, per rules)
   3. Call deploy_to_staging() (MCP tool)
   4. Wait and check_deployment_status()
   5. If failed, call rollback()
   

The skill orchestrates the workflow, calling MCP tools for actions and respecting rules for conventions. Each layer does what it's best at.

The "Right" Combination

Getting Started

Ready to try each approach? Here's where to start:

1. Agent Skills: Browse the Skills collection on TokRepo — install one in 10 seconds:

   npx tokrepo install code-review-skill
   

2. MCP Servers: Check the MCP Servers collection — configure pre-built servers for your stack
3. Custom Rules: Start with a simple CLAUDE.md or .cursorrules file in your project root

FAQ

Can I convert a skill into an MCP server?

You generally don't need to. Skills and MCP servers serve different purposes. If your skill needs external API access, pair it with an MCP server rather than rewriting it.

Are skills slower than MCP servers?

Skills add context to the agent's prompt, which may slightly increase processing time. MCP server calls are direct function invocations. In practice, the difference is negligible — the AI's thinking time dominates.

Can I use all three in the same project?

Yes, and it's recommended. Most mature projects have:

• 5-10 custom rules in CLAUDE.md
• 2-5 agent skills in .claude/commands/
• 1-3 MCP servers for external integrations

Where can I find pre-built skills and MCP servers?

TokRepo has 500+ open-source agent skills, MCP servers, prompts, and workflows. Search, install, and contribute from the command line:

npx tokrepo search "your use case"