diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml new file mode 100644 index 0000000..9e9ff1f --- /dev/null +++ b/.github/workflows/validate.yml @@ -0,0 +1,20 @@ +name: Validate + +on: + push: + pull_request: + +permissions: + contents: read + +jobs: + validate: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: 22 + cache: npm + - run: npm ci + - run: npm run validate diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..c2658d7 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +node_modules/ diff --git a/README.md b/README.md index e4c6928..c0e83ae 100644 --- a/README.md +++ b/README.md @@ -1,87 +1,59 @@ -# Agent Plugins Example +# Mobbin Agent Plugin -A copyable reference package for the [Agent Plugins Specification v1.0.0](https://agent-plugins.org/specification). +The Mobbin Agent Plugin packages Mobbin's hosted MCP server for Agent Plugins 1.0.0 clients. It +helps agents find real-world UI screens, multi-step flows, and website sections from Mobbin's +design library. -This repository demonstrates the portable core and includes an Agent Skill that helps migrate existing plugins from client-specific formats. It is a reference example, not a substitute for the normative specification; if they differ, the specification wins. +## Install -## Layout +The package is a portable Agent Plugins 1.0.0 directory. Use the installation flow documented by +your client: -```text -agent-plugins-example/ -├── plugin.json # Required portable manifest -├── skills/ # Portable Agent Skills -│ └── migrate-agent-plugin/ -│ ├── SKILL.md -│ └── references/ -│ ├── client-extensions.md -│ ├── migration-guide.md -│ └── validation-checklist.md -├── README.md -└── LICENSE -``` +- [VS Code](https://code.visualstudio.com/docs/agent-customization/agent-plugins): install from + the marketplace, use **Chat: Install Plugin From Source**, or register a local checkout with + `chat.pluginLocations`. +- [Cursor](https://cursor.com/docs/plugins): install from Customize, or load a local checkout + from `~/.cursor/plugins/local/`. +- [GitHub Copilot](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference): + use `copilot plugin install OWNER/REPO` or the documented local/repository flow. +- [Kiro](https://kiro.dev/docs/powers/installation/): use **Powers → Add Custom Power**. +- [ChatGPT and Codex](https://developers.openai.com/plugins): install through OpenAI's plugin + directory. + +Claude Code is not an Agent Plugins-compatible client; use Mobbin's +[`claude mcp add` setup](https://docs.mobbin.com/mcp/clients/claude-code) instead. -The smallest valid plugin needs only `plugin.json`. This example includes a skill so it is useful as well as structurally illustrative. +On first use, the client opens a browser for OAuth authorization. You need a Mobbin account on a +Pro, Team, or Enterprise plan. The plugin contains no API key or other credential. -## The portable core +## What it installs -Agent Plugins v1 defines two portable component types: +- The `mobbin` MCP server at `https://api.mobbin.com/mcp` using Streamable HTTP. -- Agent Skills under immediate child directories of `skills/`. -- MCP servers in an optional root `mcp.json` using the matching v1.0.0 MCP schema. +The root `plugin.json` and `mcp.json` are the only package configuration files required by the +Agent Plugins standard. -The root `plugin.json` schema is closed. Do not add `hooks`, `agents`, `commands`, `mcpServers`, `lspServers`, or arbitrary client fields at its top level. Put portable MCP configuration in `mcp.json` and client-owned manifest data inside `extensions`. +Mobbin provides these read-only MCP tools: -See the authoritative documentation for the [plugin manifest](https://agent-plugins.org/plugin-authors/manifest), [skills](https://agent-plugins.org/plugin-authors/skills), [MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers), and [client extensions](https://agent-plugins.org/plugin-authors/client-extensions). +- `search_screens` — UI screens. +- `search_flows` — multi-step user journeys such as onboarding and checkout. +- `search_sections` — website sections such as pricing pages, heroes, and footers. -## Add client-specific capabilities safely +Results include images, metadata, and links back to Mobbin. -Hooks and similar capabilities are not portable v1 components. A client can add them through a reverse-domain extension namespace it owns and documents: +## Layout ```text -your-plugin/ +mobbin-agent-plugin/ ├── plugin.json -├── skills/ -├── mcp.json # Optional portable MCP configuration -└── com.vendor.client/ # Optional client extension - └── hooks/ - └── hooks.json -``` - -If a client uses both manifest data and files, `plugin.json` can contain an extension object: - -```json -{ - "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "your-plugin", - "extensions": { - "com.vendor.client": { - "settingDefinedByThatClient": true - } - } -} +├── mcp.json +├── schemas/1.0.0/ +│ ├── plugin.schema.json +│ └── mcp.schema.json +├── scripts/ +│ └── validate.mjs +└── .github/workflows/validate.yml ``` -`com.vendor.client` is illustrative. Use only a namespace and fields documented by the client that owns them. Other clients ignore an extension they do not implement, leaving the portable skills and MCP configuration usable. - -## Migrate without breaking the existing plugin - -Use an additive migration: - -1. Add and validate the root `plugin.json` without deleting working platform files. -2. Move or copy reusable skills into `skills//SKILL.md`. -3. Convert portable MCP servers to root `mcp.json` with explicit transport types. -4. Keep hooks, agents, commands, LSP, UI, and marketplace metadata in a client extension or a separate compatibility package required by that platform. -5. Test the portable core and every supported client package before removing legacy files. - -The included [`migrate-agent-plugin` skill](skills/migrate-agent-plugin/SKILL.md) contains the full migration workflow, artifact mapping, extension strategy, and validation checklist. - -## Copy this example - -1. Copy this directory and rename it to match your plugin. -2. Update `name`, `version`, `description`, `author`, and other allowed metadata in `plugin.json`. -3. Replace the example skill or add more immediate children under `skills/`. -4. Add `mcp.json` only if the plugin provides MCP servers. -5. Add client extensions only for namespaces implemented by your target clients. -6. Validate paths, schemas, skills, and each supported client integration. - -The directory name and manifest name do not have to match under the portable specification, but keeping them identical is strongly recommended for predictable packaging and discovery. +Read the [Mobbin MCP introduction](https://docs.mobbin.com/mcp/introduction) for client setup and +authorization details. diff --git a/mcp.json b/mcp.json new file mode 100644 index 0000000..4fc355d --- /dev/null +++ b/mcp.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "mobbin": { + "type": "streamable-http", + "url": "https://api.mobbin.com/mcp" + } + } +} diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..df014f6 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,71 @@ +{ + "name": "mobbin-agent-plugin", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "mobbin-agent-plugin", + "devDependencies": { + "ajv": "8.20.0" + } + }, + "node_modules/ajv": { + "version": "8.20.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.20.0.tgz", + "integrity": "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==", + "dev": true, + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/fast-uri": { + "version": "3.1.5", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz", + "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==", + "dev": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "dev": true, + "license": "MIT" + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..60ce757 --- /dev/null +++ b/package.json @@ -0,0 +1,11 @@ +{ + "name": "mobbin-agent-plugin", + "private": true, + "type": "module", + "scripts": { + "validate": "node scripts/validate.mjs" + }, + "devDependencies": { + "ajv": "8.20.0" + } +} diff --git a/plugin.json b/plugin.json index e422ca8..467d5ef 100644 --- a/plugin.json +++ b/plugin.json @@ -1,8 +1,14 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "agent-plugins-example", - "version": "1.0.0", - "description": "A copyable reference package and migration guide for Agent Plugins v1.0.0.", + "name": "mobbin", + "version": "0.1.0", + "description": "Search Mobbin's UI library for screens, flows, and website sections from your agent.", + "author": { + "name": "Mobbin", + "url": "https://mobbin.com" + }, + "homepage": "https://docs.mobbin.com/mcp/introduction", + "repository": "https://github.com/mobbin/mobbin-agent-plugin", "license": "MIT", - "keywords": ["agent-plugins", "example", "migration", "skills"] + "keywords": ["mobbin", "design-research", "ui-design", "ux-design", "mcp"] } diff --git a/schemas/1.0.0/mcp.schema.json b/schemas/1.0.0/mcp.schema.json new file mode 100644 index 0000000..a9139a4 --- /dev/null +++ b/schemas/1.0.0/mcp.schema.json @@ -0,0 +1,120 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "title": "Agent Plugins MCP Configuration", + "description": "Machine-readable schema for mcp.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.", + "type": "object", + "properties": { + "$schema": { + "const": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "description": "Canonical identifier of the MCP configuration schema for the Agent Plugins version targeted by this document." + }, + "mcpServers": { + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/server" + } + } + }, + "required": ["$schema", "mcpServers"], + "additionalProperties": false, + "$defs": { + "server": { + "title": "MCP server", + "oneOf": [ + { + "$ref": "#/$defs/stdioServer" + }, + { + "$ref": "#/$defs/streamableHttpServer" + }, + { + "$ref": "#/$defs/sseServer" + } + ] + }, + "stdioServer": { + "title": "stdio MCP server", + "type": "object", + "properties": { + "type": { + "const": "stdio" + }, + "command": { + "type": "string", + "minLength": 1, + "description": "Executable token. Resolution rules are defined by the Agent Plugins specification." + }, + "args": { + "type": "array", + "items": { + "type": "string" + } + }, + "env": { + "type": "object", + "propertyNames": { + "not": { + "enum": ["PLUGIN_ROOT", "PLUGIN_DATA"] + } + }, + "additionalProperties": { + "type": "string" + } + }, + "cwd": { + "type": "string", + "pattern": "^(?:\\./|\\$\\{PLUGIN_ROOT\\}(?:/|$)|\\$\\{PLUGIN_DATA\\}(?:/|$))", + "description": "Plugin-relative, PLUGIN_ROOT-rooted, or PLUGIN_DATA-rooted working directory. Filesystem containment is validated separately." + } + }, + "required": ["type", "command"], + "additionalProperties": false + }, + "streamableHttpServer": { + "title": "Streamable HTTP MCP server", + "type": "object", + "properties": { + "type": { + "const": "streamable-http" + }, + "url": { + "type": "string", + "minLength": 1, + "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification." + }, + "headers": { + "$ref": "#/$defs/headers" + } + }, + "required": ["type", "url"], + "additionalProperties": false + }, + "sseServer": { + "title": "Legacy HTTP+SSE MCP server", + "type": "object", + "properties": { + "type": { + "const": "sse" + }, + "url": { + "type": "string", + "minLength": 1, + "description": "MCP endpoint URL. URL semantics are defined by the Agent Plugins specification." + }, + "headers": { + "$ref": "#/$defs/headers" + } + }, + "required": ["type", "url"], + "additionalProperties": false + }, + "headers": { + "title": "HTTP headers", + "type": "object", + "additionalProperties": { + "type": "string" + } + } + } +} diff --git a/schemas/1.0.0/plugin.schema.json b/schemas/1.0.0/plugin.schema.json new file mode 100644 index 0000000..8fed0e1 --- /dev/null +++ b/schemas/1.0.0/plugin.schema.json @@ -0,0 +1,65 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "title": "Agent Plugins Manifest", + "description": "Machine-readable schema for plugin.json in Agent Plugins 1.0.0. The Agent Plugins specification defines additional semantic and operational requirements.", + "type": "object", + "properties": { + "$schema": { + "const": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "description": "Canonical identifier of the plugin manifest schema for the Agent Plugins version targeted by this document." + }, + "name": { + "type": "string", + "minLength": 1, + "maxLength": 64, + "pattern": "^(?!.*(?:--|\\.\\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$", + "description": "Human-readable plugin name." + }, + "version": { + "type": "string" + }, + "description": { + "type": "string" + }, + "author": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "email": { + "type": "string" + }, + "url": { + "type": "string" + } + }, + "additionalProperties": false + }, + "homepage": { + "type": "string" + }, + "repository": { + "type": "string" + }, + "license": { + "type": "string" + }, + "keywords": { + "type": "array", + "items": { + "type": "string" + } + }, + "extensions": { + "type": "object", + "description": "Client-specific manifest data keyed by reverse-domain extension namespace. Agent Plugins assigns no semantics to namespace object contents.", + "additionalProperties": { + "type": "object" + } + } + }, + "required": ["$schema", "name"], + "additionalProperties": false +} diff --git a/scripts/validate.mjs b/scripts/validate.mjs new file mode 100644 index 0000000..b6f61a5 --- /dev/null +++ b/scripts/validate.mjs @@ -0,0 +1,49 @@ +import Ajv from "ajv/dist/2020.js"; +import { readFile } from "node:fs/promises"; +import { createRequire } from "node:module"; +import { dirname, resolve } from "node:path"; +import process from "node:process"; + +const require = createRequire(import.meta.url); +const root = resolve(dirname(new URL(import.meta.url).pathname), ".."); +const errors = []; + +function fail(message) { + errors.push(message); +} + +async function readJson(path) { + try { + return JSON.parse(await readFile(resolve(root, path), "utf8")); + } catch (error) { + fail(`${path}: ${error.message}`); + return null; + } +} + +function validateSchema(schemaPath, data, label) { + if (data === null) return; + const schema = require(resolve(root, schemaPath)); + const ajv = new Ajv({ allErrors: true, strict: true }); + const valid = ajv.validate(schema, data); + if (!valid) { + for (const error of ajv.errors ?? []) { + fail(`${label}: ${error.instancePath || "/"} ${error.message}`); + } + } +} + +const plugin = await readJson("plugin.json"); +const mcp = await readJson("mcp.json"); +validateSchema("schemas/1.0.0/plugin.schema.json", plugin, "plugin.json"); +validateSchema("schemas/1.0.0/mcp.schema.json", mcp, "mcp.json"); + +if (errors.length > 0) { + console.error(`FAIL: ${errors.length} validation error${errors.length === 1 ? "" : "s"}`); + for (const error of errors) console.error(`- ${error}`); + process.exitCode = 1; +} else { + console.log("PASS: plugin.json schema"); + console.log("PASS: mcp.json schema"); + console.log("Validation passed."); +} diff --git a/skills/migrate-agent-plugin/SKILL.md b/skills/migrate-agent-plugin/SKILL.md deleted file mode 100644 index 7fa96b5..0000000 --- a/skills/migrate-agent-plugin/SKILL.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -name: migrate-agent-plugin -description: Migrate an existing Claude, Copilot, Codex, Cursor, Kiro, VS Code, or other client-specific agent plugin to the portable Agent Plugins v1 structure while preserving platform-specific hooks, agents, commands, LSP, UI, and marketplace behavior. Use when auditing, converting, or modernizing an agent plugin. -license: MIT -metadata: - version: "1.0.0" ---- - -# Migrate an Agent Plugin - -Convert an existing plugin to the Agent Plugins v1 portable core without prematurely removing behavior required by its current clients. - -## Source of truth - -Use the current [Agent Plugins specification](https://agent-plugins.org/specification) as the normative source. - -Read these references before editing: - -- [Migration guide](references/migration-guide.md) -- [Client extensions](references/client-extensions.md) -- [Validation checklist](references/validation-checklist.md) - -## Workflow - -1. Inventory the current plugin before moving files. - - Record every manifest, skill, prompt or command, agent, MCP server, hook, LSP server, UI resource, script, secret requirement, and marketplace entry. - - Identify the clients that currently load each artifact and the install paths or discovery rules they require. - - Run existing tests or capture a manual smoke-test baseline. - -2. Classify each artifact. - - Portable core: root `plugin.json`, Agent Skills in `skills/`, and MCP servers in root `mcp.json`. - - Client extension: additional behavior loaded through a reverse-domain namespace owned and documented by a client. - - Compatibility layer: legacy files or a generated client package retained until that client supports the portable or namespaced form. - - Distribution metadata: marketplace catalogs, install policy, signing, and release configuration; these are outside the portable package format. - -3. Add the portable manifest. - - Create `plugin.json` at the plugin root. - - Set `$schema` to `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`. - - Include `name` and only supported metadata fields. - - Do not put component paths or client fields such as `hooks`, `agents`, `skills`, or `mcpServers` at the top level. - -4. Normalize portable components. - - Put each skill at `skills//SKILL.md`; only immediate children of `skills/` are discovered. - - Make each skill name match its parent directory and the Agent Skills naming rules. - - If MCP is present, convert it to root `mcp.json`, declare the matching v1.0.0 schema, and give every server an explicit `stdio`, `streamable-http`, or `sse` type. - - Use `${PLUGIN_ROOT}` for packaged read-only resources and `${PLUGIN_DATA}` for persistent writable state where the MCP schema permits expansion. - -5. Preserve non-core behavior. - - Use a client extension only when the target client publishes a reverse-domain namespace and its semantics. - - If the client still requires a legacy layout, keep or generate a separate compatibility package. Treat the portable files as the source of truth and avoid manually maintaining divergent copies. - - Do not invent a vendor namespace and assume an unrelated client will load it. - -6. Validate and test incrementally. - - Validate the portable manifest, every skill, optional MCP configuration, and package path containment. - - Test each supported client independently, including hooks and other compatibility behavior. - - Remove legacy artifacts only after the replacement passes the same behavior checks. - -## Required migration report - -Before finishing, report: - -- The discovered source format and target clients. -- A mapping from every original artifact to portable core, extension, compatibility layer, distribution metadata, or removal. -- Files added, moved, generated, retained, and intentionally omitted. -- Validation and client smoke-test results. -- Remaining client-specific risks or manual steps. - -Prefer an additive, reversible migration. Never claim that hooks, agents, commands, LSP servers, UI, or marketplace metadata became portable Agent Plugins v1 components. diff --git a/skills/migrate-agent-plugin/references/client-extensions.md b/skills/migrate-agent-plugin/references/client-extensions.md deleted file mode 100644 index 1284ab6..0000000 --- a/skills/migrate-agent-plugin/references/client-extensions.md +++ /dev/null @@ -1,76 +0,0 @@ -# Client Extensions - -Agent Plugins v1 keeps the portable core small. Client extensions provide an escape hatch for hooks, agents, commands, LSP, UI, and other behavior that has not become portable. - -## Rules - -1. Extension namespaces are reverse-domain identifiers, such as `com.vendor.client`. -2. The client that owns the namespace defines its fields, files, validation, and runtime behavior. -3. Manifest extension data belongs under `extensions` in root `plugin.json`. -4. Extension files belong in a top-level directory whose name exactly matches the namespace. -5. Other clients ignore namespaces they do not implement without losing valid portable components. -6. An extension is not a way for a plugin author to make up fields that existing clients will automatically understand. - -## Manifest data - -```json -{ - "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "your-plugin", - "extensions": { - "com.vendor.client": { - "settingDefinedByThatClient": true - } - } -} -``` - -The portable specification validates only that each namespace value is an object. The owning client defines everything inside it. - -## Extension files - -```text -your-plugin/ -├── plugin.json -├── skills/ -└── com.vendor.client/ - ├── hooks/ - │ └── hooks.json - └── agents/ - └── reviewer.md -``` - -This layout has effect only if `com.vendor.client` actually implements those paths. - -## Choose the right compatibility strategy - -### The client documents an Agent Plugins extension namespace - -Use its exact namespace, fields, and directory layout. Test failures in the extension separately from the portable skills and MCP configuration. - -### The client supports Agent Plugins core but still discovers legacy add-ons - -Keep the root manifest conforming. Follow the client's documented additive loading behavior for legacy hooks or agents, and label those files as client-specific. If that layout conflicts with strict portable packaging, generate a separate client distribution from the portable source. - -### The client does not support Agent Plugins core - -Keep the legacy plugin working and add a portable sibling package. Share underlying skill text, scripts, and server code where safe, but avoid symlinks that resolve outside either package root. - -## Hooks - -Hooks are a common extension candidate, but Agent Plugins v1 does not define their event names, input/output protocol, command format, security model, or discovery path. Preserve the existing hook until the target client documents a replacement. Review hook scripts as executable code and test approval, denial, failure, and timeout behavior after migration. - -## Do not put client fields at the manifest top level - -These examples are nonconforming in an Agent Plugins v1 root manifest: - -```json -{ - "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "your-plugin", - "hooks": "hooks.json", - "agents": "agents/" -} -``` - -Use a documented extension or a compatibility package instead. diff --git a/skills/migrate-agent-plugin/references/migration-guide.md b/skills/migrate-agent-plugin/references/migration-guide.md deleted file mode 100644 index 1186a34..0000000 --- a/skills/migrate-agent-plugin/references/migration-guide.md +++ /dev/null @@ -1,114 +0,0 @@ -# Migration Guide - -Use this guide to map an existing plugin into the Agent Plugins v1 portable core while keeping client-specific behavior available. - -## 1. Inventory before conversion - -Locate all plugin manifests and component roots. Common legacy or client-specific artifacts include: - -- `.claude-plugin/plugin.json`, `.plugin/plugin.json`, `.github/plugin/plugin.json`, `.codex-plugin/plugin.json`, or a root manifest without the Agent Plugins `$schema`. -- Skills under `skills/`, `.agents/skills/`, `.github/skills/`, `.claude/skills/`, or a configured custom path. -- MCP configuration in `.mcp.json`, `.github/mcp.json`, another client config, or inline manifest fields. -- Hooks in `hooks.json`, `hooks/hooks.json`, a settings file, or inline manifest fields. -- Commands, prompts, custom agents, LSP servers, UI assets, authentication declarations, and marketplace catalogs. - -Do not delete or move anything until its consumer and replacement are known. - -## 2. Map every artifact - -| Existing artifact | Agent Plugins v1 destination | Compatibility action | -| --- | --- | --- | -| Plugin identity and metadata | Root `plugin.json` | Retain a legacy manifest only if a target client still requires it. Generate copies from one source when possible. | -| Reusable skill | `skills//SKILL.md` | Normalize frontmatter and keep scripts, references, and assets inside the skill directory. | -| MCP server | Root `mcp.json` | Convert client-specific fields and declare an explicit transport type. Keep a client adapter only for unsupported fields or transports. | -| Hook | No portable v1 destination | Use a client-owned extension namespace or retain a client compatibility package. | -| Custom agent or persona | No portable v1 destination | Keep it in a client extension or compatibility package. Convert to a skill only when on-demand instructions truly preserve its semantics. | -| Command or prompt | No portable v1 destination | Convert reusable task instructions to a skill when appropriate; otherwise retain the client feature. | -| LSP server | No portable v1 destination | Retain it as a client extension or compatibility package. | -| UI or app integration | No portable v1 destination | Retain it as a client extension or compatibility package. | -| Marketplace entry, install policy, signing | Outside the portable package | Keep it in the platform's distribution repository or release process. | - -## 3. Create the portable manifest - -Start with the smallest valid root manifest: - -```json -{ - "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", - "name": "your-plugin" -} -``` - -Allowed optional fields are `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions`. The schema is closed. Unknown top-level fields are nonconforming even when a particular client historically accepted them. - -Plugin names are 1–64 characters, use lowercase ASCII letters, digits, hyphens, and periods, begin and end with an alphanumeric character, and contain neither `--` nor `..`. - -## 4. Normalize skills - -Each discoverable skill must be an immediate child of `skills/`: - -```text -skills/ -└── deploy/ - ├── SKILL.md - ├── scripts/ - ├── references/ - └── assets/ -``` - -The `SKILL.md` name must match its parent directory. Keep skill-relative dependencies inside that directory and update references after moving files. Do not rely on recursive discovery of nested skill directories. - -## 5. Convert MCP configuration - -Portable MCP configuration belongs in root `mcp.json`, not inline in `plugin.json`: - -```json -{ - "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", - "mcpServers": { - "example": { - "type": "stdio", - "command": "node", - "args": ["${PLUGIN_ROOT}/server/index.js"], - "cwd": "${PLUGIN_ROOT}" - } - } -} -``` - -Use a single executable token for `command`; do not put a shell command line in that field. A bundled executable uses a plugin-relative `./path`. Non-loopback remote servers use HTTPS. Do not embed secrets in remote headers. - -## 6. Preserve platform behavior - -Migration should be additive first: - -1. Add the portable root manifest and components. -2. Leave the working client package intact. -3. Make portable files the source of truth. -4. Generate or copy legacy adapters only when client documentation requires them. -5. Test every supported client. -6. Remove old files only after their consumers have migrated. - -A repository can keep the portable plugin and client adapters as siblings: - -```text -repository/ -├── plugin/ # Agent Plugins v1 portable package -└── client-adapters/ # Generated or maintained platform packages - ├── client-a/ - └── client-b/ -``` - -An adapter is not part of the portable core. Clearly label which files are canonical and automate synchronization when multiple manifests or layouts must ship. - -## 7. Test the migration - -Test at least: - -- Loading the plugin with a conforming Agent Plugins client. -- Skill discovery and activation. -- Every MCP transport and tool, when present. -- Legacy installation and all retained hooks, agents, commands, LSP, or UI behavior. -- Upgrade and rollback from the last released client-specific package. - -The migration is complete only when the portable core validates and the promised client behaviors still work. diff --git a/skills/migrate-agent-plugin/references/validation-checklist.md b/skills/migrate-agent-plugin/references/validation-checklist.md deleted file mode 100644 index 9be4420..0000000 --- a/skills/migrate-agent-plugin/references/validation-checklist.md +++ /dev/null @@ -1,49 +0,0 @@ -# Validation Checklist - -## Package - -- [ ] `plugin.json` is a regular file at the plugin root. -- [ ] Every packaged or resolved path remains inside the plugin root. -- [ ] Symlinks, junctions, and reparse points do not escape the package. -- [ ] No credentials, tokens, or private keys are embedded in the package. - -## Manifest - -- [ ] `$schema` is `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json`. -- [ ] `name` satisfies the v1 length and character rules. -- [ ] Only `$schema`, `name`, `version`, `description`, `author`, `homepage`, `repository`, `license`, `keywords`, and `extensions` appear at the top level. -- [ ] Every `extensions` member is an object keyed by a reverse-domain namespace. -- [ ] Optional metadata has the type required by the schema. - -## Skills - -- [ ] Each skill is an immediate child directory of `skills/`. -- [ ] Each skill contains a regular file named exactly `SKILL.md`. -- [ ] The frontmatter `name` matches the directory name and Agent Skills naming rules. -- [ ] `description` explains both what the skill does and when to use it. -- [ ] Referenced scripts, references, and assets exist within the skill directory. -- [ ] Each skill validates independently; one invalid skill should not hide failures in another. - -## MCP, when present - -- [ ] Root `mcp.json` uses `https://agent-plugins.org/schemas/1.0.0/mcp.schema.json`. -- [ ] Its specification version matches `plugin.json`. -- [ ] Every server declares exactly one supported transport variant. -- [ ] `command` is one executable token, not a shell command string. -- [ ] Plugin-relative executable paths and working directories begin with `./`. -- [ ] `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` appear only in fields where expansion is defined. -- [ ] Remote non-loopback URLs use HTTPS and contain no embedded credentials. - -## Client compatibility - -- [ ] Every client extension uses a namespace implemented and documented by its owning client. -- [ ] Hooks, agents, commands, LSP, UI, and marketplace metadata are not presented as portable v1 components. -- [ ] A compatibility package remains available for clients that still require a legacy layout. -- [ ] Portable and legacy manifests are generated from one metadata source where practical. -- [ ] Installation, update, rollback, and behavior smoke tests pass for every supported client. - -## Handoff - -- [ ] The migration report maps every original artifact to its new owner and location. -- [ ] Removed files have a verified replacement and recovery path. -- [ ] Remaining limitations and manual release steps are documented.