Authoring skills vs mcp

Authoring: Skills vs MCP Servers

Two different ways to extend an agent, for two different things. Picking the wrong one is the most common waste: knowledge bloated into a server, or a real capability trapped in prose the model can only read, never call. This skill is the decision axis plus how to author each artifact. It composes with skill-creator / writing-skills (authoring mechanics) and mcp-builder (server mechanics) — it covers the choice between them, which they don't.

1. The decision axis (apply this first)

• SKILL = knowledge. Methodology, convention, domain knowledge the model reads into context and then acts on with the tools it already has. There is nothing to "call."
• MCP SERVER = capability. An external system / API / DB / service that needs credentials and structured I/O — a callable tool the model invokes to do something and get a typed result back.

The test: "Would the agent READ this to know how, or CALL this to do it?"

• Read-to-know-how → skill. (e.g. "how to model a REST resource", "how we review for regressions".)
• Call-to-do-it → MCP. (e.g. "search this ticketing system", "write a DNS record", "query the metrics warehouse".)

Two failure modes to reject:

• Don't MCP-ify knowledge. A methodology doesn't become a server because it's important. It has no creds, no structured call — it's a skill.
• Don't trap a capability in prose. A skill that says "here's how to hit API X: curl this, parse that" is a capability wearing a skill costume. Extract it into an MCP tool; leave at most a thin methodology skill behind.

Hybrids are real: keep the methodology as a skill and the call as an MCP (e.g. a "research discipline" skill beside a "search the source" MCP). Split along the read/call line.

2. How to author a SKILL

• Frontmatter: name (kebab-case purpose), a description that says when to use (and when not) so it's discoverable cold.
• Progressive disclosure: lead with the decision/the rule; push detail and edge cases lower or into companion files.
• When-to-use / when-not: state both. A skill that never says when not to fire mis-activates.
• Examples + anti-patterns: show the right call and the common wrong ones.
• Gold-bar, no slop: a skill earns its place by changing behavior. If it restates what a capable model already does, don't ship it.

3. How to author an MCP SERVER

• Tools & resources: model each tool as one clear verb with a typed input/output schema. Prefer a few sharp tools over one overloaded one.
• Structured I/O: return structured results, not prose blobs — the caller is a program path.
• Credentials stay out of the server body: fetch them at call-time from a secrets broker / secret store; never bake keys into the server or its config. Keys live in the broker, not the workload.
• Idempotency & errors: make writes safe to retry; return typed errors the agent can branch on.
• Provenance / security audit: run the server through a static skill/tool audit (malicious-code + injection scan) before any agent adopts it.

4. Gates and where it ships

Both artifacts clear the same publishing bar — gold-only utility, privacy/secret scan, gated PR, public-first routing. That bar lives in skill-curation; apply it, don't restate it here.

When to use / not

• Use when classifying a capability/knowledge item, or deciding how to extend an agent.
• Not for the line-by-line mechanics of writing a skill (skill-creator / writing-skills) or wiring a server (mcp-builder) — this picks which one, then hands off.

Anti-patterns

• Building an MCP server for a pure methodology (knowledge-as-a-server).
• A skill that teaches the agent to hand-call an external API (capability-in-prose) instead of an MCP tool.
• One mega-tool with an untyped grab-bag input.
• Credentials embedded in the server instead of fetched from a broker at call-time.
• Adopting a server with no provenance/security audit.
• Publishing either artifact with org traces, or on elegance instead of proven value.