Skills, plugins, and MCP
Discussions around extending AI coding assistants often treat skills, plugins, and the Model Context Protocol (MCP) as interchangeable ways of doing the same thing. In reality, they represent three fundamentally distinct architectural layers: prompt instructions, packaging, and external running processes. Distinguishing between them helps clarify how an agent acquires new context versus entirely new capabilities.
A skill is instructions
A Skilla named set of instructions, packaged as markdown, that a harness loads into the context when it looks relevant. It adds no new capability.Full glossary entryIntroduced in Skills, plugins, and MCP is essentially a directory containing a structured Markdown document. It typically includes a unique name, a concise summary description, and a set of instructions guiding the model through a specific workflow. Typical examples include documenting your team's commit conventions, detailing pre-release validation steps, or describing the schema and access patterns of an internal reporting database.
Crucially, a skill contains no executable code managed by the harness. It is pure guidance injected into the model's prompt context whenever the agent deems it relevant to the task at hand.
The architecture scales cleanly across dozens or hundreds of skills through Progressive disclosurekeeping only a name and a one-line description in the context, and loading the body only when it is needed, so many skills cost little until used.Full glossary entryIntroduced in Skills, plugins, and MCP. Instead of injecting every detailed instruction into the prompt up front, the harness only keeps the skill's name and short description in the standing context window. This baseline overhead is minimal—usually around one hundred tokens per skill. A library of one hundred registered skills might consume around ten thousand tokens of passive context. When an incoming user request matches a skill's description, the harness dynamically pulls the full instruction body into active context. Auxiliary reference files and embedded scripts remain completely unloaded until explicitly referenced, and executing a helper script contributes only its runtime output to the conversation rather than its source code.
A skill does not grant the model new underlying capabilities. If an agent lacks network access to reach your project management tracker, writing a skill that explains your issue-tracking conventions will not allow it to query the API. What a skill changes is how the model exercises its existing abilities: which tools it prioritizes, the sequence of actions it takes, and the stylistic conventions it follows.
The primary trade-off is relying on the model's judgment to trigger them. Because skills load dynamically based on description matching, an overly vague description—such as "helps with documents"—tends to either trigger indiscriminately or get ignored entirely. Crafting a skill description requires the same precision as drafting a tool description: clearly articulating both what the skill accomplishes and the precise circumstances under which it should be invoked.
A plugin is a bundle
A Plugina distributable, versioned bundle that can hold skills, slash commands, subagent definitions, hooks, and MCP server configuration together.Full glossary entryIntroduced in Skills, plugins, and MCP is a versioned, distributable software artifact. Inspecting a plugin bundle reveals a cohesive collection of components: skills, Slash commandan instruction the user invokes by name, rather than one the model chooses to load on its own.Full glossary entryIntroduced in Skills, plugins, and MCP, subagent configurations, deterministic Hooka script the harness runs when an event fires, such as after a file edit, with no model involvement in the decision to run it.Full glossary entryIntroduced in Skills, plugins, and MCP, and MCP server connection settings, all coordinated through a manifest file.
Within this bundle, components serve different operational roles. A slash command gives users a way to explicitly trigger a skill by typing its name, bypassing model inference. A hook, by contrast, executes deterministically on the local machine when predefined harness events occur—such as immediately after saving a file edit or just before executing a tool call. Because hooks execute through the harness without model deliberation, they provide a reliable foundation for enforcing style formatters, linters, and security guardrails.
The primary advantage of a plugin is standardized distribution. Without packaged plugins, rolling out shared workflows across an engineering team requires every engineer to manually copy disparate scripts and configuration files into specific local paths—a fragile process that breaks as soon as an update is published. Packaging these assets as a plugin allows teams to install and update entire toolchains through package managers and centralized marketplaces with simple version increments.
The trade-off centers on security and trust. Because plugins can execute arbitrary local hook scripts and configure MCP servers with access tokens, installing a third-party plugin carries the same operational risk as running third-party packages from npm or PyPI. Organizations managing plugin ecosystems need clear governance, package review processes, and version pinning to mitigate supply chain risks.
MCP is a running process
The Model Context Protocolan open protocol, using JSON-RPC, for connecting AI applications to external tools and data, so each integration is written once rather than once per application.Full glossary entryIntroduced in MCP in depth (MCP) is an open standard, and an MCP server is an independent operating system process implementing that specification. These servers run completely out of process: either locally as subprocesses managed by the harness over standard input and output (stdin/stdout), or remotely as standalone HTTP services over Server-Sent Events (SSE) or WebSockets. An MCP server exposes concrete tools the model can invoke, structured resources the harness can read, and prompt templates. The MCP guide explores this protocol in detail.
Unlike skills and plugins, MCP is the only mechanism that expands the model's fundamental capabilities. A skill cannot directly query a production database, and a plugin cannot do so on its own without bundling an active integration. An MCP server connects to live environments because it runs compiled code or scripts equipped with database drivers, network credentials, and socket access.
This expanded capability introduces concrete costs. The schema definitions for every connected server's exposed tools must reside in the context window across every interaction, meaning five connected servers exposing a dozen tools each will quickly establish a substantial baseline token overhead. Furthermore, every server is a long-running process requiring lifecycle management, health monitoring, and dependency maintenance. Remote servers introduce additional authentication complexity, necessitating OAuth handshakes, secure token storage, and fine-grained access policies.
Choosing the right abstraction
Deciding which mechanism to adopt depends on what the model needs to accomplish the task:
- When the model needs domain knowledge or operational procedures, write a skill. Use skills for coding guidelines, architecture runbooks, schema descriptions, and team-specific review criteria. They replace oversized static system prompts and repetitive prompt-pasting.
- When the model needs external access or runtime actions, implement an MCP server. Use MCP servers when querying internal microservices, executing database commands, or manipulating issue trackers. If the operation requires authentication secrets, network sockets, or execution environments, it belongs in an MCP server.
- When distributing tools and configuration across a team, package a plugin. Plugins are not an alternative to skills or MCP servers; they are the packaging layer used to deliver both alongside hooks and commands in a single installable unit.
Ask what the model is missing.
- The model lacks knowledge or a procedure: write a skill.
- The model lacks access to a system: use an MCP server.
- A team needs the same set-up: package it as a plugin.
- Do not add an MCP server to supply instructions. Use a skill.
- Do not add a skill to supply access. Use an MCP server.
In mature development environments, teams often converge on a common architecture: dozens of lightweight, inexpensive skills, a small handful of focused MCP servers, and an internally maintained plugin that packages both for the organization.
As organizations scale their tool ecosystems beyond a handful of servers, managing context overhead and authentication becomes its own challenge. See MCP gateways for architectural patterns that manage large-scale server deployments.
Terms introduced
- Skill: a named set of instructions, packaged as markdown, that a harness loads into the context when it looks relevant.
- Plugin: a distributable, versioned bundle of skills, slash commands, subagent definitions, hooks, and MCP server configuration.
- Progressive disclosure: keeping only a name and a description in the context, and loading the body only when it is needed.
- Slash command: an instruction the user invokes by name, rather than one the model chooses to load.
- Hook: a script the harness runs when an event fires, with no model involvement in the decision.
How providers do it
All three vendors have converged on SKILL.md for instructions and on a bundle format for
distribution. The names of the bundle, and where the files are looked for, are where they part.
| Concept | Anthropic | OpenAI | Cursor |
|---|---|---|---|
| Skill format | SKILL.md, frontmatter name and description | SKILL.md, frontmatter name and description | SKILL.md, name must match the folder |
| Personal skills | ~/.claude/skills/ | $HOME/.agents/skills | ~/.cursor/skills/ |
| Project skills | .claude/skills/ | .agents/skills | .cursor/skills/ or .agents/skills/ |
| Standing context cost | About 100 tokens per skill | At most 2% of the context for the whole list | Not published |
| Instruction layer besides skills | Skills only | AGENTS.md | Rules (.mdc), four inclusion modes, plus AGENTS.md |
| Bundle called | Plugin | Plugin | Plugin |
| Manifest | .claude-plugin/plugin.json | Bundle metadata, plus agents/openai.yaml per skill | .cursor-plugin/plugin.json |
| Bundle can hold | Skills, commands, agents, hooks, MCP, LSP, monitors, binaries | Skills, MCP servers, assets, optional UI | Rules, skills, agents, commands, hooks, MCP |
| Distribution | Marketplaces, official and community, or a private repository | First-party integrations plus a publish flow | Cursor Marketplace, team marketplaces, cursor.directory |
Most rows are confirmed. Cursor's idle skill cost, OpenAI's config.toml key for MCP servers,
and OpenAI's third-party plugin review process are all marked unconfirmed in the tabs below.
Skills travel between these three almost unchanged, so a well-written SKILL.md is portable.
Plugins do not travel at all: three manifest formats, three marketplaces, and three sets of
component directories.
- Anthropic
- OpenAI
- Cursor
What this maps to: Anthropic calls skills Agent Skills, and they are the origin of the SKILL.md convention several other vendors now follow. Claude Code adds plugins as the packaging layer, and both sit alongside MCP rather than replacing it.
| Question | Answer | Status |
|---|---|---|
| What is the skill mechanism called | Agent Skills | confirmed |
| What is the file format | A directory containing SKILL.md, with YAML frontmatter. name and description are the only required fields | confirmed |
| What are the field limits | name is 64 characters, lowercase letters, numbers and hyphens. description is 1024 characters and must say what the skill does and when to use it | confirmed |
| How does progressive disclosure work | Three levels. Metadata is always loaded, at about 100 tokens per skill. The SKILL.md body loads when triggered, under 5k tokens. Bundled files and scripts cost nothing until read or run | confirmed |
| Do bundled scripts enter the context | No. Claude runs them through bash and only the output costs tokens | confirmed |
| Where do skills live in Claude Code | ~/.claude/skills/ for personal, .claude/skills/ for a project, or inside a plugin | confirmed |
| Where do skills live on the API | Uploaded through the Skills API at /v1/skills, referenced by skill_id in the container parameter, and requiring the code execution tool | confirmed |
| Do skills sync between surfaces | No. Claude Code, the API and claude.ai each hold their own | confirmed |
| What is the plugin mechanism called | Claude Code plugins, with a manifest at .claude-plugin/plugin.json holding name, description and version | confirmed |
| What can a plugin contain | skills/, commands/, agents/, hooks/hooks.json, .mcp.json, .lsp.json, monitors/, bin/, and a settings.json | confirmed |
| How is a plugin distributed | Through a marketplace. Anthropic runs a curated claude-plugins-official and a reviewed claude-community; teams can host a private one in their own repository | confirmed |
| Are plugin commands namespaced | Yes, as /plugin-name:skill-name, so two plugins can ship a skill with the same name | confirmed |
| What does Anthropic say about trust | Use skills only from sources you created or trust. A malicious skill can direct Claude to invoke tools or run code outside its stated purpose. Enterprise organisations can turn on skill content scanning | confirmed |
Their vocabulary
| Standard term | Their term |
|---|---|
| Skill | Agent Skill, SKILL.md |
| Slash command | A skill invoked by name, or a file in commands/ |
| Hook | Hook, in hooks/hooks.json |
| Plugin manifest | .claude-plugin/plugin.json |
| Plugin registry | Marketplace |
Where to look
/plugin lists what is installed and has an Errors tab that shows a plugin whose MCP or LSP server failed to start. /context shows what is currently occupying the window, including custom agents.
Last verified: 2026-09-09 against platform.claude.com/docs/en/agents-and-tools/agent-skills/overview and code.claude.com/docs/en/plugins.
What this maps to: OpenAI uses the same two words. Skills are SKILL.md directories that Codex and ChatGPT both read, and plugins are the distributable bundle that can carry skills, MCP servers and optional UI together.
| Question | Answer | Status |
|---|---|---|
| What is the skill mechanism called | Skills, defined in SKILL.md with YAML frontmatter | confirmed |
| What frontmatter is required | name and description. The guidance is that the description should say when the skill should and should not trigger | confirmed |
| Where does Codex look for skills | .agents/skills in the working directory or repository root, $HOME/.agents/skills for the user, /etc/codex/skills for an administrator, and a set bundled by OpenAI. The closest scope wins | confirmed |
| Is there progressive disclosure | Yes. The skills list carries each skill's name and description, documented as taking at most 2% of the context, and the full SKILL.md loads only once Codex selects it | confirmed |
| Is there a plugin mechanism | Yes. A plugin can include one or more skills and can bundle MCP servers, assets, and optional UI | confirmed |
| How does a skill declare an MCP dependency | Optional metadata in agents/openai.yaml, under dependencies.tools, with type: "mcp", a value naming the server, and a url | confirmed |
| Where are Codex MCP servers configured | Codex reads config.toml; the exact table name was not checked today | unconfirmed; what is the key in config.toml, and does it accept stdio as well as HTTP? |
| Is there a project instructions file as well | AGENTS.md is the convention Codex reads for repository instructions | unconfirmed; not read against OpenAI's own documentation today |
| Is there a marketplace or directory | OpenAI ships first-party plugin integrations and publishes a build-and-publish flow | unconfirmed; how a third party lists a plugin, and who reviews it, was not checked today |
Their vocabulary
| Standard term | Their term |
|---|---|
| Skill | Skill, SKILL.md |
| Plugin | Plugin |
| Skill dependency on a server | dependencies.tools in agents/openai.yaml |
| Repository instructions | AGENTS.md |
Where to look
Codex reports which skills it discovered at the start of a session, which is the quickest way to tell whether a scope is being picked up at all.
Last verified: 2026-09-09 against learn.chatgpt.com/docs/build-skills and developers.openai.com/apps-sdk/.
What this maps to: Cursor has three layers rather than two. Rules came first and are the instruction layer, Skills are the SKILL.md layer added later, and Plugins are the bundle that ships either of them along with agents, commands, hooks and MCP servers.
| Question | Answer | Status |
|---|---|---|
| What is the instruction mechanism called | Rules. Project rules are .mdc files in .cursor/rules/; AGENTS.md in the project root works as a plain-markdown alternative with no frontmatter | confirmed |
| How does a rule get included | Four modes: Always Apply, Apply Intelligently (the agent judges from the description), Apply to Specific Files (glob match), and Apply Manually (the user @-mentions it) | confirmed |
| Does Cursor support skills as well | Yes. Agent Skills are SKILL.md files with YAML frontmatter, where name is required and must match the parent folder name | confirmed |
| Where do skills live | ~/.cursor/skills/ for personal skills, and .cursor/skills/ or .agents/skills/ anywhere inside a repository, including nested subdirectories | confirmed |
| Can a skill bundle code | Yes. A scripts/ directory, referenced from SKILL.md by relative path | confirmed |
| Is there a plugin mechanism | Yes. A bundle with a manifest at .cursor-plugin/plugin.json, requiring at least a name | confirmed |
| What can a plugin contain | Rules (.mdc), skills, agents, commands, MCP servers, and hooks | confirmed |
| How are plugins installed | Through the Customize panel in the sidebar. Sources are the Cursor Marketplace, a team marketplace on Teams and Enterprise plans, cursor.directory, or ~/.cursor/plugins/local for testing | confirmed |
| Can plugins be scoped | Yes. Installed plugins filter by user, workspace, or team scope | confirmed |
| Is there progressive disclosure for skills | Implied by the design, but Cursor's own token figures were not read today | unconfirmed; what does an installed skill cost while idle? |
Their vocabulary
| Standard term | Their term |
|---|---|
| Skill | Agent Skill, SKILL.md |
| A rules file the agent may pull in | Rule, .mdc, or AGENTS.md |
| Plugin manifest | .cursor-plugin/plugin.json |
| Plugin registry | Cursor Marketplace, team marketplace, cursor.directory |
Where to look
The Customize panel in the sidebar lists installed plugins with their scope, which is where a rule or skill that "should" be active but is not usually turns out to be installed at the wrong scope.
Last verified: 2026-09-09 against cursor.com/docs/context/rules and cursor.com/docs/plugins.