From e5b0f0aeec2f657c5f79f26c6ec78f4f454d749a Mon Sep 17 00:00:00 2001
From: Amit Kotlovski <amit@amitkot.com>
Date: Sun, 7 Jun 2026 12:27:25 +0300
Subject: [PATCH] Add cross-agent skills compatibility plan

---
 .../plans/cross-agent-skills-compatibility.md | 48 +++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 docs/plans/cross-agent-skills-compatibility.md

diff --git a/docs/plans/cross-agent-skills-compatibility.md b/docs/plans/cross-agent-skills-compatibility.md
new file mode 100644
index 0000000..fdb5ef0
--- /dev/null
+++ b/docs/plans/cross-agent-skills-compatibility.md
@@ -0,0 +1,48 @@
+# Cross-Agent Skills Compatibility Plan
+
+## Summary
+
+Make the repo installable through `npx skills`, `gh skill` / `gh skills`, and Codex skills/plugins while preserving the existing Claude plugin marketplace as the source of truth.
+
+Use an additive compatibility layer: do not move existing plugin folders or break `.claude-plugin/marketplace.json`.
+
+## Key Changes
+
+- Add a generated root `skills/` tree containing copies of every existing `*/skills/*/SKILL.md` skill and its local resources.
+- Add a generator/validator script that rebuilds `skills/` from the existing plugin folders, so duplicated skill content is mechanical and not hand-maintained.
+- Add Codex plugin metadata alongside current Claude metadata:
+  - Generate `<plugin>/.codex-plugin/plugin.json` from each existing `<plugin>/.claude-plugin/plugin.json`.
+  - Add a root Codex marketplace file using the Codex plugin schema, sourced from the existing marketplace entries.
+- Keep existing Claude install commands and plugin marketplace behavior unchanged.
+
+## Compatibility Fixes
+
+- Fix current `gh skill publish --dry-run` errors:
+  - Quote or fold the long `evidence-over-speculation` description so YAML parses correctly.
+  - Change `ralph` `allowed-tools` from YAML array to a string.
+- Add recommended `license: Apache-2.0` frontmatter to all skills.
+- Leave long skill-body warnings as non-blocking unless the implementation naturally splits references; the installable target is "passes validation," not a broad content refactor.
+
+## Docs And Workflow
+
+- Update `README.md` with three install paths:
+  - Claude Code plugin marketplace: existing `/plugin marketplace add ...`.
+  - Agent skills: `npx skills` and `gh skill install ... --agent codex|claude-code`.
+  - Codex plugins: install/add marketplace instructions for the new `.codex-plugin` metadata.
+- Update the marketplace-author skill/docs so future edits bump versions and regenerate all compatibility surfaces.
+- Add a `just` task such as `just generate-compat` and include it in `just audit-public`.
+
+## Test Plan
+
+- Run `gh skill publish --dry-run` and require zero errors.
+- Run a local install smoke test with `gh skill install . --from-local <skill-name> --agent codex --scope project` into a temp repo.
+- Validate JSON with `jq` for all `.claude-plugin`, `.codex-plugin`, and marketplace files.
+- Run the existing `just audit-public`.
+- If available during implementation, run `npx skills` discovery/install against the local repo or package and document the exact verified command.
+
+## Assumptions
+
+- Existing top-level plugin folders remain canonical.
+- The generated root `skills/` directory uses copied files, not symlinks, for GitHub and npm installer compatibility.
+- `lspmux-lsp` remains plugin-only because it has no `skills/*/SKILL.md`.
+- `gh skill` preview behavior is based on the installed local CLI version tested here: `gh 2.92.0`.