The Agent Toolkit: AGENTS.md vs. MCP vs. Skills vs. Subagents

TL;DR

• Four tools, four jobs. AGENTS.md = project context. MCP = external connections. Agent Skills = reusable procedures. Subagents = isolated specialists.
• They're layers, not competitors. Each solves a different problem. The real power comes from combining them.
• Start small. You don't need all four on day one. Pick one, learn it, add the next when you feel the pain it solves.

You've read the individual lessons. You know what AGENTS.md does. You know what MCP is. You've seen Agent Skills and Subagents. Now you're staring at a real task—debugging a production issue, automating a data pipeline, setting up a new repo—and the question hits: Which one do I actually need here?

The answer, annoyingly, is often "more than one." These tools aren't competing standards. They're four layers of the same stack, each solving a different problem. This lesson gives you the decision framework to pick the right tool (or combo) for any task—without overthinking it.

The Four Tools at a Glance

The "aha" here: These four tools map to four questions your agent needs answered: What's this project? (AGENTS.md) → What can I access? (MCP) → How should I do this? (Skills) → Where should I do it? (Subagents). When all four are answered, your agent stops guessing and starts executing.

What Each Layer Solves

AGENTS.md — Project Context

Your agent clones a repo and needs to know: What package manager? What test command? What PR title format? AGENTS.md answers these questions once, for every agent, every session. It's the always-on project context layer.

Solves: "The agent keeps trying npm install but we use pnpm."

MCP — External Access

Your agent needs to query a database, create a GitHub issue, or send a Slack message. MCP servers provide standardized connections to external systems. Resources for reading, Tools for actions, Prompts for workflows.

Solves: "I keep copy-pasting database results into the chat."

Agent Skills — Reusable Procedures

Your agent knows what tools are available but doesn't know when or how to use them well. A skill packages that procedural knowledge: "When the user asks about data quality, first check the schema, then run these queries, then summarize."

Solves: "The agent has access to our database but doesn't know our team's analysis workflow."

Subagents — Execution Isolation

Your agent runs a test suite and dumps 500 lines of output into your conversation. Or you want a database query agent that can never write data. Subagents provide isolated execution with scoped tools and permissions.

Solves: "Test output is drowning my context window" and "I need a read-only agent."

How They Work Together

These aren't standalone tools—they're layers of a stack. Here's how they connect in a real workflow.

The Stack

┌─────────────────────────────────┐
│  Subagents (execution layer)    │  WHERE the work happens
│  Isolated context, scoped tools │
├─────────────────────────────────┤
│  Agent Skills (knowledge layer) │  HOW the work is done
│  Procedures, checklists, domain │
├─────────────────────────────────┤
│  MCP (capability layer)         │  WHAT the agent can access
│  Databases, APIs, services      │
├─────────────────────────────────┤
│  AGENTS.md (context layer)      │  WHERE the agent is working
│  Project setup, conventions     │
└─────────────────────────────────┘

Walkthrough: Debugging a Production Issue

Here's how all four layers combine for a single task: "The payments API is returning 500 errors in production."

1. AGENTS.md tells the agent: "This is a Node.js monorepo. Run pnpm install to set up. Tests are pnpm test --filter payments. Logs are in /var/log/payments/."

2. MCP servers give the agent access: the file system server reads log files, the GitHub server searches recent commits, the Slack server can post to #incidents.

3. A "debug-diagnostics" skill tells the agent how to investigate: "When a service returns 500s: (1) check recent deploys via git log, (2) read error logs, (3) look for recent schema changes, (4) report root cause with a fix suggestion."

4. A subagent runs the investigation in isolation—reading hundreds of log lines, searching dozens of files—and returns a clean summary: "Root cause: migration in commit abc123 added a NOT NULL column without a default. Fix: add a default value or backfill."

Your main conversation stays clean. The agent followed a proven procedure. External systems were queried directly. The project's specific commands were used correctly.

When to Use Which — Decision Framework

Start with one question: What's the actual problem?

The Quick Decision Tree

Ask these questions in order:

1. Is this about this specific project's setup or conventions? → AGENTS.md.
2. Does the agent need to access an external system? → MCP server.
3. Does the agent need to follow a procedure (and that procedure is reusable)? → Agent Skill.
4. Should the work happen in isolation (noisy output, restricted permissions)? → Subagent.

If the answer is "yes" to multiple questions—which is common—use multiple tools. They stack.

Common Combos

Combo 1: MCP + Skill

Use case: Database analysis.

• MCP provides the Postgres server (the agent can run SQL queries).
• Skill provides the procedure ("When asked about data quality, check schema first, look for nulls, then run aggregation queries, then summarize").

Without the skill, the agent has database access but guesses at the workflow. Without MCP, the skill describes a procedure the agent can't actually execute.

Combo 2: AGENTS.md + Subagent

Use case: Running tests after code changes.

• AGENTS.md documents the test command (pnpm test --filter payments).
• Subagent runs the tests in isolation, capturing 500 lines of output and returning only failures.

Without AGENTS.md, the subagent guesses the test command. Without the subagent, test output floods your main conversation.

Combo 3: Skill + Subagent

Use case: Code review.

• Skill defines the review checklist (security, tests, performance, style).
• Subagent runs the review in isolation, reading dozens of files and returning a prioritized list of issues.

Combo 4: All Four

Use case: Full debug workflow (as shown in the walkthrough above).

# AGENTS.md (project root)
## Setup
- Install: `pnpm install`
- Build: `pnpm build`
- Test: `pnpm test`

## PR conventions
- Title format: `[package] Brief description`
- Run `pnpm lint` and `pnpm test` before committing.

---

# MCP config (claude_desktop_config.json)
{
"mcpServers": {
  "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
  "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres"] },
  "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] }
}
}

---

# Skill: debug-diagnostics/SKILL.md
---
name: debug-diagnostics
description: Diagnose production issues. Use when a service returns errors or is degraded.
---

1. Check recent deploys (`git log --oneline -10`)
2. Read error logs from the affected service
3. Look for recent database migrations
4. Cross-reference deploy timing with error onset
5. Report: root cause, affected scope, suggested fix

---

# Subagent: .cursor/agents/investigator.md
---
name: investigator
description: Deep investigation of production issues. Use proactively when debugging errors.
tools: Bash, Read, Grep, Glob
disallowedTools: Edit, Write
model: sonnet
---

You are a production investigator. Run all diagnostic steps.
Report only: root cause, affected scope, and suggested fix.
Do not modify any code.

Common Mistakes

Using MCP when a skill would suffice

Scenario: You want the agent to follow your team's PR review process. Mistake: You build a custom MCP server that exposes a "review PR" tool. Why it's wrong: A PR review process is procedural knowledge, not an external system connection. A skill is simpler, more portable, and doesn't require running a server. Fix: Write a skill. Use MCP only when the agent needs to access something (the GitHub MCP server to fetch the diff, for example).

Putting reusable procedures in AGENTS.md

Scenario: You add your "incident runbook" to AGENTS.md in every repo. Mistake: The same runbook is now copy-pasted across 15 repos. When you update it, you update 15 files. Why it's wrong: AGENTS.md is project-specific. Reusable procedures belong in skills, which are shared across projects. Fix: Create a skill for the runbook. Reference it from each repo.

Skipping subagents for verbose operations

Scenario: You ask the agent to "run all tests and review the results." Mistake: The agent runs tests in the main conversation. 500 lines of output consume your context window. Fix: Delegate to a test-runner subagent. It captures the output and returns only failures.

Installing every MCP server on day one

Scenario: You install 15 MCP servers before you've used any of them. Mistake: Each server adds tools to the agent's context. Too many tools confuse tool selection—the agent picks the wrong one or takes longer to decide. Fix: Start with 2-3 servers for your most frequent tasks. Add more as specific needs arise.

By Experience Tier

• 1–3 years: Start with AGENTS.md. Document your project's setup, build, and test commands. This one file will save you from re-explaining the same things to your agent every session. That's enough for now.
• 4–7 years: Add MCP. Install 2-3 servers for tools you use daily (file system, GitHub, your database). The moment you stop copy-pasting data into your chat is the moment MCP clicks.
• 8–15 years: Add skills and subagents. Package your team's common procedures (code review, incident response, data analysis) as skills. Use subagents for noisy or restricted operations. Start sharing skills in your team's repos.
• 15–20 years: Design the toolkit at org scale. Which MCP servers are approved? Which skills are shared vs. team-specific? How are API keys managed? Create templates and governance that let teams adopt without reinventing.
• 20–30 years: You've seen this pattern before: standardize the interfaces (MCP), codify the procedures (skills), document the context (AGENTS.md), and isolate the execution (subagents). It's microservices architecture applied to AI workflows. Drive adoption as infrastructure strategy.
• 30+ years: The four layers map to principles you've applied for decades. Clean interfaces (MCP). Documented context (AGENTS.md). Codified expertise (skills). Bounded execution (subagents). The tools are new; the architecture isn't.

Do This Next

1. Audit your current setup. Which of the four layers are you using today? Which pain points map to a missing layer? ("I keep re-explaining my project" → AGENTS.md. "I keep copy-pasting data" → MCP.)
2. Add the missing layer. Don't add all four at once. Pick the one that solves your biggest pain point and set it up this week.
3. Try a combo. Once you have two layers, combine them for a real task. MCP + skill for data analysis. AGENTS.md + subagent for test automation.
4. Share with your team. If you created a skill or AGENTS.md that works, share it. Check skills into version control. Add AGENTS.md to your team's repo template.
5. Revisit in two weeks. After using the toolkit for real work, come back and add the next layer. The decision framework in this lesson will make more sense after hands-on experience.

Resources

• AGENTS.md lesson — Project-specific agent instructions.
• MCP lesson — Connecting agents to external systems.
• Agent Skills lesson — Portable procedures and domain expertise.
• Subagents lesson — Isolated specialists for complex tasks.
• agents.md — The AGENTS.md standard.
• modelcontextprotocol.io — The MCP standard.
• agentskills.io — The Agent Skills standard.