SKILL.md vs MCP: Declarative Config Beats Protocol Integration

The USB-C analogy for MCP is brilliant marketing [10]. One universal port that connects everything—databases, IDEs, browsers, SaaS tools—to any AI agent that speaks the protocol. Anthropic’s Model Context Protocol , launched November 25, 2024 [1], promises to eliminate the integration sprawl problem: instead of every agent needing a custom connector to every tool, agents and tools each implement a single standard. The community quickly dubbed this the shift from N×M custom integrations to a simpler model where both sides converge on one protocol.

But here’s what the marketing doesn’t emphasize: USB-C cables don’t require you to run a local server, negotiate stateful sessions, or debug JSON-RPC error codes at 2 AM. MCP does.

For many real-world use cases, a YAML file with markdown instructions beats a protocol-based client-server architecture. The emerging SKILL.md pattern proves it. While MCP adoption accelerated with OpenAI [4] and Google DeepMind [5] integrations in 2025, teams are discovering that declarative agent configuration offers a faster path to value—especially when your “integration” is primarily about encoding procedural knowledge rather than connecting to external systems.

This article examines both approaches honestly. MCP solves real problems for real scenarios. But so does SKILL.md, and understanding when each fits will save you from architectural overkill that slows down teams rather than empowering them.

The Two Paths: Declarative vs Protocol-Based Configuration

Agent configuration today splits into two fundamentally different philosophies.

SKILL.md takes a declarative approach. You write a YAML frontmatter block describing the skill’s metadata—name, description, parameters—followed by markdown instructions telling the agent exactly how to behave. The file lives on the filesystem. The agent reads it when needed. No servers spin up. No sockets open. No protocols negotiate capabilities.

MCP takes a protocol-based approach. You build a server implementing the MCP specification [9]. It speaks JSON-RPC 2.0 over stdio or HTTP. Clients maintain stateful 1:1 connections to servers. Capability negotiation happens at connection time. Every tool invocation traverses this protocol stack.

The difference isn’t cosmetic—it changes who owns the complexity. With SKILL.md, complexity lives in the agent’s implementation. With MCP, complexity lives in your infrastructure.

Here’s what a simple SKILL.md file looks like:

---
skill:
  name: code_review
  description: Review code changes for quality, security, and maintainability
  params:
    files:
      type: array
      description: List of file paths to review
      required: true
    focus:
      type: string
      description: Specific area to focus on (security, performance, readability)
      default: general
---

## Instructions

When reviewing code:
1. Check for obvious security issues (SQL injection, XSS, hardcoded secrets)
2. Verify error handling exists and is appropriate
3. Look for test coverage of critical paths
4. Flag overly complex functions (>50 lines)
5. Suggest specific improvements, not vague criticisms

The entire skill is self-contained in a single human-readable file. Git tracks every change. Rollbacks require nothing more than git checkout. No deployment pipeline. No health checks. No authentication configuration.

Exposing the same capability via MCP requires building and running a server process, establishing a stateful client-server connection, completing capability negotiation, and implementing error handling for transport failures. Both approaches accomplish similar goals—but one adds layers of infrastructure between your intent and the result.

The declarative approach treats skills as data. The protocol approach treats capabilities as services. Data is easier to version, inspect, and reason about. Services require operational expertise and ongoing maintenance.

MCP’s Hidden Complexity Tax

The integration simplification promise of MCP is genuine. When you have twenty different agents needing database access, MCP eliminates twenty separate custom connectors. Each agent connects to one MCP server; the server manages database connectivity.

What hides in that simplicity is the operational cost of the abstraction.

Session lifecycle management becomes your problem. MCP connections are stateful [10]. When connections drop—and they will—you handle reconnection logic, state reconciliation, and error propagation. In production, this means health checks, circuit breakers, and graceful degradation strategies that didn’t exist before MCP.

Authentication complexity blocked enterprise adoption for months. The June 2025 specification update added RFC 8707 Resource Indicators support [2], binding tokens to specific MCP server URIs to prevent malicious servers from mis-using access tokens [8]. The November 2025 update then added async tasks and further OAuth extensions [3]. These additions addressed real enterprise blockers—but each added configuration surface area that teams must manage.

Server sprawl emerges as adoption grows. Each new capability requires a server process. A typical production deployment might have separate MCP servers for databases, APIs, file systems, and custom business logic. Each needs monitoring, logging, updates, and security patches.

Replit Connectors, launched October 2025 [7], illustrates this dynamic. Replit absorbed MCP’s complexity into their platform, offering 20+ pre-built integrations (Google, Dropbox, Salesforce, Linear, Notion). Users got the benefit without the operational burden—because Replit’s engineers carried it. Teams without that infrastructure face it directly.

When to Choose Which Approach

The decision isn’t about which is better—it’s about which fits your constraints.

Choose MCP when:

• You’re integrating external systems requiring real-time data (databases, APIs, SaaS platforms)
• Multiple teams need shared access with different permission levels
• Audit trails and access logging are non-negotiable requirements
• You have operations expertise to manage server infrastructure
• The ecosystem already has MCP servers for what you need (growing rapidly since OpenAI [4] and Google DeepMind [5] adoption in 2025, with Google Cloud adding managed MCP server support in December 2025 [6])

Choose SKILL.md when:

• You’re encoding procedural knowledge (code review guidelines, deployment procedures, team conventions)
• Rapid iteration matters more than protocol compliance
• You lack operations resources for server management
• Version control integration and rollback simplicity are priorities
• Context window efficiency matters—loading metadata for 100 SKILL.md files costs roughly ~10,000 tokens (an approximation based on typical SKILL.md frontmatter size); 100 active MCP connections require persistent session state

Hybrid approaches are emerging as the practical reality. Many teams use MCP for external tool connectivity while using SKILL.md for usage conventions and context-specific behaviors. An agent might connect to an MCP database server for queries while following SKILL.md instructions for how to structure responses or handle edge cases.

The framework for choosing is simpler than it appears: ask whether this capability needs to connect to something external or guide how the agent thinks. Connection problems favor MCP. Guidance problems favor SKILL.md. Most real-world agents need both.

Practical Takeaways: Choosing Between SKILL.md and MCP

Before you choose MCP:

• Confirm you actually need real-time external connectivity. If the capability is purely instructional, a protocol server adds cost with no benefit.
• Budget for operations. Stateful MCP servers require monitoring, health checks, and security patching. If your team lacks that bandwidth, start with SKILL.md and migrate later. A concrete failure mode teams encounter: an MCP server drops its database connection during a brief network hiccup, and the agent silently receives errors or stale data because no reconnection logic was implemented. Build and test that resilience before going to production, not after.
• Check the ecosystem. As of early 2026, MCP servers exist for most major databases, APIs, and SaaS tools—including Google Cloud’s managed MCP server offering [6]. If a server already exists for your target system, the operational cost may be worth it.

Before you choose SKILL.md:

• Confirm the skill doesn’t need to authenticate to anything. SKILL.md inherits filesystem permissions—it has no built-in mechanism for OAuth flows or API credentials.
• Plan your discovery model. Skills need to be discoverable by the agent. A practical pattern: keep a single skills/ directory in your agent’s repository, one named subdirectory per skill containing its SKILL.md, and a manifest file the agent reads at startup. Without a consistent convention, skill sprawl becomes its own maintenance burden as the library grows.
• Use progressive disclosure. Keep frontmatter concise (~100 tokens of metadata); load full instructions only at invocation time. The OpenAI Agents SDK [11] follows a similar principle for tool definitions—register tool metadata upfront, resolve full context on demand.

For hybrid architectures:

• Treat MCP and SKILL.md as complementary layers, not competing standards.
• Use SKILL.md to encode how to use an MCP tool—rate limits, retry behavior, response formatting—without baking that knowledge into the server itself.
• Version both together in the same repository so capability and usage guidance stay in sync.

Conclusion

MCP’s integration standardization solves a genuine pain point, and rapid adoption by OpenAI [4], Google DeepMind [5], Google Cloud [6], and platforms like Replit [7] validates its trajectory. For teams building agents that connect to databases, APIs, and enterprise systems, MCP has become the standard path forward.

But the analogy breaks down in important ways. USB-C cables don’t require you to run a server process. They don’t need authentication configuration [2][8] or session management [10]. MCP does all of these things, and those costs matter—especially for teams encoding procedural knowledge that doesn’t require external connectivity.

The SKILL.md pattern offers a compelling alternative for these cases. Progressive disclosure keeps context windows manageable. Git-native versioning aligns with existing workflows. Zero infrastructure requirements enable rapid experimentation.

The smartest teams aren’t choosing sides—they’re choosing both. MCP for external connectivity. SKILL.md for internal guidance. Understanding when each fits separates teams that ship useful agents from those stuck in architectural debates.

Sources