Agent Skills vs MCP: Choosing the Right Interface
Agent skills vs MCP explained: compare instructions, tool connections, security boundaries, versioning, and when to combine both for reliable AI agents.
The agent skills vs MCP decision is often framed as a competition between two ways to “give an AI tools.” That framing is incomplete. A skill and a Model Context Protocol server solve different layers of the problem: one teaches an agent how to operate in a domain, while the other exposes capabilities and context through a standardized connection.
Dockup uses a SKILL.md because its primary interface is an existing command-line tool. The skill teaches Claude Code and Codex to use that CLI safely: always request JSON, authenticate non-interactively, resolve exact targets, wait for terminal deployment states, and stop before destructive work.
What is an agent skill and why does SKILL.md matter?
An agent skill is a directory of operating instructions and supporting references that an agent can load when a task matches the skill’s purpose. SKILL.md is the entry point: its frontmatter describes the capability, and its body explains workflows, constraints, examples, and decision rules.
A skill is especially useful when the executable interface already exists. The agent does not need a new protocol adapter merely to run a well-designed CLI. It needs accurate knowledge about:
- Which commands are authoritative.
- Which flags are required for machine use.
- How authentication works in a sandbox.
- Which outputs prove success.
- Which actions require a human.
- Where secrets may appear.
- How to diagnose common failures.
Dockup’s installation is intentionally simple:
npm install -g dockup-cli
dockup skill install
dockup skill status --json
One canonical copy is written to ~/.agents/skills/dockup/ and linked into both Claude Code and Codex. The skill ships inside the CLI package, and dockup update refreshes them together. That packaging decision prevents a common failure mode: instructions describing commands that the installed binary does not have.
The skill is not the deployment engine. The CLI performs operations, emits JSON, and returns exit codes. The skill is the operating manual the agent follows.
What is the Model Context Protocol?
The Model Context Protocol, commonly called MCP, is an open protocol for connecting an AI application to external tools, resources, and prompts through a client-server architecture. An MCP server can expose callable tools, readable resources, and reusable prompts. An MCP client inside the agent host discovers and invokes those capabilities.
MCP is valuable when a system needs a durable protocol boundary rather than local shell execution. Examples include:
- A remote SaaS API that should expose carefully typed operations.
- A data source that provides browsable resources.
- A desktop application that wants tool discovery without shipping a CLI.
- A central service used by many agent hosts and operating systems.
- An integration where the server must mediate credentials and policy.
The server controls the implementation behind each tool. The agent host sees the declared name, description, input schema, and output. Transport, lifecycle, and authorization depend on the chosen MCP setup.
MCP does not automatically provide domain judgment. A server may expose delete_service, but the agent still needs policy about when deletion is appropriate. Conversely, a skill can explain a workflow but cannot create capabilities that are absent from the underlying CLI or API.
How do agent skills vs MCP differ in practice?
The clearest comparison is by responsibility:
| Dimension | Agent skill / SKILL.md | MCP server |
|---|---|---|
| Primary job | Teach workflows and constraints | Expose tools, resources, and prompts |
| Execution | Uses existing CLI, files, APIs, or apps | Server implements callable capabilities |
| Discovery | Agent loads matching skill instructions | Client discovers server capabilities |
| Deployment | Often a folder installed with a package | A local or remote server process |
| Version risk | Instructions can drift from the tool | Server schema can drift from backend behavior |
| Best fit | Existing interface needs expert operating guidance | Capability needs a standardized protocol boundary |
| Security focus | Behavioral rules and command safety | Connection, server trust, scopes, and tool authorization |
| Offline/local use | Excellent with local CLIs | Possible with a local MCP server |
| Multi-client reuse | Copy or package the skill for each host | One server can support multiple compatible clients |
Neither column is inherently more “agentic.” Reliability comes from matching the interface to the system.
For Dockup, the CLI already has 135 commands, structured JSON, true exit codes, a 900-second default deploy timeout, secret masking, and confirmation gates. Wrapping every command in another local server would add a translation layer without changing the underlying deployment truth. A skill is a direct fit because it teaches the agent how to use the executable contract that already exists.
A remote platform with no CLI may reach the opposite conclusion. An MCP server can provide the missing typed tool surface and keep API credentials outside the agent’s shell environment.
When should you use a skill, MCP, or both?
Use a skill alone when all of the following are true:
- A mature CLI or local application already exposes the required capability.
- The agent host is allowed to execute it.
- Machine-readable output and exit semantics are adequate.
- The main gap is procedural knowledge, not connectivity.
- Packaging can keep instructions aligned with the executable.
Use MCP alone when the agent needs a protocol-native connection and the server itself can provide enough context for safe operation. This is common for read-heavy data access, remote services, and applications that want a stable cross-client tool interface.
Use both when the protocol tools need a richer operating playbook. An MCP server might expose safe, typed primitives, while a skill explains the multi-step business workflow, escalation rules, and validation criteria. The skill can tell the agent when and why to call each MCP tool.
A combined architecture can look like this:
User request
↓
Skill: workflow, policy, validation rules
↓
MCP client: discovers typed capabilities
↓
MCP server: authenticates and executes
↓
External system
A CLI-centered architecture is simpler:
User request
↓
Skill: workflow, policy, validation rules
↓
CLI: JSON output + exit code + wait semantics
↓
Platform API
Complexity should be justified by a boundary it improves. Adding MCP solely because it is fashionable can create another process to deploy, authenticate, monitor, and version.
Decision examples
| Situation | Better starting point | Reason |
|---|---|---|
| Local deployment CLI with JSON output | Skill | Connectivity already exists |
| Company knowledge base with structured resources | MCP | Resource discovery is central |
| Database administration API without a CLI | MCP | Typed remote operations are useful |
| Complex release runbook across existing tools | Skill | Cross-tool procedure is the main need |
| Regulated remote operations plus detailed policy | Both | Server enforces scope; skill guides behavior |
| One-off personal automation | Skill or direct CLI | Lowest operational overhead |
The right answer can change over time. A team may begin with a skill around a CLI, then add an MCP server when remote multi-client access or centralized credential mediation becomes important.
How do security and trust boundaries compare?
Skills are instructions, so their trust risk resembles code documentation with operational influence. A malicious or careless skill can tell an agent to expose secrets, disable safeguards, or run destructive commands. Review the full directory, not only its title.
Questions for a skill review include:
- Who published it?
- Does it invoke commands outside its stated purpose?
- Does it instruct the agent to print tokens or credentials?
- Does it bypass confirmations?
- Are command examples derived from the installed version?
- Can updates replace the skill without review?
- Does the skill define a bounded target-discovery process?
MCP introduces a server trust boundary. The client must know which server it is connecting to, which tools it exposes, what data leaves the machine, and how authorization is scoped. A server can change behavior behind a stable tool name, so deployment provenance and server versioning matter.
Questions for an MCP review include:
- Is the server local or remote?
- Who operates it?
- How are credentials stored and rotated?
- Which tool calls can mutate or delete data?
- Are tool inputs validated server-side?
- Are outputs treated as untrusted content?
- Is every call auditable?
- Can the client restrict available tools?
The agent host should not equate “discovered through MCP” with “safe.” Protocol standardization improves interoperability, not the trustworthiness of every server.
Dockup’s skill encodes several safety rules: use DOCKUP_TOKEN rather than interactive login, never print credentials, discover targets with dockup services --json, use --wait, and stop on needs_confirm. The CLI reinforces those instructions by masking secrets and refusing destructive operations without explicit approval. This defense-in-depth model is described in production guardrails for AI agents.
How should versioning and failure recovery work?
Version drift is possible in both approaches, but it appears differently.
A skill can become stale when the documented command changes. The strongest mitigation is packaging the skill with the executable and updating both through one release process. Dockup follows this model. The agent can check the installed skill:
dockup skill status --json
An update refreshes the CLI and bundled skill together:
dockup update
An MCP client can discover the server’s current tool schemas, but schema compatibility does not guarantee semantic compatibility. A tool may retain the same inputs while changing authorization, side effects, latency, or output interpretation. The server should publish versions, preserve backward compatibility where possible, and return structured errors.
Failure handling also differs. A CLI offers process exit codes naturally. An MCP tool call needs an equally clear application-level result. In either case, the agent should not infer success from a transport-level acknowledgment.
A useful reliability checklist is:
| Requirement | Skill + CLI implementation | MCP implementation |
|---|---|---|
| Capability discovery | CLI schema | Server tool list |
| Structured output | JSON/NDJSON | Typed tool result |
| Failure signal | Non-zero exit + code | Explicit error result |
| Long operation | --wait / documented stream | Progress or completion protocol |
| Secret protection | Masking and stderr discipline | Server-side redaction |
| Destructive approval | CLI confirmation gate | Server policy or client confirmation |
| Audit | Platform audit log | Server and backend audit logs |
| Version check | Skill/binary status | Server metadata and schemas |
The interface should make failure harder to misreport than success.
What architecture should a production team choose?
Start by naming the actual gap.
Choose a skill-first architecture when the team already trusts and operates a CLI. Invest in its machine contract: JSON, real exit codes, stable error codes, version-aligned instructions, and confirmation. Then package the skill with that tool. This is the shortest path for Claude Code deployment and Codex deployment through Dockup.
Choose MCP-first when the capability is naturally remote, resource-oriented, or shared among many clients. Treat the server as production software: authenticate it, scope it, monitor it, and review every mutation.
Choose both when policy and connectivity are independently complex. Keep responsibilities clear. The skill should not duplicate the server implementation, and the server description should not become a sprawling operational manual.
A practical evaluation workshop
Run a small proof with one read operation, one reversible write, one long-running operation, and one destructive operation that must be blocked. Score each design on:
- How the agent discovers the operation.
- How credentials are supplied.
- How success is proven.
- How failure is categorized.
- How a human approves danger.
- How logs and audit evidence are retrieved.
- How versions stay aligned.
- How the integration is removed cleanly.
Do not decide from a diagram alone. Observe the failure paths. A design that looks elegant on the happy path may become ambiguous when a deployment times out, a server disconnects, or an instruction file is one release behind.
The Dockup CLI reference provides a concrete example of a skill-backed CLI contract. The broader AI-powered development article explains why these interfaces matter as agents take on more of the development loop.
Account for operational ownership
The integration’s owner matters as much as its architecture. A skill wrapped around a CLI usually inherits that CLI’s installation, release, and support process. The team that publishes the binary can ship its matching instructions and test them together.
An MCP server creates a separate production component. Someone must own hosting, certificates or local process startup, authentication, monitoring, incident response, schema compatibility, and dependency updates. That investment can be worthwhile when the server is a meaningful shared boundary. It is unnecessary overhead when it only forwards local calls to an already sufficient executable.
During evaluation, write down who owns each layer:
| Layer | Skill-first owner | MCP-first owner |
|---|---|---|
| Domain instructions | Skill publisher | Client prompt or companion skill |
| Executable behavior | CLI publisher | MCP server team |
| Credential handling | CLI and runtime environment | Server and client connection |
| Availability | Local executable and platform API | Server process, transport, and backend |
| Schema compatibility | CLI release process | MCP server release process |
| Incident evidence | CLI output and platform audit | Client logs, server logs, and backend audit |
This ownership table often resolves the agent skills vs MCP debate more clearly than a feature checklist.
Evaluate latency and failure surfaces
A local skill plus CLI call has a short path: agent host, process, platform API. An MCP path may add server startup, transport negotiation, remote routing, and another authentication layer. Those additions are not inherently bad, but each one creates a distinct failure surface.
Test disconnection, expired credentials, malformed inputs, partial long-running operations, and server upgrades. The agent must be able to say whether the failure occurred in the host, the protocol connection, the server, or the external platform. A generic “tool failed” result is not sufficient for production work.
For long deployments, the interface must preserve terminal-state semantics. Whether the call is a CLI --wait operation or an MCP tool with progress, the agent must not convert an acknowledgment into success. The agent skills vs MCP choice does not remove that requirement.
Plan for portability without sacrificing truth
MCP can improve portability across compatible clients because the same server advertises tools through a shared protocol. Skills can also be portable when multiple agents support the same directory and SKILL.md conventions, as Claude Code and Codex do for Dockup’s installation model.
Portability is useful only if semantics remain precise. A tool called deploy must define whether it returns when queued or when healthy. A skill instruction that says “deploy and verify” must point to a command that can actually provide that proof.
The strongest design keeps domain truth close to the executable layer and uses the higher layer to explain intent. In the agent skills vs MCP comparison, neither a standardized protocol nor a well-written instruction file compensates for an ambiguous backend operation.
Put the workflow into production
Use the smallest architecture that creates a trustworthy boundary. For Dockup, install the packaged skill and let the CLI remain the executable source of deployment truth.
npm install -g dockup-cli
dockup skill install
The first command installs the CLI. The second installs the matching Dockup skill for Claude Code and Codex. Start free at app.dockup.ai.
FAQ
Are agent skills and MCP the same thing?
No. A skill primarily provides instructions and operating knowledge. MCP provides a protocol for exposing tools, resources, and prompts through a client-server connection.
Does a SKILL.md file execute commands itself?
No. It tells the agent how to use underlying capabilities such as a CLI, files, APIs, or MCP tools. The executable interface performs the action.
When is a skill better than MCP?
A skill is often the simpler choice when a mature local CLI already provides secure, machine-readable operations and the missing piece is workflow guidance.
Can an agent use a skill and MCP together?
Yes. A skill can describe a multi-step workflow and policy while an MCP server exposes the typed tools and resources used by that workflow.
Why does Dockup ship its skill inside the CLI package?
Packaging them together lets dockup update refresh the executable and its instructions in one pass, reducing the risk that the skill describes a different command version.