Here’s a skill we’d already written, unchanged by packaging:

Note what line 1 of the Steps assumes: a running MCP server. That dependency is the thing packaging fixes.

The migration is one file at the root:

Both fields are required, and that’s the whole minimum. Names run 1 to 64 characters of lowercase alphanumerics, hyphens and periods, must start and end alphanumeric, and can’t contain – or … So acme.reports is fine, while My-Plugin, -start and has–double are not.

When you’re ready to publish rather than test, the manifest takes metadata too. The schema is closed: ten top-level fields are permitted and nothing else (full field reference).

That’s nine of the ten. The last is extensions, for client-specific data, which comes later. author also takes an optional email.

version should be SemVer and license should be SPDX, though a client won’t reject you for malformed strings. Wrong JSON types are a different matter: a number where a string belongs is fatal even on an optional field. Exactly two schema violations are non-fatal, an unknown top-level field and an extensions value that isn’t an object. Both get reported and ignored, and the plugin still loads. Everything else is fatal and the client refuses the whole package.

One rule catches people migrating to a large skills library. Discovery goes exactly one level deep: clients read the immediate subdirectories of skills/ and don’t recurse (discovery rules). If you’ve been grouping skills into category folders, those skills stop existing the moment you package them, with no error explaining why.

Your tools travel with your expertise

mcp.json sits beside your manifest and declares the servers your skill needs. It carries only two top-level keys, and every server declares its transport explicitly:

Three transports exist, and the required fields differ (MCP server reference):

command is one executable token, not a shell command. Either a bare name resolved by platform search rules, or a plugin-relative path starting with ./. Placeholder expansion deliberately does not apply to it, so a bundled binary is found by that ./ path and nothing else.

The two placeholders are environment variables the client provides to stdio subprocesses, and the difference between them matters more than the names suggest:

Write into PLUGIN_ROOT and your state disappears the next time someone updates the plugin. Both expand in args, env values and cwd only. Not in environment keys, not in command, not in remote URLs, and not in headers. Expansion is textual and single-pass, so nothing nests.

Headers are literal package data that anyone who downloads your plugin can read, which is why the spec forbids putting credentials in them. Agent Plugins 1.0.0 defines no portable OAuth or credential-reference field at all. Authentication stays client-managed.

Components fail independently

If your MCP server can’t start, your skills still load. The spec requires the client to keep loading everything else, and says it should report the failure rather than swallow it. For an entry that is invalid or declares a transport the client doesn’t support, the spec goes further: the client must skip that entry and carry on.

Failure is scoped at three levels (failure boundaries), and knowing which one you’ve hit is most of the debugging:

Absence is tolerated too. A plugin with no mcp.json isn’t broken, because a missing component location is not an error. A location in the wrong form, like mcp.json as a directory, invalidates that component type while the rest keeps loading.

This is the difference between a bundle and a package format. A bundle is all-or-nothing. A package format degrades in parts, which is the only reason it’s safe to hand someone a folder containing both your instructions and a server that has to reach the network.

Client-specific behavior without forking

Hooks, commands, subagents and rules aren’t in v1. They’re too client-specific to standardise without freezing someone’s roadmap. Rather than forcing a lowest common denominator, the spec hands each client a namespace it owns.

A client namespace can appear as a reverse-domain directory at the root, as a key under extensions in the manifest, or both. Neither one requires the other.

Clients ignore namespaces they don’t recognise, so the portable core stays portable. The same mechanism could re-fragment plugins one directory down if every client leans on its own namespace instead of the core, which is the thing to watch as v2 gets debated.

One folder, every client

Two Google products ship as Agent Plugins today. Agents CLI packages our expert skills for agent building, evaluation, deployment, observability and publishing. The Data Agent Kit brings Spanner, Cloud SQL and AlloyDB plugins, plus a starter pack covering BigQuery, into whichever coding agent you already use.

In Antigravity CLI that is one command:

Every other client still has its own installer, which is the gap the spec is closing:

The set of clients that read the portable format is growing, and it is published and kept current at agent-plugins.org/compatible-clients.

One caution from doing this ourselves. Conformance permits partial implementations: a client must support at least one of stdio and streamable-http and should support both, while sse is optional. Build on either modern transport and you are safe across everything listed today, but test your plugin in a second client before you promise it works there.

Deciding what to package

Not everything needs a plugin. A single skill with no tools is fine as a skill. One server for one client is simpler as a plain MCP config. Reach for a plugin when instructions and tools have to arrive together, in more than one place.

When it doesn’t load

Every failure we hit was silent in practice, though only the first is silent by design: a directory nested too deep is never discovered, so there’s nothing for a client to report. For an invalid SKILL.md the spec says the client should report it, and the clients we tried didn’t. Each has a distinct signature:

There’s no standard validator yet. The project’s non-normative future-considerations doc floats a plugin linter, and conformance test suites aimed at client implementations, as things a future version may define. Nothing is committed. For now the check is loading the plugin in a real client and reading the diagnostics.

What doesn’t travel yet

Credentials are the first gap. Plugins must not embed secrets, and there’s no portable field to reference them either, so anything behind an authenticated gateway still needs per-client setup. The folder moves; the authentication stays behind.

The second is naming collisions with formats that already exist. Claude Code uses .claude-plugin/plugin.json and .mcp.json. Antigravity uses mcp_config.json. These sit next to the portable layout rather than inside it. Expect a transition period where a repo carries both, and check which one a client is actually reading before you debug a plugin that was never loaded.

Two status notes worth carrying: ADK’s Skills support is still experimental (Python v1.25.0, TypeScript v0.6.1, Go v1.2.0), and Agent Plugins 1.0.0 is published as a Working Draft.

Get started today

Build a valid plugin in about a minute:

Then work outward from there:

• Convert something real. Point it at a skill you’ve already written. Check nothing sits deeper than one level under skills/.

• Add its tools. Write mcp.json. Use a ./ path for a bundled binary, ${PLUGIN_ROOT} for assets you ship, and ${PLUGIN_DATA} for anything you write.

• Open it in a second client and confirm what actually loaded, not what should have.

• Add publishing metadata once it works: version, license, repository, keywords.

• Install ours, Agents CLI and the Data Agent Kit, and read the specification

If you liked this article, don’t miss out on our previous article 7 rules for self-improving agent loops every AI engineer should know. And follow along for more.