plugin-container-v2: full-skin plugin container for multi-skill bundles

[chitcommit]

Work key: chittymarket/plugin-container-v2

Corrected 2026-07-30. The first version of this issue claimed plugins "cannot state that they ship hooks, MCP servers, commands, an output style". That is wrong — the official manifest supports all of those. Corrected problem statement below; the real gap is narrower and different.

What the official format already gives us

.claude-plugin/plugin.json (plugins-reference) already supports:

{
  "name", "displayName", "version", "description",
  "author": { "name", "email", "url" },
  "homepage", "repository", "license", "keywords",
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": ["./custom/agents/reviewer.md"],
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "experimental": { "themes": "./themes/", "monitors": "./monitors.json" },
  "dependencies": ["helper-lib", { "name": "secrets-vault", "version": "~2.1.0" }]
}

Components auto-discover from skills/, commands/, agents/, hooks/; the manifest is only needed for metadata or custom paths. claude plugin validate ./my-plugin already validates manifest + skill/agent/command frontmatter + hooks/hooks.json.

The actual gap

1. ChittyOS plugins under-use the schema that exists. chittyos-core's entry is name/description/version/source/strict/category/keywords — no dependencies, no hooks, no mcpServers, no author/license/repository. MCP servers ship as separate plugins (chittyos-mcp, neon-mcp) rather than as mcpServers on the plugin that needs them. This is the cheapest, highest-value fix and needs no new spec — just adoption.

2. claude plugin validate is not in CI. Nothing catches a malformed manifest or bad frontmatter before it reaches the marketplace.

3. Multi-runtime projection is genuinely outside the official spec. codex-skills/, openclaw-agents/, chatgpt-apps/ exist in some plugins with no schema declaring which runtimes a plugin targets or which artifact projects where. chittyagent-dispatch does the projecting but has no declared contract to project from. This is the part that actually needs new design.

4. No requires for backend services. A plugin can depend on another plugin (dependencies), but cannot express "requires ChittyConnect broker reachable" or "needs binding X" (by reference, never value). Ecosystem-specific, not covered upstream.

5. No conflicts. Two plugins defining /checkpoint collide silently. Skills are namespaced by plugin (/commit-commands:commit), which mitigates but does not declare intent.

6. statusline is not a plugin component — it is settings-level. The original issue wrongly listed it. themes/monitors exist but only under experimental.

Scope

1. Adopt the existing schema first. Audit all 16 plugins; populate dependencies, hooks, mcpServers, outputStyles, author, license, repository where artifacts already exist on disk. No new spec required.
2. Add claude plugin validate to CI across every plugin in plugins/.
3. Design the ChittyOS extension layer — additive keys the upstream loader ignores:
   • chitty.runtimes: target runtimes + per-artifact projection map, consumed by chittyagent-dispatch
   • chitty.requires: backend services (health/version contract), bindings by reference
   • chitty.conflicts: declared namespace collisions
   • chitty.profile: linkage to profiles.json lens model
4. Validator for the extension layer: fails closed on undeclared-on-disk, declared-but-missing, cross-plugin collisions, unresolvable requires.
5. Reference migration: chittyos-core, proving both validators.

Non-goals

• Do not fork or replace the upstream manifest. Extensions live under a chitty.* namespace so upstream tooling keeps working.
• Not changing marketplace transport or install flow.
• No secret values in manifests — requires names a binding; the broker resolves it.

Acceptance criteria

• All 16 plugins audited; existing-schema fields populated where artifacts exist
• claude plugin validate green for every plugin, running in CI
• JSON Schema for the chitty.* extension layer, referenced from CHARTER.md
• Extension validator fails on each of the four fault classes, with a test per class
• chittyos-core migrated as reference
• chittyagent-dispatch projects from chitty.runtimes for ≥2 runtimes without per-plugin branching
• v1 plugins still install (regression test)
• Triad docs updated

Notes

Prior art in-repo: chittyagent-dispatch (projection), profiles.json (lens model), capabilities.generated.json (generated inventory). Related: #70.

Marked for development — not started.

🤖 Generated with Claude Code

[chitcommit]

Corrected the problem statement. The original claimed the plugin manifest can't declare hooks/MCP servers/commands/output styles — it can; plugin.json supports skills, commands, agents, hooks, mcpServers, outputStyles, lspServers, experimental.themes, experimental.monitors, and dependencies with version constraints.

Real gap is narrower: ChittyOS plugins under-use the schema that already exists (no dependencies/hooks/mcpServers populated, MCP servers shipped as separate plugins), claude plugin validate isn't in CI, and only the multi-runtime projection + service requires + conflicts genuinely need new design — as a chitty.* extension namespace, not a fork.

Also dropped statusline from the component list; it's settings-level, not a plugin component.

Tracked in Linear as CFDXN-124.

[chitcommit]

Finding: the ChatGPT/Claude "projection" is duplication, not projection

Verified in plugins/ch1tty/:

plugins/ch1tty/chatgpt-apps/ch1tty-search.json
plugins/ch1tty/claude-skills/ch1tty-search.json   <- BYTE-IDENTICAL
plugins/ch1tty/chatgpt-apps/ch1tty-fetch.json
plugins/ch1tty/claude-skills/ch1tty-fetch.json    <- BYTE-IDENTICAL

Both directories hold the same MCP tool definitions (name, description, inputSchema, outputSchema, annotations, _meta with chittycanon/canon_uri). The pair is search + fetch — ChatGPT's connector contract.

They are identical because MCP is the shared substrate. ChatGPT reaches tools via MCP connectors/Apps SDK (the 2023 plugin directory is retired), and Claude reaches them via MCP. There is no per-runtime transformation happening, so the directory split buys nothing and creates two copies that can drift.

Implication for chitty.runtimes — it should be smaller than originally scoped. Rather than one artifact directory per runtime:

• One canonical MCP tool definition per tool. runtimes declares exposure (which runtimes surface it, under what name, with what visibility), not duplicate artifacts.
• Per-runtime handling collapses to the genuinely different bits: ChatGPT's search/fetch naming contract, Claude's plugin-skill namespacing (/plugin:skill), OpenClaw's YAML agent shape.
• codex-skills/ and openclaw-agents/ need the same audit — check whether they are also copies before designing transforms for them.

This makes item 3 in the scope cheaper and reduces drift surface. It also means the first concrete deliverable may be deleting a duplicate directory and pointing both runtimes at one source, before any schema work.

[chitcommit]

Reference implementations: ChittyMarket's projection is inverted

Two upstream vendors solve multi-runtime distribution, and neither duplicates artifacts.

Cloudflare — one repo, one artifact tree, thin per-runtime manifests (cloudflare/skills, 2.5k stars):

skills/            <- ONE tree, 11 skills, not duplicated
.claude-plugin/marketplace.json   { "$schema": "...", "owner": {name,url}, plugins:[{ "source": "./" }] }
.cursor-plugin/marketplace.json   { "owner": {name},  plugins:[{ "source": "./" }] }   <- no $schema, no owner.url

Both manifests point source at the same ./. The only delta is manifest metadata.

OpenAI — one source, per-runtime repos with components subtracted:

• Codex: codex://plugins/install/openai-developers?marketplace=openai-curated
• Claude Code: openai/openai-developers-for-claude — .claude-plugin/ + plugins/ + tests/
• Cursor: openai/openai-developers-for-cursor — .cursor-plugin/ + top-level mcp.json

Per their docs, the Claude/Cursor builds "bundle the portable developer skills and public OpenAI Docs MCP server without the Codex-specific Platform connector." So projection = subtract components the runtime can't use, not transform file formats.

Also confirmed: the Codex SKILL.md format (openai/skills, 24k stars) is the same name + description frontmatter with references/, scripts/, assets/, agents/ — i.e. identical to Claude's skill format. Which means codex-skills/ in ChittyMarket is almost certainly duplication too, same as the already-confirmed chatgpt-apps/ ≡ claude-skills/.

What this changes

ChittyMarket's current shape is inverted: one manifest, artifacts duplicated into skills/, codex-skills/, openclaw-agents/, chatgpt-apps/, claude-skills/. Upstream does the opposite — one artifact tree, thin manifests per runtime.

Revised approach, replacing the chitty.runtimes projection-map idea:

1. Collapse duplicate artifact trees. Keep one canonical skills/ and agents/ per plugin. Confirmed duplicate: chatgpt-apps/ ≡ claude-skills/ (byte-identical). To verify: codex-skills/ vs skills/.
2. Emit thin per-runtime manifests — .claude-plugin/, and .cursor-plugin/ / .codex-plugin/ as needed — all pointing source at the shared tree, differing only in metadata.
3. Express runtime differences as component subtraction, per OpenAI: a manifest omits components the runtime cannot use, rather than shipping a transformed copy.
4. chittyagent-dispatch then generates manifests, not artifact copies. Substantially smaller job than the projection map originally scoped.
5. Add tests/ — openai-developers-for-claude ships plugin tests; ChittyMarket has none.

This makes the first deliverable deletion: collapse the duplicate trees and prove both runtimes still resolve. Schema work follows, and is smaller than originally written.

[chitcommit]

Measured adoption audit — and the component that actually is "the full skin"

Ran against all 16 plugins in plugins/:

Official component	Adopted
skills/	7/16
agents/	5/16
.mcp.json	2/16
commands/	1/16
hooks/	1/16
README.md	1/16
.lsp.json	0/16
monitors/	0/16
bin/	0/16
settings.json	0/16

Good news: no plugin makes the classic structural mistake — nothing but plugin.json sits inside .claude-plugin/.

Non-standard directories ChittyMarket invented: chatgpt-apps/, claude-skills/, codex-skills/, openclaw-agents/ (the duplication), plus canonical/ and scripts/.

settings.json is the "full skin" mechanism, and nothing uses it

Per Create plugins, a plugin can ship settings.json at its root:

{ "agent": "security-reviewer" }

Setting agent activates one of the plugin's custom agents as the main thread, applying its system prompt, tool restrictions, and model. This lets a plugin change how Claude Code behaves by default when enabled.

That is precisely the "robust container that is the full skin" this issue was opened for — a plugin that owns the main thread's persona, not just adds skills beside it. Supported keys today: agent, subagentStatusLine. Zero ChittyOS plugins use it.

Concretely: the nb-development-defaults posture and the collaborative-decisioning output style are currently loose config. A chittyos-core shipping settings.json + agents/ + outputStyles/ would make the whole working posture installable and versioned.

bin/ is the other unused lever

bin/ — Executables added to the Bash tool's PATH while the plugin is enabled.

ChittyOS leans on the can chitty CLI and scripts/ throughout. A plugin could ship those on PATH instead of assuming they are pre-installed — removing a whole class of "works on my machine".

Additional components absent from the original scope

• monitors/monitors.json — background monitors; each stdout line from command reaches Claude as a notification. Obvious fit for ChittyOS health/beacon watching, currently done with hooks or not at all.
• .lsp.json — not needed today; noting for completeness.
• --plugin-dir accepts a .zip, and --plugin-url loads a hosted archive (session-only). Gives a CI-artifact test path.
• claude plugin init <name> scaffolds a skills-directory plugin that auto-loads as <name>@skills-dir with no marketplace step — the right shape for local iteration before promoting into ChittyMarket.
• claude plugin validate --strict treats warnings as errors — use this in CI, not the lenient form.

Revised acceptance criteria (additive)

• chittyos-core ships settings.json activating its canonical agent — the "full skin" deliverable
• Evaluate bin/ for can chitty and scripts/ distribution
• Evaluate monitors/ for ChittyOS health/beacon watching
• README.md in every plugin (currently 1/16)
• CI runs claude plugin validate --strict per plugin

[chitcommit]

RESOLVED: the multi-runtime projection problem largely does not exist

OpenClaw bundle formats supports three external bundle formats natively — Codex, Claude, and Cursor:

Claude bundles — detected via .claude-plugin/plugin.json or manifestless default layout. Consumes skills/, commands/, agents/, hooks/, .mcp.json, .lsp.json, settings.json. commands/ is processed as skill content; settings.json is imported as embedded defaults; .lsp.json merges into OpenClaw defaults.

"Claude markdown command files and Cursor command markdown both work through the normal OpenClaw skill loader"

Codex bundles — .codex-plugin/plugin.json + skills/, hooks/, .mcp.json, .app.json.
Cursor bundles — .cursor-plugin/plugin.json + skills/, .cursor/…, .mcp.json.

Every runtime directory we maintain is redundant

ChittyMarket dir	Why it's unnecessary
openclaw-agents/	OpenClaw reads the Claude bundle directly — no conversion step exists to justify it
codex-skills/	Codex SKILL.md is the same name+description frontmatter format as Claude's (openai/skills)
chatgpt-apps/	Byte-identical to claude-skills/; MCP is the shared substrate
claude-skills/	Same — should be the one canonical tree

Every runtime either reads the Claude bundle natively (OpenClaw), uses an identical skill format (Codex/Cursor), or reaches tools over MCP (ChatGPT). There is no format transform anywhere in the chain.

Final design — replaces the chitty.runtimes projection map entirely

One canonical artifact tree, plus thin per-runtime manifests, exactly as cloudflare/skills does it:

plugins/<name>/
  skills/            <- ONE tree
  agents/
  hooks/hooks.json
  .mcp.json
  settings.json
  bin/
  README.md
  .claude-plugin/plugin.json    <- thin
  .codex-plugin/plugin.json     <- thin, only if Codex needs its own listing
  .cursor-plugin/plugin.json    <- thin, only if Cursor needs its own listing

chittyagent-dispatch generates manifests, never artifact copies. Its job shrinks to emitting 2–3 small JSON files per plugin.

chitty.* extension keys are then needed only for what genuinely has no upstream equivalent: service requires (bindings by reference) and declared conflicts. Runtime targeting is expressed by which manifest files exist — not by a projection map.

Revised deliverable order

1. Delete chatgpt-apps/, codex-skills/, openclaw-agents/; consolidate on skills/ + agents/. Verify each runtime still resolves.
2. Adopt existing upstream components (settings.json, bin/, hooks/, .mcp.json, README.md) — see adoption audit above.
3. claude plugin validate --strict in CI.
4. Thin per-runtime manifests where a separate listing is actually wanted.
5. chitty.* extensions last, and only for requires/conflicts.

The work is now mostly deletion and adoption. No new container format is required — which inverts this issue's original premise for the third and final time.

[chitcommit]

Duplication audit CLOSED — all four runtime directories confirmed redundant

Directory	Compared against	Result
chatgpt-apps/	claude-skills/	byte-identical
codex-skills/<s>/SKILL.md	skills/<s>/SKILL.md	identical (4/4 sampled: capability-governor, capability-registry-audit, chitty-deploy, chitty-health)
openclaw-agents/*.yaml	agents/*.md	trivial reformat — the YAML is the markdown frontmatter with --- delimiters stripped; identical name, description, and embedded <example> blocks

The openclaw-agents/ case is the weakest justification of the three: it is a delimiter change, and OpenClaw reads Claude bundles natively (.claude-plugin/plugin.json + agents/ + skills/ + hooks/ + .mcp.json + settings.json), so even the reformat buys nothing.

Every projection in this repo is a copy. There is no transform to preserve.

Confirmed live: OpenClaw 2026.6.11 is installed on the chittyserv VM with state at ~/.openclaw, so the native-bundle path can be verified empirically rather than assumed — point OpenClaw at a plugin directory and confirm the agents load from agents/ with openclaw-agents/ deleted.

Deliverable 1 is now fully specified

Delete chatgpt-apps/, codex-skills/, openclaw-agents/, and consolidate claude-skills/ into skills/. Then verify per runtime:

• Claude Code: claude --plugin-dir ./plugins/<name> loads skills + agents
• OpenClaw: bundle import resolves agents from agents/ (installed locally — testable now)
• Codex: SKILL.md resolves from skills/
• ChatGPT: MCP tool defs resolve from the single canonical location

Removes roughly half the artifact tree and eliminates the drift surface that made these copies dangerous — nothing today keeps them in sync.