agent-plugins-skill

Agent Plugins Plugin Development

This skill uses the Agent Plugins 1.0.0 formal specificationas the source of truth to help agents produce portable plugins, or implement clients conforming to the specification. The following reference materials are Chinese explanations and original examples; in case of discrepancies, the formal specification text prevails, then refer to theofficial JSON Schemas. Do not confuse this skill's version agent-plugins-skill, the plugin's own version with the Agent Plugins specification version.

When to use

• Plugin authors: create new plugins; convert existing proprietary packages such as Claude/Codex/Cursor into portable packages; add skills, MCP servers, or client-proprietary extensions.
• Client implementers: implement directory loading, validation, discovery, MCP connections, path safety, and fault isolation; develop conformance tests.
• Reviewers: check a real plugin or client against the 1.0.0 requirements item by item, and give specific fixes. Merely having SKILL.md, some client's plugin.json or an MCP configuration is not sufficient grounds to claim Agent Plugins compatibility.

If the user only requests Agent Skills format or ordinary MCP server development, use the corresponding specialized skills; here we handle their combination and loading contract within an Agent Plugin package .

Quick start

In this skill's directory, copy examples/minimal-plugin/ to a new plugin directory, modify a valid package and manifestaccording to name, then put real skills into skills/<名称>/SKILL.md. When MCP is needed, add a root MCP configuration and runningaccording to mcp.json. Do static validation first, then load in the target client; demo remote URLs cannot be treated as usable services.

First determine the task

1. Confirm the target directory, whether it is anauthor、clientorreviewtask, and the target specification version. When the user does not specify a version, use 1.0.0 as the baseline; when the latest version is needed, re-check the official website.
2. For existing projects, first inspect the working tree, existing package layout, host-proprietary manifests, and how it runs; preserve existing non-target changes. Identify what is portable and what must remain in host extensions.
3. Choose the corresponding reference file below, and read only the needed sections. In the specification, MUST/MUST NOT is a conformance requirement,SHOULD/RECOMMENDED is a recommendation, andMAY is permitted; do not upgrade recommendations into hard failures.
4. When delivering, clearly distinguish: static structure and Schema checks, client loading tests, actual MCP handshake/tool invocation, and target host installation verification. Success at one level cannot substitute for another.

Plugin author workflow

1. Read package and manifest: create a unique plugin.jsonin the root directory, containing the canonical $schema and a valid name. Fill in metadata by field type; client-proprietary data goes into extensions。
2. Read as needed skills and extensions: in skills/<skill-name>/SKILL.md Place skills that conform to the Agent Skills specification; put client-specific files in a reverse-domain top-level directory.
3. If MCP is needed, read MCP Configuration and Operation: place mcp.jsonin the root directory; decide item by item between stdio、streamable-http or ssefor legacy service compatibility, and handle paths, variables, and credential boundaries.
4. From Complete Examples and Counterexamples choose the closest example to adapt;examples/minimal-plugin/ provides a copyable minimal skill package. The service addresses and commands in the examples are for demonstration only and must be replaced with real resources before running.
5. Check JSON against the official Schema, then perform path, URL, placeholder, version, extension, and sensitive information checks according to the semantic checklist in the reference file. Load and actually invoke in the target client as much as possible; record unverified items.

Author Delivery Checklist

• The package root directory and the target version, legal name, and field types of plugin.json have all been verified.
• skills/、mcp.json is an optional component; if present, its fixed location and content are valid. No skills or MCP configuration are embedded in the manifest.
• Files accessed within the package still resolve to the package root via real paths; package-relative paths in the configuration start with ./ according to the rules.
• No keys are placed in visible env or headers; the client is responsible for authorization discovery, interaction, and credential storage.
• Client-specific capabilities are explicitly marked as extensions; installation, publishing, permissions, and sandbox policies are not misrepresented as portable core functionality.

Client Implementation Workflow

Read Loader and Consistency, implement in order: directory root and real path boundaries → first validate plugin.json → discover supported fixed components → fault isolation at each level → optional extension handling. If MCP is supported, then read the operation sections of MCP Configuration and Operation . Implement at least one of the two component types, skills or MCP; an MCP client supports at least one of stdio or streamable-http .

Use Consistency Test Matrixto cover observable outcomes, especially unknown manifest top-level fields, non-object extensions, erroneous component types, a single bad skill, a single bad MCP entry, startup failures, and path escapes atdifferent fault boundaries. The client runtime must not fetch the Schema online; the local implementation follows the identified canonical $schema selection rules.

Review Output

Provide item by item according to the table below: 通过 / 不符合 / 未验证 / 不适用, file or runtime evidence, the corresponding specification section, and the minimal fix. For clients, list supported components and transports; for plugins, list the measured results in the target client. You may refer to Compatible Clients and Sources, but that list changes over time; reopen the official page before use.

Dimension	Focus
Package	Single root directory, path containment, root plugin.json, version
manifest	Closed fields, required fields, names, non-fatal exceptions, extension namespaces
Discovery	skills/ immediate subdirectories, root mcp.json, missing and erroneous types
MCP	Schema same version, per-item types, commands/URLs/headers, variables, isolation
Client	At least one type of component, load order, continued operation under partial failure, real runtime evidence

Diagnosing common failures

• The host can install it, but standard clients do not discover it: First check whether the root plugin.json exists,$schema is a supported Agent Plugins version, then check the fixed component locations; the host's native manifest cannot replace it.
• One bad configuration makes the entire package disappear: Check whether the client mistakenly treats an unknown top-level manifest field or a non-object extensions as a fatal error; these two cases should be reported and ignored. Only other manifest Schema errors should reject the entire package.
• An MCP failure causes skills to disappear as well: Distinguish between mcp.json being invalid at the top level, an individual service being invalid, and connection/handshake failure, handling them at the MCP type or service entry boundary respectively.
• Local MCP command not found: Check whether command is a single token, whether the in-package path starts with ./ , whether the executable is actually packaged, and whethercwd and ${PLUGIN_DATA} comply with the rules.
• Remote MCP passes static checks but cannot be invoked: Record URL/headers rules, target client transport support, authorization, and the real MCP handshake separately; do not treat passing Schema as runtime success.

Resource navigation

Task	Read
Package layout, manifest, name, version, Schema	package-and-manifest.md
Skill discovery and client extensions	skills-and-extensions.md
MCP configuration, environment variables, and running	mcp-servers.md
Client loading, failure boundaries, test matrix	client-implementation.md
Copyable structure, valid/invalid configurations	examples.md
Official website pages, Schema, compatible clients	sources-and-compatibility.md

**Version note:** The above interpretations were verified as of 2026-09-28. Before creating cross-version packages or claiming a client's current support status, re-check the official website and the target client's documentation.