What is the difference between an agent skill and an MCP server?

A skill packages instructions, scripts, templates, and references for a repeatable workflow. An MCP server exposes live tools, resources, and prompts over a protocol. Skills teach the agent how to work; MCP gives it a typed connection to external capabilities and data.

What does an Agent Plugin contain?

Agent Plugins 1.0 can package portable skills and MCP server configuration under one manifest. Clients may also support namespaced, client-specific components such as agents, hooks, commands, or automation templates.

Can a skill call an MCP tool?

Yes. A skill can instruct the agent when and how to use tools supplied by an MCP server. The skill should reference stable capabilities and avoid depending on undocumented client-specific tool names when portability matters.

Should every API integration use MCP?

No. Use MCP when several agents need a discoverable, governed tool or data interface. A small deterministic script or existing CLI may be simpler for a repository-specific task that does not need a persistent external service.

Are agent plugins portable across all coding agents?

The standard makes skills and MCP configuration portable component types, but clients may support different extensions and behaviors. Test the portable core in each target client and treat client-specific namespaces as optional layers.

How do teams reduce coding-agent context bloat?

Keep always-on instructions short, use skill descriptions for discovery and load detailed references only when needed, limit enabled MCP tools, and package related capabilities without activating every component for every task.

What should teams review before installing an agent plugin?

Review the publisher, plugin manifest, skill instructions, scripts, hooks, MCP server commands, requested environment variables, filesystem access, network destinations, update policy, and any client-specific extension directories.

Skills vs MCP vs Agent Plugins for Coding Agents

Coding agents can now be extended through skills, Model Context Protocol servers, and installable plugins. These terms are often treated as three versions of the same feature. They solve different problems.

A skill is a task-specific package of instructions and supporting files. MCP is a protocol for discovering and calling live tools, resources, and prompts. An Agent Plugin is a distribution unit that can bundle skills and MCP configuration, with room for client-specific additions.

The choice affects context usage, permissions, portability, and maintenance. Putting a style guide behind an MCP server adds operational weight. Putting a production database query into a Markdown skill gives instructions without a governed execution path. Packaging unrelated capabilities in one plugin makes installation easy and review difficult.

This guide gives each layer a clear job, then shows how to combine them without turning the agent into an unreviewable collection of prompts and tools.

The Short Decision Rule

Start by asking what the agent is missing.

Use a skill for repeatable know-how

Choose a skill when the missing capability is a workflow, standard, or body of domain guidance. Examples include preparing a release, testing a login flow, applying a repository's migration policy, or producing a document in a house format.

The skill can include a SKILL.md, scripts, templates, examples, and references. Compatible agents discover it from its name and description, then load the detailed material when the task matches.

Use MCP for live systems

Choose MCP when the agent must discover or invoke an external capability at runtime. Examples include reading an issue tracker, querying a database, searching current cloud documentation, opening a browser, or changing an infrastructure resource.

MCP servers expose typed tools and data through a client-server protocol. Authentication, transport, availability, and authorization become part of the design.

Use a plugin for distribution

Choose an Agent Plugin when several related components should be installed, versioned, and removed as one product. A cloud-development plugin may include onboarding skills plus an MCP server for current documentation. A testing plugin may pair a test workflow with a reporting service.

A plugin does not replace the components inside it. It packages them.

Need	Primary choice	Reason
Teach a repeatable repository workflow	Skill	Instructions and local resources load when relevant
Read or change a live external system	MCP server	Typed, discoverable runtime interface
Ship several related capabilities together	Agent Plugin	One manifest, version, and installation unit
Enforce a deterministic lifecycle action	Client hook or CI	The action should not depend on model choice
Apply a short rule to every task	Repository instructions	Always-on context is appropriate when it is truly universal

What an Agent Skill Is

The Agent Skills specification defines a directory centered on SKILL.md. The file begins with YAML frontmatter that includes a name and description, followed by instructions the agent should follow.

Discovery stays small

The name and description tell the client when a skill may apply. The full body is loaded only after discovery, and linked resources can be read later as the workflow needs them.

This progressive pattern matters. A team can install many skills without placing every page of guidance into every prompt. Google describes the same motivation in its skills repository: condensed expertise can reduce the context bloat caused by loading broad documentation or tool definitions before they are needed.

A skill can contain executable support

A useful skill often includes more than prose.

release-validation/
  SKILL.md
  scripts/
    check-version.sh
    verify-changelog.ts
  references/
    release-policy.md
  templates/
    release-notes.md

The instructions can tell the agent which script to run, how to interpret its output, and what to report. The script remains deterministic code; the skill provides the judgment about when it applies and how the steps fit together.

A skill is not a remote service

A skill does not create a standard network connection, credential exchange, or runtime tool discovery mechanism. It may tell the agent to use an existing CLI or MCP tool, but the skill itself is packaged know-how.

This makes skills easy to keep beside a codebase. It also means maintainers must avoid hiding unsafe shell behavior behind friendly Markdown instructions.

What MCP Provides

Model Context Protocol defines how an AI application connects to context and actions supplied by servers.

The host, client, and server have separate roles

The MCP host is the AI application. It creates a client for each configured server. The server exposes capabilities and handles requests.

Servers can run locally over standard input and output or remotely over Streamable HTTP. The transport affects authentication and operations, while the data layer defines the exchanged methods and structures.

Tools, resources, and prompts are distinct primitives

The current MCP architecture defines three core server primitives:

Tools are executable functions for actions such as API calls, file operations, or database queries.
Resources provide contextual data such as schemas, records, documents, or API responses.
Prompts are reusable interaction templates.

Clients discover what a server provides, then retrieve or call the appropriate primitive. Tool inputs use JSON Schema, giving the host a machine-readable contract before execution.

MCP introduces an operational boundary

A remote server needs authentication, authorization, rate limits, logging, version compatibility, incident handling, and availability targets. A local server may start a process with filesystem and environment access.

Those costs are justified when several agents need the same live interface or when a system owner wants one governed integration. They are unnecessary for every small workflow.

What Agent Plugins 1.0 Packages

The Agent Plugins specification version 1.0.0 defines a portable package layout with a root manifest.

Portable components have standard locations

A conforming package uses plugin.json for metadata. Skills live in skills/, and MCP server configuration lives in mcp.json.

cloud-development/
  plugin.json
  skills/
    project-onboarding/
      SKILL.md
    architecture-review/
      SKILL.md
  mcp.json

The manifest declares the specification schema, package identity, version, and other metadata. The client discovers skills and MCP configuration from their defined paths.

Client-specific components use namespaces

Some clients support custom agents, hooks, commands, rules, or automation templates. Agent Plugins allows client-owned data under reverse-domain namespaces.

VS Code, for example, documents Copilot-specific components under com.github.copilot/. Other clients can ignore that directory and still load the portable skills and MCP definitions.

cloud-development/
  plugin.json
  skills/
  mcp.json
  com.github.copilot/
    agents/
    hooks/
      hooks.json

This is graceful portability, not identical behavior everywhere. The core travels; optional features depend on the client.

Packaging creates a trust decision

One installation may add Markdown instructions, executable scripts, hooks, and processes that connect to remote services. Users need to review the whole package, including files absent from its marketplace description.

The specification requires filesystem-resolved paths supplied by a plugin to remain inside the plugin root. That guards package traversal, but it does not prove that included scripts or remote servers are safe.

Compare Context and Tool Costs

Agent quality can decline when every capability is always present.

Instructions consume attention

Always-on instructions compete with the task, conversation, code, and tool output. Long universal rule files encourage contradictions and make it hard to know which sentence changed the result.

Skills improve the situation through discovery and progressive loading. Keep descriptions precise enough that the agent loads the skill for the right work and ignores it elsewhere.

Tool definitions also consume context

An MCP client commonly discovers tools and supplies their names, descriptions, and schemas to the model. Connecting several broad servers can produce hundreds of tools before the task begins.

The current MCP documentation describes progressive tool discovery for clients that federate many servers. Even without that feature, teams can disable irrelevant servers, expose smaller tool groups, or put a gateway in front of approved capabilities.

Plugins should not mean activate everything

A plugin is a convenient catalog and dependency unit. Installation should not automatically make every skill body and every MCP tool part of each prompt.

Good clients retain component activation rules. Good plugin authors keep the bundle cohesive so the user can predict what becomes available.

Decide with a Capability Matrix

The same requirement can look different depending on freshness, risk, and reuse.

Requirement	Skill	MCP	Plugin
Repository coding conventions	Strong fit	Poor fit	Package if distributed with related workflows
Multi-step release procedure	Strong fit	Add only for live release systems	Strong if shipped with tools and templates
Current issue-tracker data	Can explain process	Strong fit	Package client config with issue workflow
Production database action	Can define safeguards	Strong fit with narrow tools	Package only after serious review
Static framework examples	Strong fit	Usually unnecessary	Useful for a maintained vendor kit
Current vendor documentation	Skill can route retrieval	Strong resource/search fit	Strong combination
Post-edit formatting command	Script in skill or hook	Usually unnecessary	Client extension may package hook
Cross-client installation	Skill spec helps	MCP config can travel	Primary purpose of the plugin format

Ask whether the information changes

Stable procedures and examples fit local resources. Data that changes by the minute belongs behind a live tool or resource.

Current documentation sits in the middle. A skill can teach the agent how to search and apply it, while an MCP documentation server supplies the latest source material.

Ask whether the agent must act

Reading a policy needs context. Creating a cloud project needs a tool with identity, permissions, and an audit trail.

Do not turn an instruction into authority. A sentence saying the agent may deploy does not replace credentials and server-side authorization.

Ask how many environments need it

A one-repository script may be easiest to maintain locally. A capability used across editors, coding agents, and internal platforms benefits from a protocol or portable package.

Portability carries testing work. Every target client may interpret activation, approvals, environment variables, and extensions differently.

A Layered Architecture That Holds Up

Most mature setups use all three layers with narrow responsibilities.

Repository instructions define the baseline

Keep always-on guidance short: how to build and test, where architecture decisions live, what directories are sensitive, and which actions require approval.

If a rule applies only to deployments or database migrations, move it into the relevant skill. Universal context should be universal.

Skills orchestrate workflows

A deployment skill can inspect the repository, select the correct runbook, invoke tests, request approval, call deployment tools, and verify the result. It explains the sequence and stopping conditions.

The skill should refer to capabilities by purpose where possible. Hard-coding one client's display name for a tool makes reuse brittle.

MCP connects live systems

Expose narrow operations such as deployment_get, deployment_create_preview, and deployment_rollback. Give each operation a clear schema and enforce authorization on the server.

Avoid one universal run_shell or call_api tool for a sensitive platform. Broad tools push security decisions into prompts and make audits harder.

Plugins distribute the tested combination

Once the deployment skill and MCP server work together, package them with version constraints, setup documentation, and optional client integrations.

The plugin becomes the unit teams install. The skill remains the workflow, and the MCP server remains the live interface.

The Google Cloud Plugin as a Concrete Example

Google's September 2026 developer plugin demonstrates why the layers are complementary.

Skills provide platform procedures

The bundle includes guidance for onboarding, authentication, project configuration, architecture, and guarded use of gcloud. These tasks benefit from vendor-maintained instructions and examples.

Google's skills work also emphasizes progressive loading so every piece of cloud guidance does not occupy the context window at once.

MCP supplies current documentation

The plugin includes configuration for Google's Developer Knowledge MCP server. The server gives agents a live source of official developer documentation instead of freezing all product details inside the plugin release.

This separates procedure from freshness. A skill can say how to evaluate an IAM choice, while the documentation service supplies current product facts.

The plugin makes the pair installable

Users install one named package rather than copying several skill folders and hand-editing an MCP configuration. The Agent Plugins layout aims to keep that package usable across multiple coding-agent clients.

The example also shows the remaining friction: clients still have different installation commands and authentication setup. A shared package format reduces duplication without erasing client behavior.

Avoid the Tool Coupling Trap

Coupling appears when a workflow assumes one exact server, tool name, or client implementation.

Depend on a capability contract

Document what the workflow needs: search official cloud documentation, inspect the active project, or create a preview environment. Map that need to available tools during setup.

If the skill directly embeds a long list of vendor-specific tool identifiers, a server update can break the workflow even when equivalent capabilities still exist.

Keep vendor facts close to the vendor source

Do not copy changing quotas, model lists, regions, or pricing into a skill unless the release process updates and tests them. Point the workflow at official documentation through a resource or search tool.

Keep stable safety rules local. A rule requiring explicit confirmation before deleting a project should not disappear because a documentation service is unavailable.

Version the bundle and components

Record which skill release was tested with which MCP server behavior. Use semantic versions for plugin changes and describe breaking tool or configuration changes.

Remote servers may evolve independently from installed files. Capability discovery helps, but end-to-end contract tests are still needed.

Security Review by Layer

Each layer introduces a different kind of risk.

Review skills as code and policy

Read the instructions for hidden behavior, unsafe approvals, broad destructive commands, and requests to expose secrets. Inspect every referenced script and template.

Skills can change agent judgment even when they never execute a program. A malicious instruction can redirect tool use, weaken review, or encourage data disclosure.

Review MCP as an application integration

Check the server publisher, source, transport, authentication, scopes, data handling, and tool descriptions. For local servers, inspect the command, package source, working directory, and environment variables.

For remote servers, require TLS, narrow tokens, tenant-aware authorization, request logging, rate limits, and a revocation path. The model must not receive raw credentials.

Review plugins as a supply chain

A plugin can combine the previous risks and add client-specific hooks. Verify the manifest schema, repository, signed or pinned release where available, contents, update policy, and ownership.

VS Code warns that plugin hooks and MCP servers may run code on the local machine. Treat installation like adding a developer tool, not like bookmarking documentation.

Separate installation from approval

Installing a capability should not grant every action automatically. Keep human confirmation or policy checks for high-impact changes such as deletion, payment, production deployment, and access modification.

The plugin declares what exists. The client and service decide what may run.

Build a Skill Without Hiding Too Much

A skill should make a workflow clearer to maintainers as well as agents.

Write a precise description

The description drives discovery. State both the capability and the trigger.

---
name: validate-database-migration
description: Validate a proposed Postgres migration against a disposable branch. Use when a change adds or modifies SQL migration files.
---

Avoid descriptions such as "helps with databases." They load for unrelated tasks and provide little signal about the expected outcome.

Put deterministic checks in scripts

Let a script find changed migration files, run a linter, apply them to a disposable database, and report machine-readable results. Let the skill decide when to run the script and how to respond to failure.

This division reduces prompt length and prevents the model from reimplementing parsing logic differently on every run.

Route to live tools explicitly

Name the required capability and explain its permission boundary.

Use the approved database-branch tool to create an isolated child from the sanitized preview parent. Never use a production connection string. Ask for confirmation before deleting a branch you did not create in this run.

The MCP server must still enforce the rule. Instructions improve agent behavior; authorization provides the guarantee.

Design an MCP Server the Skill Can Use

The server interface determines how much judgment the model must supply.

Prefer task-shaped tools

create_preview_branch is safer and easier to describe than execute_database_admin_command. Its schema can require a repository and pull-request number while the server selects the approved parent and naming policy.

Task-shaped tools also produce better audit events because the operation has business meaning.

Return structured results

Return stable identifiers, state, safe URLs, and explicit error categories. Do not make the skill parse a paragraph to find a branch ID.

{
  "branchId": "br_preview_412",
  "state": "ready",
  "expiresAt": "2026-09-27T12:00:00Z",
  "consoleUrl": "https://console.example/branches/br_preview_412"
}

Keep secrets out of tool output. The server or runtime should attach credentials to downstream requests without exposing them to the model.

Limit discovery noise

Split very large servers by domain or support filtered discovery. Tool names and descriptions should explain when to use the operation and when not to use it.

Remove deprecated tools after a migration period. A growing list of aliases gives the model more chances to choose the wrong one.

Package and Test a Plugin

Distribution adds another quality gate.

Keep the bundle cohesive

A plugin named postgres-release may reasonably include migration validation, schema review, branch management, and database documentation. Adding social posting and browser design tools to the same package makes permissions and activation hard to reason about.

Separate plugins can depend on a shared foundational plugin when clients support that model, or document the required companion capability.

Test the portable core first

Validate plugin.json against the Agent Plugins schema. Confirm that skills are discoverable, referenced files stay inside the package, and mcp.json works in every target client.

Then test namespaced extensions separately. A plugin can remain useful in a client that ignores its custom hook or agent definition.

Test behavior, not installation alone

Run representative prompts and verify which skill activates, which tools become visible, what approvals appear, and what files or network destinations are accessed.

Include negative tests. The agent should not load a deployment skill for a documentation edit, call production tools during preview validation, or continue after a denied approval.

Governance for Teams

Individual experimentation becomes an organizational dependency quickly.

Maintain an approved catalog

Record publisher, repository, owner, purpose, version, review date, requested permissions, MCP endpoints, and supported clients. Give teams a supported install path instead of asking every developer to evaluate marketplace packages independently.

An approved plugin may still contain optional components. Document which ones the organization enables and why.

Pin and update deliberately

Automatic updates reduce maintenance but can change instructions and executable behavior between two agent runs. Pin production-sensitive plugins or use a staged channel that tests updates before broad rollout.

Track remote MCP server changes too. An installed plugin version may point to a service whose tool catalog changes without a local package update.

Observe outcomes

Measure skill activation, tool calls, denials, failures, latency, and repeated human corrections. High activation with low success may mean the description is too broad or the workflow is stale.

Keep prompts and tool payloads under the same privacy rules as source code and production logs. Observability should not become a second copy of secrets or customer data.

A Practical Adoption Sequence

Teams do not need to design a marketplace on day one.

Put concise repository-wide rules in the agent instruction file.
Identify one repeated workflow with a clear start and finish.
Package it as a skill with a precise description and deterministic scripts.
Test activation on tasks that should and should not use it.
Add MCP only when the workflow needs current external data or governed actions.
Narrow the MCP tools and enforce permissions on the server.
Run end-to-end tests for success, denial, timeout, and malformed output.
Package related, stable components as a plugin when more than one team or client needs them.
Validate the portable core in each supported client.
Place client-specific additions in namespaced extensions and make them optional.
Publish through an approved catalog with owners and version policy.
Review usage and remove components that add more context or risk than value.

For implementation details around MCP security, see Implementing Model Context Protocol for Secure Agents. Secure TanStack AI MCP OAuth covers per-user authorization, and AI Coding Assistants Can't Read Your Code explains why explicit project context still matters.

Skills, MCP servers, and plugins work best as layers. Keep knowledge in a skill, live authority behind MCP, and distribution in a plugin. When one layer starts doing all three jobs, context grows, permissions blur, and maintenance gets harder.