--- name: conciliate-ai-agent-plugins description: > Use this skill when one AI agent plugin must be created, audited, or reconciled across Claude Code, OpenAI Codex/ChatGPT, Hermes Agent, OpenCode V2, and Google Antigravity (plus skill-only hosts such as Copilot CLI). It maps manifests, skills, commands, subagents, hooks, MCP servers, tools, secrets, UI, and distribution across platforms; detects gaps and drift with a compatibility matrix and drift ledger; decides between unify, generate, adapt, degrade, declare, and drop; and validates cross-host parity before release. Trigger on "multi-platform plugin", "portable plugin", "make this plugin work in Claude/Codex/Hermes/OpenCode/Antigravity", "cross-agent compatibility", "plugin parity", "gap analysis", "compatibility matrix", or "drift" when more than one agent runtime is involved. license: MIT compatibility: claude-code, codex, chatgpt, hermes, opencode, copilot, antigravity allowed-tools: bash, read, write, edit metadata: audience: developers workflow: cross-platform-plugin-development --- # Conciliate AI Agent Plugins One plugin, several runtimes. Keep a single canonical contract and make every difference explicit: either adapted, generated, degraded, or declared. This skill does not replace the platform skills. It decides **what must be equal** across hosts and **where divergence is allowed**, then routes implementation to `create-update-claude-plugin`, `create-update-codex-plugin`, `create-update-hermes-plugin`, `create-update-opencode-plugin`, or `create-update-antigravity-plugin`. Those five skills are the reference implementations of each host's rules. ## 1. Core Model Three layers, three rules: | Layer | Rule | |---|---| | **Canonical core** | Identity, skill text, schemas, docs, and remote MCP URLs exist once | | **Adapters** | Manifests and runtime code translate the core; they contain no business logic | | **Declared gaps** | Anything a host cannot do is written down with a fallback, owner, and review date | If the same intent is implemented twice with different text, that is drift. If a host cannot express it, that is a gap. Neither is a bug by itself; silence is. ## 2. Platform Quick Map | Concern | Claude Code | Codex / ChatGPT | Hermes Agent | OpenCode V2 | Antigravity | |---|---|---|---|---|---| | Manifest | `.claude-plugin/plugin.json` | `plugin.json` | `plugin.yaml` + `register(ctx)` | none; `package.json` + plugin `id` | `plugin.json` (no version field) | | Skills | Root `skills/` | Root `skills/` | Root `skills/` + `register_skill` | `ctx.skill.transform` or a discovery root | Root `skills/` | | Commands | `commands/*.md` | Skill substitute | `ctx.register_command` | `ctx.command.transform` | Skill becomes `/name` in the CLI | | Subagents | `agents/*.md` | None | None | `ctx.agent.transform` | `agents/*.md` | | Hooks | `hooks/hooks.json` | `hooks/hooks.json` (local only) | `ctx.register_hook` | `ctx.*.hook` | `hooks.json` (nested by hook name) | | MCP | `.mcp.json` | `mcp.json` | Host `config.yaml` | Config `mcp` or `ctx.mcp.transform` | `mcp_config.json` | | Extra surface | Mods, monitors, LSP | MCP Apps UI | Providers, memory | TUI/RPC | `rules/`, sidecars | | Distribution | Marketplace + tag | Marketplace / public dir | Git, pip, Nix | npm / git | git, local dir, official marketplace | Full field-by-field mappings: `references/platform-matrix.md` and `references/component-mapping.md`. ## 3. Reconciliation Loop 1. **Declare targets and tiers** (`must` / `should` / `out of scope`) before coding. A target without a tier is not a target. 2. **Inventory** with the bundled scanner. 3. **Canonicalize** identity, skill text, MCP definitions, and tool schemas. 4. **Classify** each finding as gap or drift, then merge by root cause. 5. **Decide** one resolution per finding: unify, generate, adapt, degrade, declare, or drop. 6. **Implement adapters** in dependency order: identity → manifests → MCP → tools → commands/agents/UI → hooks. 7. **Validate per host**, then run the cross-host gate (`--strict`). 8. **Release once**, regenerate every manifest/catalog, update the ledger, and schedule the next re-audit. Detailed steps, templates, and the behavior matrix: `references/reconciliation-workflow.md`. ## 4. Gap vs Drift - **Gap** — capability promised by the canonical contract but absent on a host. - **Drift** — capability exists on both, but name, version, text, schema, or behavior diverged. | Decision | Use when | |---|---| | **Unify** | Difference is accidental; one form works everywhere | | **Generate** | Difference is mechanical (manifests, `.mcp.json`, catalogs) | | **Adapt** | Same intent, different runtime API (hooks, native tools) | | **Degrade** | Optional capability; a documented text/skill fallback is enough | | **Declare** | Host cannot express it and does not need to; needs owner + date | | **Drop** | Capability is not worth its cross-platform cost | Codes, severity, and the ledger format: `references/drift-taxonomy.md`. **Hard rule:** never resolve P0 by declaring it; never resolve P1 by silence. ## 5. Release Gate | Severity | Examples | Gate | |---|---|---| | P0 | Broken entrypoint, name mismatch, secret leak, schema mismatch | Block on every target | | P1 | Missing MCP server, missing skill registration, version or hook-semantics drift | Block unless declared with a substitute | | P2 | Commands/subagents/UI without a native surface, context-budget drift | Ship and schedule | "Compatible" means: every must-tier host loads, runs the primary workflow, has zero undeclared P0/P1 findings, and every known gap has a ledger row. ## 6. Non-Negotiable Contracts - **Identity:** one `name`, one `version`, one `description` across manifests, package metadata, and marketplace catalogs. - **Skills:** one canonical `description` per skill; it is the trigger on every host. Keep the portable frontmatter subset and move platform-only fields to adapters. - **Tools/MCP:** shared JSON Schema and identical server names; implement handlers per runtime, never share handler code across Python and TypeScript. - **Secrets:** one env var name, declared in every manifest, stored only in the host's secure store, never in metadata, logs, or skill bodies. - **Hooks:** automation only. Every workflow must pass with hooks denied or unavailable. - **Paths:** host root variables, never `/home/...`, `~`, or hardcoded install directories. ## 7. Recommended Layouts Skills-only plugin (simplest; per-host manifests in one root): ```text my-plugin/ ├── .claude-plugin/plugin.json # Claude ├── plugin.json # Codex (root) ├── plugin.yaml # Hermes ├── package.json # OpenCode ├── skills//SKILL.md # canonical skill text ├── mcp.json # canonical MCP definitions ├── .mcp.json # generated for Claude ├── __init__.py # Hermes adapter (register_skill, register_tool) └── COMPATIBILITY.md # matrix + ledger ``` **Antigravity cannot share the root with Codex.** Both require `plugin.json`, and the Antigravity schema forbids the extra keys Codex uses (`additionalProperties: false`, no `version`). Ship it as a sibling directory or a generated copy: ```text my-plugin/ ├── codex/plugin.json # name, version, description ├── antigravity/plugin.json # name, description, $schema only ├── antigravity/mcp_config.json # Streamable HTTP only ├── antigravity/hooks.json # events nested under hook names └── canonical/skills//SKILL.md ``` Install the Antigravity directory itself (`agy plugin install ./antigravity`), not the parent. A shared root only works if the Codex manifest is reduced to the two Antigravity keys — verify with `agy plugin list --json` before choosing that. Complex plugin with native runtimes: `canonical/` plus generated host manifests and thin adapters, as described in `references/reconciliation-workflow.md`. ## 8. Scanner ```bash node scripts/conciliate.ts . \ --targets claude,codex,hermes,opencode,antigravity # Machine-readable, fail the build on P0/P1 node scripts/conciliate.ts . --targets claude,codex,hermes,opencode,antigravity \ --json --strict ``` It detects platforms and identities, inventories skills/MCP/hooks/components, and reports `GAP-*` / `DRIFT-*` findings with a coverage matrix (rules and sidecars are validated per host, not by the matrix). It is a cross-host gate, not a replacement for each host's own validator. It assumes the canonical layout (`skills/`, `hooks/hooks.json`, `mcp.json`/`.mcp.json`, `mcp_config.json`/`hooks.json` for Antigravity); custom manifest paths can surface as gaps and should be confirmed by hand. Target detection: Antigravity is identified by a root `plugin.json` whose `$schema` points at `antigravity.google`, or by `mcp_config.json`, `hooks.json`, or `rules/`. Codex is not claimed for that same file, because the two schemas are incompatible. ## 9. Validation Stack Run all four layers before release: 1. **Canonical**: generated files match their sources; one version everywhere. 2. **Per host**: the five `create-update-*` validators and host CLIs (`claude plugin validate`, `opencode plugin check`, `hermes plugins list`, `agy plugin list --json`). 3. **Cross-host**: `conciliate.ts --strict`. 4. **Behavior**: the scenario matrix in `references/reconciliation-workflow.md#step-7--behavior-matrix`. ## 10. Reference Triggers | Need | File | |---|---| | Field/component matrix per host | `references/platform-matrix.md` | | Adapter recipes and per-component mapping | `references/component-mapping.md` | | Codes, severity, ledger, resolution patterns | `references/drift-taxonomy.md` | | Step-by-step process and templates | `references/reconciliation-workflow.md` | | Ledger and behavior-matrix template | `assets/COMPATIBILITY.template.md` | | Upstream sources and re-audit procedure | `references/platform-sources.md` | | Vendored per-host docs (104 pages) and refresh rules | `references/docs/README.md` | ## 11. Checklist - [ ] Targets and tiers are written down, with host versions. - [ ] Scanner baseline captured before changes. - [ ] One canonical identity; every manifest/catalog agrees. - [ ] One canonical description per skill; portable frontmatter subset respected. - [ ] Each host's required entrypoint exists and loads. - [ ] Every skill is actually registered/discoverable on every must-tier host. - [ ] MCP server names and schemas match; Hermes install step documented. - [ ] Antigravity ships its own directory (no shared root `plugin.json` with Codex). - [ ] Hooks are optional, idempotent, fail-open, and mapped by semantics. - [ ] Secrets use one env name and the host secure store. - [ ] Per-host validators pass; `conciliate.ts --strict` passes. - [ ] Behavior matrix filled for must-tier hosts, including a no-trigger prompt. - [ ] `COMPATIBILITY.md` has no open P0/P1 findings and every declared gap has an owner and review date.