Skills vs MCP: Extending Coding Agents in Modern Architectures

In modern agentic software development, extending an autonomous agent requires navigating two complementary architectural surfaces: procedural skills and the Model Context Protocol (MCP). Confusing these two surfaces or forcing one into the role of the other produces fragile, expensive, and non-deterministic agent behavior.

The fundamental distinction:

Model Context Protocol (MCP) is a connectivity standard: It defines how an agent establishes authenticated, structured, bidirectional communication with external systems (APIs, databases, knowledge graphs, software servers).
Skills are a procedural knowledge format: Packaged as structured directories centered on a SKILL.md file, skills encode human heuristics, step-by-step methodologies, quality gates, and error-recovery procedures.

The Architectural Axiom: MCP equips an agent with tools and hands; skills give the agent judgment and methodology; semantic wiki pages provide the authoritative source of truth.

flowchart TD
    subgraph Human_and_Intent["1. Human Intent & Standing Rules"]
        RULES["Root Invariant Rules<br/>(AGENTS.md / CLAUDE.md)"]
        PROMPT["Task Directive<br/>(e.g., 'Elevate VectorIndexingInternals')"]
    end

    subgraph Agent_Core["2. Agent Reasoning Engine (Antigravity agy / Claude Code)"]
        RUNTIME{"LLM Orchestrator<br/>(Prompt + Context Assembly)"}
    end

    subgraph Procedural_Layer["3. Procedural Skills Layer (.agents/skills/)"]
        SKILL_H["Skill Header (60 tokens)<br/>Loaded on Session Init"]
        SKILL_B["Skill Runbook (SKILL.md)<br/>Progressively Injected on Match"]
        SKILL_H -.->|Trigger Condition| SKILL_B
    end

    subgraph Connectivity_Layer["4. Data Plane: Model Context Protocol (MCP)"]
        K_MCP["Knowledge MCP (/knowledge-mcp)<br/>21 read tools: assemble_bundle, get_page_for_agent"]
        A_MCP["Admin MCP (/wikantik-admin-mcp)<br/>29 write tools: update_page, verify_pages"]
        R_MCP["Roller MCP (/api/mcp)<br/>Customer blog publishing tools"]
    end

    subgraph Systems_Plane["5. Operating Systems & Knowledge Backbone"]
        WIKI[("Wikantik Semantic Wiki<br/>(Specs, ADRs, RDF Graph)")]
        BLOG[("Roller Fork (docker2)<br/>Customer Outreach")]
        REPO[("Product Codebases<br/>(stockroom, jspwiki, jakemon)")]
    end

    RULES --> RUNTIME
    PROMPT --> RUNTIME
    SKILL_H --> RUNTIME
    RUNTIME -->|Invokes Method| SKILL_B
    SKILL_B -->|Guides Tool Selection| RUNTIME
    RUNTIME <-->|Calls Tool| K_MCP
    RUNTIME <-->|Calls Tool| A_MCP
    RUNTIME <-->|Calls Tool| R_MCP
    K_MCP <--> WIKI
    A_MCP <--> WIKI
    R_MCP <--> BLOG
    RUNTIME <-->|File Edits / Bash| REPO

1. The Anatomy of Modern Agent Extensions

The Model Context Protocol (MCP) Surface

Introduced by Anthropic in late 2024 and standardized across the AI industry (supported natively in Claude Code, Antigravity, Cursor, Gemini CLI, Goose), MCP provides a client-server JSON-RPC architecture over Streamable HTTP or stdio:

Tool Discovery (tools/list): Exposes machine-readable JSON Schema definitions defining exact parameter constraints.
Granular Privilege Partitioning: Enables security boundaries by separating read-only discovery from destructive administrative writes.
Stateful Session Management: Manages OAuth tokens, database connection pooling, and multi-tenant authorization out-of-band so the agent never touches raw credentials.

The Open `SKILL.md` Specification

A skill is a self-contained directory following the open cross-client standard:

.agents/skills/project_structured_page_curation/
├── SKILL.md                 # Primary instruction file with YAML frontmatter
├── references/              # Context reference docs loaded on demand
└── scripts/                 # Deterministic validation scripts

The operational core is progressive disclosure:

At session boot, only the skill's name and its 50–80 token frontmatter description enter the agent's context window.
The substantive 2,000–3,500 token instruction body is loaded dynamically only when the agent determines that the task requires that specific capability.

2. Real-World Stack Grounding: Wikantik and Roller

The Simple Agility ecosystem demonstrates how skills and MCP servers cooperate across production environments:

1. Wikantik Dual-MCP Architecture

Wikantik partitions its 50 tools into two distinct trust tiers (ConnectingClaudeCodeToWikantikMcp, FindingTheRightMcpTool):

/knowledge-mcp (21 Read-Only Tools): Available to standard coding agents and guest keys (mcp_read). Exposes semantic hybrid search (assemble_bundle), context discovery (retrieve_context), token-budgeted projections (get_page_for_agent), structural navigation (list_clusters, list_pages_by_filter), and RDF SPARQL querying (sparql_query, get_ontology).
/wikantik-admin-mcp (29 Read/Write Tools): Restricted to privileged administrative keys (mcp_admin). Exposes page authoring (write_pages, update_page), verification stamping (mark_page_verified), cluster renames (rename_cluster), and Knowledge Graph curation (curate_nodes, curate_edges).

2. Roller Native Blog MCP

The sovereign customer communication platform (RollerHub) exposes a specialized MCP server at /api/mcp on docker2:

Enables autonomous publishing agents (blogger-agent, SA-INIT-01) to query weblogs, create draft entries, assign categories, and stage customer spotlights.
Protected by role-based API tokens (POST, EDIT_DRAFT, ADMIN), ensuring that a compromised blogging agent cannot perform server administrative operations.

3. Production Procedural Skills

In ~/source/wiki-content-agent/.agents/skills/, dedicated skills orchestrate complex multi-step routines:

project_structured_page_curation: A specialized skill encoding the exact heuristics for updating page frontmatter, enforcing the Wikantik v2.4 scalar cluster declaration architecture, escaping currency math, and curating Knowledge Graph node boundaries.

3. Comparative Decision Matrix

To determine whether an extension should be implemented as an instruction file, a skill, a plain script, or an MCP server, apply this comparative evaluation:

Extension Mechanism	Token Cost Incurred	Execution Substrate	Primary Responsibility	Ideal Use Case
Instruction File (`AGENTS.md`)	Every session boot (unconditional)	Root repository configuration	Non-derivable rules, command truth, hard invariants	Build/test flags, project boundaries, directory maps
Procedural Skill (`SKILL.md`)	Deferred until trigger (~98% cost deferred)	Local or client-wide directory	Multi-step methodology, checklists, domain judgment	Release runbooks, style guide compliance, refactor workflows
Plain Bash/Python Script	Zero until execution (output only)	Shell / Container runtime	Deterministic, non-judgmental transformations	Code compilation, unit test suites, database migration scripts
MCP Server	Tool schema in context; data on call	Independent network daemon (HTTP/stdio)	Authenticated external I/O, live data querying, system mutation	Semantic search, database querying, wiki curation, cloud APIs

4. The Power Trifecta Pattern: Wiki + Skill + MCP

The most robust architectural pattern composes all three components into a cohesive loop:

[MCP Server] (Capabilities: what can be touched)
      ▲
      │ Tool Calls & Schema Payloads
      ▼
[Agent Runtime] ◄─── Guides Methodology ───► [Skill: SKILL.md] (Heuristics: how to execute)
      ▲
      │ Queries Ground Truth
      ▼
[Semantic Wiki] (Normative Truth: what should be built)

The Semantic Wiki (Wikantik): Stores the authoritative architectural contract, event schema, and business rules (SimpleAgilityCommerceDataFlow, SimpleAgilityAttributionRFC).
The MCP Server (/knowledge-mcp): Provides the authenticated programmatic pipe allowing the agent to retrieve sections of the contract without human manual pasting.
The Skill (SKILL.md): Instructs the agent on the required verification sequence:
- Step 1: Query the contract on Wikantik via assemble_bundle.
- Step 2: Implement the Java service in the product repository.
- Step 3: Run the local test suite via ./mvnw test.
- Step 4: Verify that code conforms to the wiki specification.
- Step 5: Mark the wiki documentation as verified using mark_page_verified.

5. Mathematical Modeling of Skill Token Efficiency

The economic advantage of progressive disclosure over monolithic instruction files can be proven mathematically.

The Progressive Token Efficiency Model

Let N_inline represent the token count of inlining all procedural instructions into a monolithic AGENTS.md file. Let N_header be the lightweight descriptor cost loaded at session boot (N_header ≈ 65 tokens), and N_body be the full skill instruction body (N_body ≈ 2,500 tokens).

Let P(invoke) represent the empirical probability that a given coding session requires that specific skill. The expected token consumption per session E(T) is modeled as:

E(T) = N_{\text{header}} + P(\text{invoke}) \cdot N_{\text{body}}

The Context Conservation Ratio eta_saving is defined as:

\eta_{\text{saving}} = 1 - \frac{E(T)}{N_{\text{inline}}} = 1 - \frac{N_{\text{header}} + P(\text{invoke}) \cdot N_{\text{body}}}{N_{\text{inline}}}

Concrete Numerical Example

Consider an organization maintaining 12 specialized engineering workflows (e.g., database migration, security audit, page curation, release tagging), each averaging 2,500 tokens of procedural instructions:

Monolithic Approach: Inlining all 12 workflows into AGENTS.md:

Total Cost: 12 * 2,500 = 30,000 tokens
Every session incurs a 30,000-token tax upon initialization, consuming 15% of a 200k context window before the developer types a prompt.

Progressive Skill Approach: Packaging each workflow into a SKILL.md with a 65-token header:

Total Startup Header Cost: 12 * 65 = 780 tokens
In a typical single-focus coding session, the developer invokes at most 1 skill (P(invoke) ≈ 0.083 for each skill, or 1 skill body loaded):
Expected Session Cost: 780 + 2,500 = 3,280 tokens

Net Conservation:

\eta_{\text{saving}} = 1 - \frac{3,280}{30,000} = 1 - 0.109 = 0.891 \text{ (89.1\% token reduction)}

Progressive disclosure reduces session context overhead by 89.1%, preserving critical working memory for active code analysis and reasoning.

6. Anti-Patterns in Agent Extension Design

The Tool Definition Bloat Trap (The 100-Tool Paralysis): Registering dozens of fine-grained MCP tools on a single endpoint. Every tool definition injects its JSON Schema into the agent's context window. When an agent is presented with 80+ tools, tool selection accuracy degrades, latency increases, and token overhead escalates. Consolidate granular actions into parameterized tools (e.g., Wikantik's unified update_page supporting metadata and content merges).
The Procedural MCP Server: Building an MCP server to enforce a multi-step human workflow. MCP tools should expose atomic capabilities (read, write, execute). The sequencing and judgment belong in a Skill, where the reasoning model can adapt to unexpected intermediate results.
The Pure Documentation Skill: Authoring a skill that contains only static reference facts without actionable triggers, step sequences, or quality gates. Factual reference material belongs on a Semantic Wiki; skills are reserved for executable methodologies.
Tool/Skill Contradiction: When a skill provides instructions that conflict with an MCP tool's formal JSON Schema constraints. Automated CI tests must validate that skills invoke valid tool parameter signatures.