Skip to content

Agentic Software Development

Context & Specifications

Skills vs. MCP: When to Write a Markdown Runbook vs. Build a Tool Server

From Agentic Software Development · 10 articles · latest

Two-plane diagram comparing lazy-loaded SKILL.md runbooks against stateful JSON-RPC Model Context Protocol servers
Skills organize procedural know-how on disk; MCP servers enforce typed contracts, credentials, and mutations across system boundaries.

Once teams move past basic AGENTS.md files, they inevitably swing to one of two extremes. Either they cram every multi-step release checklist, database migration ritual, and blog formatting rule straight into the root prompt until context explodes—or they build a custom Model Context Protocol (MCP) server in TypeScript for a workflow that could have been three paragraphs of Markdown and a git command.

Running both mechanisms side by side in our own publishing stack—Markdown skills inside blogger-agent paired with dual MCP servers (wikantik-knowledge and roller)—clarified the line cleanly. As detailed in our Skills vs. MCP architecture guide, Skills and MCP live on different architectural planes. Skills encode procedural judgment (how to orchestrate tools for a specific goal); MCP exposes stateful capability and safety contracts (typed schemas, authentication, and server-side invariants).

What a Skill (SKILL.md) Actually Is

A Skill is simply a lazy-loaded directory on disk containing a SKILL.md file (YAML metadata header plus step-by-step instructions) alongside optional helper templates or reference scripts. Why is lazy loading so critical? Because when you register thirty Skills in a workspace, the agent only sees a two-line name and description for each one at startup (~15 tokens per skill). It reads the full SKILL.md instructions only when a user request actually matches that workflow.

Here is what a concise, high-leverage Skill header and body look like in practice:

---
name: publish-release-notes
description: Format, validate, and stage weekly changelog notes for Pressroom review.
---

# Release Notes Publishing Checklist
1. Run `git log v1.4.0..HEAD --oneline` to gather merged PR titles.
2. Group changes into User-Facing Features, Bug Fixes, and Breaking Changes.
3. Verify all internal links against `entries list` before staging.
4. Never auto-publish; stage with `status="DRAFT"` and run `audits seo_entry`.

Notice there is zero server process, zero JSON-RPC transport, and zero serialization boilerplate. Editing a Skill takes ten seconds in a text editor and goes straight through Git pull requests. If your workflow relies primarily on local CLI tools (git, pytest, ffmpeg, docker) plus domain judgment, writing an MCP server for it is pure waste.

Packaging Helper Scripts Inside a Skill

Unlike an AGENTS.md root file, a Skill directory can carry deterministic helper scripts (scripts/check_release.py) or static templates (resources/changelog_template.md) right alongside SKILL.md. The agent discovers and runs those helpers only when invoking the Skill, which keeps routine coding sessions blissfully unaware of release packaging details.

When You Actually Need an MCP Server

An MCP server earns its keep the moment you cross an authentication, schema, or state boundary where letting an agent wing raw curl commands or bash one-liners becomes dangerous or fragile.

Specifically, build or adopt an MCP tool server when at least two of these four conditions hold:

  1. Credential Isolation: The agent needs scoped capabilities (for example, AUTHOR vs ADMIN publishing tokens) without ever holding raw database passwords or admin session cookies inside shell environment variables.
  2. Server-Side Invariants & Validation: An API action must enforce business rules atomically—like Pressroom's optimistic locking hash checks (expectedContentHash) or AST media promotion on import—rather than trusting a prompt to remember them.
  3. Typed Schemas Over Ambiguous CLI Flags: Complex filter objects, nested payloads, and structured error diagnostics behave far better when validated against JSON Schema / OpenAPI contracts than parsed from brittle bash string interpolation.
  4. Remote Stateful Indexing: Operations like Wikantik's hybrid BM25 + pgvector search or Jena TDB2 semantic graph queries belong beside the database engine, as we detailed in First-Class AI Citizens: Dual MCP Architectures.

If you hand an agent raw Postgres credentials and tell it via a Skill "please remember to run WHERE tenant_id = 42," a single hallucinated query leaks cross-tenant data. Put that boundary inside an MCP tool server and enforce tenant scoping in code—and when you run separate read and write planes, give agents a clear decision tree like Finding the Right MCP Tool so routine queries stay on read-only endpoints.

Warning

Watch your MCP tool-definition bloat: Every MCP tool registered eagerly injects its full JSON schema into the system context on turn one. Registering 60 granular REST wrappers as separate eager MCP tools silently eats 15,000+ tokens before the user types "hello." Group related actions cleanly (for instance, entries with an action parameter) or lazy-load tool schemas on demand.

Skills vs. MCP Decision Matrix

DimensionSKILL.md RunbookMCP Server (call_mcp_tool)
Primary JobOrchestrates when and how to run stepsExposes what remote/typed actions exist
Deployment FootprintFiles checked into Git; zero runtime serverLong-lived process or HTTPS JSON-RPC endpoint
Security ModelInherits local workspace permissionsEnforces scoped tokens, RBAC, and validation
Context CostLazy-loaded (~15 tokens until triggered)Eager schemas cost upfront; lazy MCP mitigates this
Best FitEditorial style, PR templates, multi-step CLI flowsCMS publishing, DB search, telemetry, external SaaS APIs

Composing Both Planes Cleanly

The magic happens when Skills sit on top of MCP rather than competing with it. In blogger-agent, our publish_to_roller Skill never implements HTTP auth, image resizing, or WebP encoding—that lives inside Pressroom's native MCP server. Conversely, the Pressroom MCP server knows nothing about our brand tone, banned AI clichés, or 850-word floor—those editorial judgments live in SKILL.md and our local validation gates.

If you keep capability and safety inside MCP—and workflow judgment inside lazy-loaded Skills—both your AGENTS.md and your production services stay lean, auditable, and easy to evolve.

Keep reading

Comments