Should Every MCP Server Ship with an Agent Skill?

An MCP server must be useful without an agent skill. A skill can make a good server easier to operate, but it should never be the missing instruction manual for ambiguous tools—or the place where security controls exist only as prose.

Model Context Protocol servers and agent skills solve related problems at different layers. The server gives an agent capabilities: tools, resources, prompts, live data, authentication, and controlled actions. A skill gives the agent a repeatable way to apply those capabilities to a particular kind of work.

That distinction sounds simple. It becomes less obvious when a team has a working MCP server and starts asking whether a SKILL.md should ship beside it. The answer is not “always” and not “never.” The useful question is whether the server exposes a clear capability while the task still contains a non-obvious procedure.

An MCP server must work without a skill. Add a skill when the workflow—not the interface—needs explanation.

Draw the boundary before writing instructions.

A useful design starts by assigning each kind of knowledge to the layer that can actually uphold it. Four layers usually matter:

The MCP documentation describes servers as standardized providers of tools, resources, and prompts. The protocol also lets a server return general instructions during initialization. Those instructions are useful for server-wide guidance such as “search before fetching full records” or “all timestamps are UTC.” They are still hints, not enforcement.

A skill is narrower. It is selected only when a task matches its description, then contributes a workflow and any supporting scripts, references, or assets. That progressive disclosure makes a skill a good home for detailed procedures that would otherwise burden every session. OpenAI’s skills documentation makes the same practical distinction: MCP supplies capabilities and live access; a skill teaches a repeatable way to use them.

Run the no-skill test.

Imagine a capable agent connects to the MCP server with no repository context, no vendor-specific prompt, and no bundled skill. It receives only the protocol-level server information and the available tool definitions. Can it complete a basic task correctly and safely?

1. Can it identify the right tool from the name and description?
2. Can it form valid arguments from the schema without knowing undocumented IDs or magic values?
3. Does the result contain the fields needed for the next decision without a second call just to decode it?
4. Do errors explain what failed, whether retrying is safe, and what correction is possible?
5. Would the operation remain authorized and safe if the model ignored every instruction around it?

If any answer is no, fix the MCP interface or the server first. A skill may later improve efficiency, but it should not be required to translate a poorly designed contract.

The same principle applies to composite tools. If almost every caller needs the same mechanical sequence—fetching a run, isolating failed steps, removing duplicate log lines, and calculating duration—the server can expose summarize_pipeline_failure. Do deterministic work in code. Reserve the skill for the parts that genuinely require task judgment.

A skill earns its place in three situations.

01There is a non-obvious multi-tool workflow

Some goals legitimately cross several useful tools. Investigating a failed deployment might involve finding the failed run, reading its summary, checking the deployed revision, comparing environment configuration, retrieving a bounded log excerpt, and verifying a later rerun.

None of those tools is badly designed. The value is in choosing an efficient order, branching on evidence, and knowing when to stop. A skill can encode that procedure:

1. Locate the newest failed run for the requested branch.
2. Read the structured failure summary.
3. If the category is configuration, compare deployment settings.
4. If evidence is insufficient, fetch only the failed step's log excerpt.
5. Stop when one cause is supported by two independent signals.
6. Return cause, evidence, proposed fix, and verification state.

This avoids random tool exploration without turning a flexible investigation into one oversized server tool. The skill improves orchestration; each MCP tool still makes sense by itself.

02The task depends on domain-specific decision rules

A generic tool can retrieve a vulnerability, account, claim, or incident. A correct decision may depend on domain rules that are too contextual to hard-code as one universal server behavior:

• Escalate a vulnerability when exploitability, asset exposure, and business criticality cross the team’s review threshold.
• Prefer a reversible migration when production data cannot be fully reconstructed.
• Require two corroborating signals before labeling an intermittent deployment failure as infrastructure-related.

A skill can package these decision rules with examples and counterexamples. The server should still enforce hard invariants: who may access the record, which fields may leave the system, and which state transitions are allowed. Judgment belongs in the skill; permission belongs in code.

03Setup and verification are part of the job

Installation instructions are rarely enough. A useful setup workflow may need to detect the operating environment, select an authentication method, register the server, confirm capability discovery, run a read-only smoke test, and explain how to remove the integration cleanly.

This is excellent skill material because it is repeatable, conditional, and has a verifiable finish. Bundle a deterministic verification script when possible, and make the definition of done explicit:

Setup is complete only when:
- the MCP client discovers the expected server version;
- the required tools are visible;
- a read-only health call succeeds;
- the authenticated identity and scopes are reported;
- no credential value appears in output or logs.

The skill guides the installation and reports evidence. The client and server still own credential storage, transport security, scope enforcement, and token validation.

Never use a skill to patch a weak server.

Skills are persuasive context. They can improve model behavior, but they cannot create a security boundary or repair a confusing contract. If a rule must hold even when the model is mistaken, distracted, or manipulated, enforce it outside the model.

The MCP specification treats tool annotations as hints, and clients must consider them untrusted when the server is not trusted. Skills deserve the same mental model. They can inform selection and approvals, but they do not enforce either. The MCP authorization guidance places access control, scope checks, secure token handling, and error hygiene where they belong: in the system.

Package one portable skill, not three drifting copies.

When a skill is justified, keep its core agent-neutral. The open Agent Skills specification defines a directory with a required SKILL.md and optional scripts, references, and assets. The description acts as a routing rule; the body provides the executable workflow.

investigate-pipeline-failure/
├── SKILL.md
├── references/
│   └── failure-categories.md
├── scripts/
│   └── verify-setup.sh
└── agents/
    └── openai.yaml       # optional platform metadata

Keep the portable core focused on five things: trigger, inputs, workflow, output, and verification. Put detailed domain reference material outside SKILL.md so it is loaded only when needed. Use scripts for deterministic checks rather than asking the model to simulate a shell command or compare large outputs by eye.

---
name: investigate-pipeline-failure
description: Diagnose a failed CI/CD pipeline using the connected MCP tools.
  Use when a user asks why a build or deployment failed.
---

# Objective
Find the most likely cause with bounded evidence and propose the next safe action.

# Workflow
1. Resolve the repository, branch, and failed run.
2. Read the structured failure summary.
3. Follow the matching branch in references/failure-categories.md.
4. Retrieve raw logs only when the summary lacks decisive evidence.
5. Stop before any rerun, rollback, or configuration change unless approved.

# Output
Report the failed stage, likely cause, evidence, proposed action, and confidence.

# Verification
After an approved fix, check the new run and report its final state.

Adapters should remain thin. Translate tool names, invocation syntax, or platform metadata only where an agent host genuinely differs. Do not fork the reasoning policy into multiple near-identical documents. GitHub’s Agent Skills documentation, for example, explicitly supports the open skill format and several shared project locations, including .agents/skills.

What belongs in the description?

Treat the skill description as a routing rule, not marketing copy. It should say what the skill does and when it should activate. Include positive triggers and enough boundaries to avoid activation on every related tool call.

Test the server and the skill separately.

Shipping the two together should not blur their quality gates. First prove that the MCP server works in a clean client. Then prove that the skill improves a recurring task without becoming a hidden dependency.

Measure the improvement at task level: fewer wrong tool selections, fewer unnecessary calls, lower latency, less raw context, more consistent decisions, and a higher rate of verified completion. A skill that merely adds tokens and ceremony has not earned its distribution cost.

The practical decision.

So, should every MCP server ship with an agent skill? No. A small server with a few obvious, well-described tools may gain nothing from one. Ship a skill when users repeatedly perform a procedure with meaningful ordering, branching, domain judgment, setup, or verification.

The best skill makes a good MCP interface faster to use and harder to misuse. It never makes a bad interface acceptable.