docs(solutions): capture why the Agent Plugins $schema is a host routing switch

[tmchow]

Summary

Captures the learning behind #1412 / #1411 as a durable solution doc: the Agent Plugins $schema on root plugin.json is a routing switch, not metadata — Codex >=0.147 and oh-my-pi >=17.3 both branch on its prefix into strict paths (8 KB skill truncation; closed-set frontmatter validation) that broke 26–30 of 33 skills. The doc records the mechanism in each host's own source, why no root manifest can satisfy Claude Code + both strict hosts, the fix (#1426, #1427), what didn't work, and how to verify a future host before adopting a spec field.

docs/solutions/integrations/agent-plugins-schema-is-a-host-routing-switch.md

Grounding: claims verified against origin/main, Codex PR #37027's diff, and the unpacked omp 17.3.5 package; three citations corrected during validation (legacyProviderAllowed location, ce-product-pulse also has list allowed-tools, MAX_SKILL_PROMPT_BYTES lives in core-skills/src/lib.rs).

Related: #1411, #1412, #1426, #1427, docs/specs/agent-plugins.md.

Security Disclosure

No security-relevant changes.

Agent Disclosure

• Model: Claude Code · claude-fable-5

[cursor]

PR Summary

^{Cursor Bugbot is generating a summary for commit 8120a5b. Configure here.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8120a5b603

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Land the referenced prevention guard before documenting it

This commit is based directly on PR #1426 (961d90f), so the reviewed tree does not contain the claimed PR #1427 posture: tests/codex-skill-prompt-budget.test.ts still forbids the schema only while a skill exceeds 8 KB, and docs/specs/agent-plugins.md still instructs maintainers to restore it once the allowlist is empty. If this commit is consumed without the separate #1427 change, the solution and Prevention sections falsely promise an unconditional guard and can direct maintainers back to the routing regression; rebase this documentation onto the guard change or describe the actual conditional posture.

Useful? React with 👍 / 👎.