What version 1.0 packages

The published 1.0 specification defines two portable component types:

• Agent Skills, discovered as immediate child directories under skills/ when they contain a SKILL.md file.
• MCP servers, declared in a root-level mcp.json file.

The root manifest does not list those component paths. Their locations are fixed, which keeps discovery simple and prevents every client from interpreting a different layout.

release-tools/
├── plugin.json
├── skills/
│   └── release-check/
│       ├── SKILL.md
│       ├── scripts/
│       │   └── verify.sh
│       └── references/
│           └── checklist.md
└── mcp.json

A skill may carry scripts, references, and assets with its instructions. The MCP file may describe local stdio servers, remote streamable-http servers, or legacy sse servers. The agent client maps that portable configuration into its own runtime.

This packaging layer does not change how MCP tools work. If you need an MCP tool to render interactive controls inside a conversation, that is the separate MCP Apps extension. Agent Plugins handles installation and discovery; MCP Apps handles interactive tool output.

Build the smallest portable plugin

A minimal manifest needs a schema identifier and a name:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
  "name": "release-tools",
  "version": "1.0.0",
  "description": "Checks a release candidate against the team runbook"
}

The name must use lowercase letters, digits, hyphens, or periods. It must start and end with a letter or digit, and it cannot contain repeated -- or ... Semantic Versioning is recommended for version, although the specification does not require a valid SemVer string.

Put each skill in its own immediate child directory:

---
name: release-check
description: Check a release candidate against the repository runbook.
---

Read references/checklist.md, inspect the pending changes, and run
scripts/verify.sh before reporting any blocker.

The skill directory name should match the name in its frontmatter. VS Code's plugin documentation notes that an invalid name can cause a skill to be skipped. Keeping one responsibility per skill also makes the component useful outside the larger package.

Add mcp.json only when the workflow needs tools or external data:

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "release-status": {
      "type": "streamable-http",
      "url": "https://deploy.example.com/mcp"
    }
  }
}

The portable MCP configuration supports stdio, streamable-http, and legacy sse transports. Non-loopback remote endpoints must use HTTPS. Credentials do not belong in headers: version 1.0 leaves authorization discovery, interaction, and credential storage to the client.

Know where portability stops

Agent Plugins 1.0 lets a package include client-specific material through reverse-domain extension namespaces. A Copilot package, for example, can place agents, commands, rules, and hooks under com.github.copilot/. Other clients ignore that directory unless they implement the namespace.

release-tools/
├── plugin.json
├── skills/
├── mcp.json
└── com.github.copilot/
    ├── agents/
    ├── commands/
    └── hooks/

Put shared instructions and tool connections in the portable core. Lifecycle hooks, specialized agent profiles, and client-only commands belong in the relevant namespace. A package may install in several clients without providing the same complete experience in each one.

Client support can differ even within the portable core. A conforming client may support skills, MCP servers, or both. A client that supports plugin MCP servers must implement at least one of stdio or streamable-http; support for the deprecated sse transport is optional. Test the exact clients your team uses.

Treat installation as code execution

A plugin can carry scripts and executable MCP servers. Client-specific hooks may also run commands during the agent lifecycle. Review the publisher and source before installation.

Before distributing a plugin internally:

1. Pin or review every executable and dependency included in the package.
2. Keep secrets out of the manifest, mcp.json, scripts, and HTTP headers.
3. Test paths on every supported operating system.
4. Document which components run automatically and which wait for model selection or user action.
5. Publish a version and changelog so teams can inspect updates before installing them.

The specification requires package-relative paths to remain inside the plugin root. It also defines ${PLUGIN_ROOT} for packaged files and ${PLUGIN_DATA} for writable state that persists across updates. Those containment rules protect package discovery. They do not sandbox a subprocess. Apply the same permission review you would use for any other agent tool; the BLOGish least-privilege checklist is a practical starting point.

A migration plan for existing customizations

Start with a workflow already copied across several repositories. Inventory its instructions, scripts, MCP connections, hooks, and agent profiles. Move only the reusable skills and MCP configuration into the portable core, then keep host-specific behavior in an extension namespace or in the repository.

Validate plugin.json and mcp.json against the published schemas. Install the package locally in one supported client, then try a second client and record what each one loads. GitHub's plugin overview distinguishes repository configuration from plugins: manual configuration stays tied to one repository, while a versioned plugin can be installed across projects or discovered through a marketplace.

Model behavior still needs separate testing. A portable skill can load in several clients and produce different results when the clients expose different tools, gather different context, or use different models. Teams comparing those variables can run the same task through ISH chat or call models through the ISH API dashboard, while keeping the plugin instructions unchanged.

Package one workflow first. The acceptance test is concrete: a second client should load the skill and connect to the MCP server without a rewritten setup guide. Add client-specific extras after that path works.