fix(manifest): Agent Plugins $schema swap breaks skill loading on oh-my-pi (omp)

[rager306]

---

title: fix(manifest): Agent Plugins $schema swap breaks skill loading on oh-my-pi (omp)

Summary

Since #1341 conformed root plugin.json to the Agent Plugins v1.0.0 $schema, the oh-my-pi (omp) marketplace install documented in the README loads 3 of 33 skills. All /skill:<name> commands (/skill:ce-setup, /skill:ce-plan, /lfg, ...) are missing and skill:// resolution fails after a session restart. This is the observed breakage #1342's posture anticipated ("strict Agent Plugins clients loading 4 of 32 skills") — omp 17.3.5 is a shipping conformant client, so this is no longer a hypothetical.

Environment

• Host: oh-my-pi (omp) 17.3.5 (@oh-my-pi/pi-coding-agent), Linux

• Plugin: compound-engineering@compound-engineering-plugin 3.22.0

• Install path used: the README-documented flow

  omp plugin marketplace add EveryInc/compound-engineering-plugin
  omp plugin install compound-engineering@compound-engineering-plugin

Problem

Root plugin.json declares "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json" (added in #1341). omp 17.3.5 routes packages that declare this standard to its strict agent-plugins discovery provider (priority 75) and excludes them from the lenient legacy omp-plugins provider (priority 90) via legacyProviderAllowed() — for a standard package, surface === "skills" returns false.

The agent-plugins provider validates each SKILL.md frontmatter against the closed Agent Skills field set (name, description, license, allowed-tools, metadata, compatibility); any other key rejects the skill (validateAgentSkillFrontmatter, mirroring the skills-ref reference validator). Additionally allowed-tools must be a string.

Rejection breakdown across the 33 skills in 3.22.0:

Cause	Count	Example
argument-hint (unknown field)	28	ce-brainstorm, ce-plan, ce-work, lfg, ...
disable-model-invocation (unknown field)	8	ce-setup, ce-polish, ce-sweep, ...
allowed-tools is a YAML list, not a string	1	ce-proof
Conforming (loads)	3	ce-commit, ce-riffrec-feedback-analysis, ce-worktree

Net result: the documented omp install yields a plugin whose skills are invisible. omp plugin list shows the plugin installed and enabled; the session skill registry simply contains none of them (verified against omp 17.3.5 source: src/discovery/agent-plugin-format.ts validateAgentSkillFrontmatter, src/discovery/agent-plugins.ts scanStandardSkills, src/discovery/omp-plugins.ts allowedRoots).

Note: #1342 states the skill-frontmatter gap is "load-bearing on Claude Code" and defers conformant emission to a converter target. Nothing in this issue argues against that for Claude Code — but the current root manifest now actively breaks a documented, shipping install target (omp), which the plan did not anticipate ("No shipping conformant Agent Plugins client is known as of 2026-08-06").

Proposed fix

Options, in order of recommendation:

1. Drop the $schema declaration from root plugin.json (revert the conformance swap, keep the metadata mirror). Unparseable/absent $schema falls back to legacy conventions on every client: omp's legacy omp-plugins provider then loads all 33 skills (it requires only description, which every skill has), agy accepts the manifest ({name, version} is its verified minimal form, per docs/specs/antigravity.md), and Grok/Codex/Claude paths are unaffected. This restores all documented hosts today at the cost of deferring docs(plans): add Agent Plugins v1.0.0 manifest conformance plan #1342's conformance goal until the emission path exists.
2. Implement the deferred converter target now (from docs(plans): add Agent Plugins v1.0.0 manifest conformance plan #1342's scope boundaries): emit a conformant package that relocates argument-hint / disable-model-invocation under metadata: and serializes allowed-tools as a string, then point the marketplace source at the emitted tree. Larger change; preserves the conformance bet.
3. Upstream argument-hint / disable-model-invocation into the Agent Skills / Agent Plugins spec (already listed as follow-up in docs(plans): add Agent Plugins v1.0.0 manifest conformance plan #1342) — unblocks strict clients long-term but doesn't fix today's breakage.

Workaround (user-side)

Remove the $schema line from the cached plugin manifest and restart omp:

# ~/.omp/plugins/cache/plugins/compound-engineering-plugin___compound-engineering___3.22.0/plugin.json

Re-applies after every plugin upgrade.

Security Disclosure

No security-relevant changes.

[tmchow]

Confirmed against omp 17.3.5 source (src/discovery/agent-plugin-format.ts — the $schema prefix routes to the strict provider; validateAgentSkillFrontmatter rejects 30/33 skills). Same trigger as #1412.

Fix: #1426 (merged) removes the $schema from root plugin.json, so omp falls back to its lenient legacy provider and loads all 33 skills. It ships in the next release; until then the workaround in this issue stands.

Follow-up: #1427 extends the CI guard so the $schema cannot return while any skill frontmatter is non-conformant (option 2/3 from this issue — conformant emission or upstreaming the keys — remains the long-term path).

[tmchow]

Fixed on main: #1426 removed the root $schema (omp falls back to its lenient provider and loads all 33 skills); #1427 makes that unconditional in CI and records the posture in docs/specs/agent-plugins.md. Ships in the next release. Upstream ask for a per-host override: can1357/oh-my-pi#8853.