Agent Plugins 1.0: Portable AI Skills and MCP Guide

Direct answer: Agent Plugins 1.0 is a published, vendor-neutral package format for distributing Agent Skills and MCP servers. A conforming plugin uses a root plugin.json, puts skills under skills/, and can define MCP servers in mcp.json. It solves the packaging and discovery mismatch between agent clients; it does not create a universal installer, permission system, sandbox, marketplace, or user interface.

Key takeaways

• The portable core is deliberately small: Agent Skills and MCP servers.
• plugin.json is required and must declare the canonical 1.0.0 schema.
• A client-specific extension namespace can carry features that are not portable.
• Installation, approvals, permissions, provenance, and sandboxing remain client responsibilities.
• Treat a plugin like executable supply-chain input: inspect scripts, MCP commands, network access, and publisher provenance before enabling it.

Why Agent Plugins 1.0 matters

AI coding clients increasingly support the same underlying building blocks—skills that load instructions and resources on demand, plus MCP servers that expose tools and data. The packaging around those components has not been consistent. A skill may need to be moved or wrapped differently for VS Code, Copilot CLI, Codex, Cursor, or another harness.

Agent Plugins 1.0 defines an interoperability floor. Authors can publish one directory containing the portable pieces, while clients retain control over installation and their own extensions. This is a more useful promise than “every agent behaves identically”: the standard makes package contents predictable without pretending that runtime policy is universal.

The official specification is published at version 1.0.0, and the project describes itself as open and vendor-neutral. VS Code documents support for Agent Plugins alongside its existing Copilot and Claude formats. GitHub previously documented Agent Skills as folders containing instructions, scripts, and resources that Copilot loads when relevant, so the new package format builds on an already-used component model rather than replacing it.

The package model

A minimal plugin can look like this:

1hello-plugin/
2├── plugin.json
3└── skills/
4    └── greet/
5        └── SKILL.md

The manifest is intentionally closed at the top level. A minimal valid plugin.json is:

1{
2  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3  "name": "hello-plugin"
4}

Useful optional metadata includes version, description, author, homepage, repository, license, and keywords. Client-specific metadata belongs under extensions, using a reverse-domain namespace such as com.example.client.

A skill lives in its own directory and uses a SKILL.md file. For example:

1---
2name: greet
3description: Greet the user and offer help.
4---
5
6Greet the user and offer help. Keep the response concise and friendly.

The client decides how that skill is exposed to the model or user. The standard specifies discovery and package structure, not the chat UI or activation wording.

What is portable—and what is not?

This boundary is the most important implementation detail. A plugin can be portable while still having client-specific behavior. Unsupported clients should ignore an extension namespace rather than invent semantics for it.

A practical plugin with a skill and MCP server

For a real project, start with the portable core and add client-specific features only when necessary:

1repo-review-plugin/
2├── plugin.json
3├── skills/
4│   └── review-pull-request/
5│       ├── SKILL.md
6│       └── references/
7│           └── checklist.md
8├── mcp.json
9└── com.example.client/
10    └── README.md

Example manifest:

1{
2  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
3  "name": "repo-review-plugin",
4  "version": "0.1.0",
5  "description": "Review pull requests against a repository checklist.",
6  "repository": "https://github.com/example/repo-review-plugin",
7  "license": "MIT",
8  "keywords": ["code-review", "agent-skill", "mcp"]
9}

Example skill:

1---
2name: review-pull-request
3description: Review a pull request for correctness, tests, security, and maintainability.
4---
5
61. Read the repository contribution and security guidance.
72. Inspect the diff and identify behavior changes.
83. Check tests for changed paths; do not claim a test passed unless it ran.
94. Report findings with file paths, severity, and a concrete fix.
105. Separate verified findings from questions and follow-up suggestions.

The portable MCP configuration should use the schema and transport supported by the target clients. Keep commands and paths explicit, pin package versions where possible, and avoid putting secrets directly in the plugin repository. If an MCP server is local, constrain its working directory and file access in the client’s policy as well as in the server implementation.

Architecture: where the standard stops

The package format covers the left side. The right side is deliberately outside the portable contract. This means two clients may load the same skill but apply different approval prompts, environment handling, logging, or tool restrictions.

Secure implementation checklist

Before publishing or installing a plugin:

1. Review every executable path. Inspect scripts referenced by skills and MCP commands. Reject path traversal and unexpected downloads.
2. Pin dependencies. Use lockfiles or immutable versions for package managers and container images.
3. Separate data from code. Keep writable state out of the package and avoid granting the server access to the whole home directory.
4. Minimize MCP tools. Expose read-only tools by default; split destructive operations into separate, explicitly approved servers.
5. Keep secrets external. Use the client’s environment or secret manager. Never commit API keys to plugin.json, SKILL.md, or examples.
6. Test with a disposable workspace. Run the skill and server against non-sensitive fixtures before enabling them in a production repository.
7. Record provenance. Preserve the source repository, commit or release, license, review date, and expected permissions.

This matters because VS Code warns that plugins can include hooks and MCP servers that execute code on the developer’s machine. Agent Plugins 1.0 standardizes the package, not a sandbox. The specification’s future-considerations material discusses permissions, signatures, provenance, secret handling, and enterprise auditing as possible future work; those are not guarantees of the current format.

For broader MCP risks, pair this guide with the MCP tool-server threat-modeling guide. For agent harness differences, see the AI coding agents, CLI, IDE, skills, and plugins guide.

Migration strategy for existing plugins

Do not rewrite a mature client plugin in one pass. Use this sequence:

1. Inventory existing skills, MCP servers, hooks, commands, and custom agents.
2. Move only reusable skills into skills/<skill-name>/SKILL.md directories.
3. Create a root plugin.json with the canonical schema and a stable package name.
4. Convert MCP definitions to the portable mcp.json format and test each transport separately.
5. Keep hooks, slash commands, and custom agents in the client’s extension namespace or existing client format.
6. Validate the package in each target client and compare tool permissions, environment variables, and approval behavior.
7. Publish a changelog that states what is portable and what remains client-specific.

This incremental approach avoids the common mistake of claiming that a plugin is cross-client when only its skill files are portable.

Common errors and debugging

The client ignores the plugin. Check that plugin.json is at the root, is valid JSON, includes the exact 1.0.0 $schema value, and has a non-empty name.

The skill does not appear. Confirm the path is skills/<name>/SKILL.md, the file has valid frontmatter, and the client actually supports Agent Skills. Check the client’s plugin or skill logs.

The MCP server fails to start. Validate mcp.json, the selected transport, executable permissions, working directory, and required environment variables. Run the server directly in a disposable environment before attaching it to an agent.

A hook or slash command disappears. That is expected if you moved it into the portable core. Those capabilities are client-specific and need the target client’s documented format or extension namespace.

The same skill behaves differently across clients. Compare model context injection, activation rules, tool approvals, filesystem roots, and environment variables. Portability of package layout does not imply identical runtime semantics.

FAQ

Does Agent Plugins replace MCP?

No. It packages MCP server definitions alongside Agent Skills. MCP remains the protocol for connecting agents to external tools and data.

Can I install one plugin everywhere today?

Only where a client supports Agent Plugins 1.0 and the component types you use. Check the client’s current documentation; support and installation UX can vary.

Does the standard sandbox plugin code?

No. A client may sandbox or restrict execution, but Agent Plugins 1.0 itself is a package and discovery contract.

Should every plugin include an MCP server?

No. A skill-only plugin is often safer and simpler. Add MCP only when the workflow needs external tools or data.

Is plugin.json a permission file?

No. It identifies the package and its metadata. Permissions, approvals, secret handling, and auditing belong to the client and deployment environment.

Conclusion

Agent Plugins 1.0 is valuable precisely because it does not try to standardize all of agent development. It gives authors a predictable package for two high-value building blocks—skills and MCP servers—while leaving installation, trust, permissions, and client UX to the systems that must enforce them.

For developers, the best first move is a small, skill-only package with a strict manifest, reproducible tests, and clear provenance. Add MCP integrations only after reviewing their commands and data access. That produces a plugin that is genuinely portable rather than merely advertised as cross-client.

If you are comparing agent ecosystems, the site’s GitHub Copilot agentic workflow guide covers a client-specific workflow, while the Qwen-MM-Plugins multimodal tutorial shows a different approach: packaging specialized multimodal capabilities for agent harnesses.

Sources

• Agent Plugins Specification 1.0.0 — normative package, manifest, discovery, and conformance rules.
• Agent Plugins project site — package layout, governance, and compatible-client overview.
• VS Code: Agent plugins — official implementation, formats, MCP behavior, and security warnings.
• Visual Studio Code 1.132 release notes — official August 5, 2026 release notes for the agent host and agent-window context.
• GitHub Changelog: Copilot now supports Agent Skills — official description of Copilot’s Agent Skills model.
• VS Code Agent Plugins go cross-client — independent secondary reporting and implementation context.

Visual credit: Original Mermaid architecture diagram by Essam A.; based on the Agent Plugins 1.0 specification and official VS Code documentation. No external image used.