docs(skills): package adoption-router skill

Author: xiaojiou176

CHANGELOG.md

@@ -6,6 +6,12 @@ All notable changes to this repository will be documented in this file.
 
 ### Changed
 
+- added a registry-shaped `manifest.yaml` for the repo-owned
+  `cortexpilot-adoption-router` skill inside the coding-agent bundle, then
+  synced the distribution contract, skills quickstart, and Codex / Claude Code /
+  OpenClaw starter docs so CortexPilot can truthfully describe one cross-tool
+  skill artifact as `publish-ready but deferred` without claiming any live
+  marketplace or registry listing
 - added a repo-owned workflow/dependency/security closeout lane by bootstrapping
   pinned `actionlint`, `zizmor`, `trivy`, `gitleaks`, and `trufflehog`
   binaries through `scripts/lib/release_tool_helpers.sh`; the same slice adds

DISTRIBUTION.md

@@ -49,7 +49,7 @@ MCP / npm package release.
 | Claude Code starter | `starter-only` | Project-local `.claude` and `.mcp.json` starter | `examples/coding-agents/claude-code/` | local project wiring only | keep truthful; do not relabel as marketplace package |
 | OpenClaw starter | `starter-only` | Local config seed for the same read-only MCP and compatible bundle | `examples/coding-agents/openclaw/` | local config + local plugin path | keep truthful; do not relabel as ClawHub publication |
 | Cross-tool coding-agent bundle | `bundle-compatible` | Local bundle compatible with Codex local marketplace installs, Claude plugin-dir development, and OpenClaw local plugin loading | `examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/` | local bundle metadata + repo-aware MCP wrapper | keep local-install contract; no published listing claim |
-| Repo-owned skill in the bundle | `starter-only` | Routing skill for honest adoption path selection | shipped inside the local bundle | repo-owned skill only | keep repo-owned; not a marketplace item |
+| Repo-owned skill in the bundle | `publish-ready but deferred` | Cross-tool routing skill with `SKILL.md` + `manifest.yaml` for honest adoption path selection across Codex / Claude Code / OpenClaw style installs | `examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/` | repo-owned skill contract, bundle-scoped today, no live registry listing | keep truthful: package-ready metadata exists, but official marketplace / registry submissions are still later actions |
 | `@cortexpilot/frontend-api-client` | `publish-ready but deferred` | Thin JS/TS client for control-plane reads and guarded operator add-ons | package metadata + README are publish-ready, but the official install story is still clone / vendor reuse until the first npm release exists | HTTP API with token / mutation-role expectations | publish later only after the first public package release is intentionally cut |
 | `@cortexpilot/frontend-api-contract` | `publish-ready but deferred` | Generated route / query / type boundary for frontend consumers | package metadata + README are publish-ready, but the official install story is still clone / vendor reuse until the first npm release exists | typed contract layer only | publish later only after the first public package release is intentionally cut |
 | `@cortexpilot/frontend-shared` | `not standalone distribution unit` | Repo-owned presentation substrate for dashboard / desktop / future web surfaces | repo-local package only | frontend presentation helpers only | keep repo-owned for now |

docs/distribution/index.html

@@ -363,6 +363,14 @@ <h2>Current distribution matrix</h2>
                 <td>Local bundle metadata + plugin-scoped read-only MCP</td>
                 <td>Keep local-first; do not call it a published listing.</td>
               </tr>
+              <tr>
+                <td><strong>Repo-owned adoption-router skill</strong></td>
+                <td><span class="badge starter">publish-ready but deferred</span></td>
+                <td>Cross-tool skill artifact with <code>SKILL.md</code> plus <code>manifest.yaml</code> for Codex / Claude Code / OpenClaw-compatible installs.</td>
+                <td><code>examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/</code></td>
+                <td>Repo-owned skill contract, bundle-scoped today, no live registry listing</td>
+                <td>Keep the artifact honest: metadata and semver are present, but any official registry submission is still a later external action.</td>
+              </tr>
               <tr>
                 <td><strong>@cortexpilot/frontend-api-client</strong></td>
                 <td><span class="badge starter">publish-ready but deferred</span></td>

docs/skills/index.html

@@ -245,6 +245,13 @@ <h2>How to use skills today</h2>
           instead of reconstructing Codex / Claude Code / OpenClaw config files
           from scratch.
         </p>
+        <p>
+          The current bundle now carries one registry-shaped skill artifact too:
+          <code>examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/manifest.yaml</code>.
+          That makes the adoption-router skill package-ready across Codex /
+          Claude Code / OpenClaw style installs without pretending any live
+          marketplace or registry submission already exists.
+        </p>
       </section>
 
       <section class="section">
@@ -256,10 +263,13 @@ <h2>Minimal vendored skill-pack layout</h2>
   README.md
   docs/README.md
   AGENTS.md
-  .agents/skills/&lt;chosen-skill&gt;/</code></pre>
+  .agents/skills/&lt;chosen-skill&gt;/
+    SKILL.md
+    manifest.yaml</code></pre>
         <ol>
           <li>Copy the three truth files first: <code>README.md</code>, <code>docs/README.md</code>, and <code>AGENTS.md</code>.</li>
           <li>Copy only the skill folders you truly want the agent to reuse; do not mirror the whole repo just to say “skills exist.”</li>
+          <li>Keep the tracked <code>manifest.yaml</code> with the skill whenever the host tool or future registry expects machine-readable metadata.</li>
           <li>Keep the skill paired with the same repo-owned read-only MCP command when the workflow needs machine-readable inspection.</li>
           <li>Preserve the stop-signs inside the skill: hosted, write-MCP, and plugin/store claims stay frozen until the repo truth changes.</li>
         </ol>
@@ -278,7 +288,7 @@ <h3>Claude Code</h3>
           </article>
           <article class="card">
             <h3>OpenClaw</h3>
-            <p>Use skills as an adaptation layer for repo truth. OpenClaw has real plugin and skills surfaces, but CortexPilot currently lands on the integration-and-skills side first rather than claiming an official shipped plugin.</p>
+            <p>Use skills as an adaptation layer for repo truth. OpenClaw has real plugin and skills surfaces, and CortexPilot now carries a ClawHub-shaped <code>manifest.yaml</code> for its shared adoption-router skill, but it still lands on the integration-and-skills side first rather than claiming an official shipped plugin.</p>
           </article>
         </div>
       </section>
@@ -322,7 +332,10 @@ <h3>OpenClaw</h3>
             <p>
               OpenClaw already has real skills, a workspace path, and a public registry/catalog, so
               CortexPilot should fit as repo truth + proof + read-only MCP guidance rather than
-              pretending to be the native OpenClaw plugin itself.
+              pretending to be the native OpenClaw plugin itself. The tracked
+              <code>manifest.yaml</code> is there so the shared skill has
+              registry-shaped metadata ready when later external submission
+              actually happens.
             </p>
           </article>
         </div>
@@ -346,7 +359,7 @@ <h2>What this page is not claiming</h2>
           <li>not a hosted skill registry service</li>
         </ul>
         <p>
-          The truthful product story is smaller but stronger: the repository already gives teams reusable, inspectable skill playbooks that align with the real Command Tower / MCP / Proof &amp; Replay contract.
+          The truthful product story is smaller but stronger: the repository already gives teams reusable, inspectable skill playbooks that align with the real Command Tower / MCP / Proof &amp; Replay contract, and the shared adoption-router skill now includes registry-shaped metadata without skipping ahead to a fake published-listing claim.
         </p>
       </section>
 

examples/coding-agents/README.md

@@ -67,6 +67,7 @@ examples/coding-agents/
     .mcp.json
     README.md
     skills/cortexpilot-adoption-router/SKILL.md
+    skills/cortexpilot-adoption-router/manifest.yaml
 ```
 
 ## Shared read-only MCP wiring
@@ -101,6 +102,10 @@ That bundle is intended for:
 - pairing with the shared read-only MCP example above
 
 It is intentionally not framed as a published Codex Plugin Directory entry.
+What is now true, though, is that the shared bundle already carries a
+registry-shaped `manifest.yaml` for the bundled `cortexpilot-adoption-router`
+skill, so the repo can treat that skill as **publish-ready but deferred**
+without pretending an official Codex listing already exists.
 
 ## Claude Code
 
@@ -113,6 +118,8 @@ The example shows:
 - one subagent prompt
 - one tracked project-local `.mcp.json`
 - the shared read-only MCP config path to pair with them
+- one bundle-shipped `manifest.yaml` for the shared `cortexpilot-adoption-router`
+  skill
 
 ## OpenClaw
 
@@ -125,5 +132,7 @@ The truthful story is:
 - OpenClaw has native plugin and skills surfaces
 - CortexPilot currently ships a compatible local bundle example, not a
   published registry item
+- that bundle now includes a registry-shaped `manifest.yaml` for the shared
+  `cortexpilot-adoption-router` skill
 - pair the bundle with the shared read-only MCP config and repo-owned proof /
   replay surfaces

examples/coding-agents/claude-code/README.md

@@ -11,6 +11,8 @@ workflows without inventing a published marketplace package.
 - `../mcp/readonly.mcp.json.example`: the shared read-only MCP config example
 - `../plugin-bundles/cortexpilot-coding-agent-bundle/`: a local plugin-dir
   bundle with the same skill plus plugin-scoped MCP wiring
+- `../plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/manifest.yaml`:
+  registry-shaped metadata for the shared skill artifact
 
 ## Suggested setup
 

examples/coding-agents/codex/README.md

@@ -12,6 +12,8 @@ This folder shows the narrowest truthful CortexPilot setup for Codex:
 - `../mcp/readonly.mcp.json.example`: shared read-only MCP config example
 - `../plugin-bundles/cortexpilot-coding-agent-bundle/`: compatible local skill
   bundle with Codex metadata plus the same repo-owned adoption router skill
+- `../plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/manifest.yaml`:
+  registry-shaped metadata for that shared skill
 
 ## Suggested setup
 

examples/coding-agents/openclaw/README.md

@@ -11,6 +11,11 @@ truthful CortexPilot position inside that ecosystem.
    examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/
    ```
 
+   That bundle now includes
+   `skills/cortexpilot-adoption-router/manifest.yaml`, so the same repo-owned
+   skill already has ClawHub-style metadata even though no public listing is
+   live yet.
+
 2. Pair it with one of the tracked OpenClaw MCP/config examples:
 
    ```text

examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/README.md

@@ -13,11 +13,25 @@ This bundle keeps one repo-owned starter pack compatible with:
 - `.mcp.json`: plugin-scoped read-only MCP wiring
 - `skills/cortexpilot-adoption-router/SKILL.md`: route the job to the right
   CortexPilot lane without overclaiming
+- `skills/cortexpilot-adoption-router/manifest.yaml`: registry-shaped skill
+  metadata with semver, host compatibility, and non-claim boundaries
 - `commands/cortexpilot-proof.md`: Claude-style proof-first command
 - `agents/cortexpilot-reviewer.md`: Claude-style focused reviewer prompt
 - `bin/run-cortexpilot-readonly-mcp.sh`: repo-aware wrapper for the real
   read-only MCP server
 
+## Skill packaging truth
+
+The adoption-router skill now ships with both:
+
+- `SKILL.md` for repo-owned playbook behavior
+- `manifest.yaml` for registry-shaped metadata and semver
+
+That means the bundle can honestly say it already contains one **cross-tool
+skill artifact** for Codex / Claude Code / OpenClaw style installs. It still
+does **not** mean a live public listing already exists in any of those
+ecosystems.
+
 ## How the MCP wrapper behaves
 
 The wrapper works in two truthful modes:

examples/coding-agents/plugin-bundles/cortexpilot-coding-agent-bundle/skills/cortexpilot-adoption-router/manifest.yaml

@@ -0,0 +1,58 @@
+schema_version: 1
+name: cortexpilot-adoption-router
+display_name: CortexPilot Adoption Router
+version: 0.1.0
+status: publish-ready-but-deferred
+summary: >
+  Repo-owned cross-tool skill that routes Codex, Claude Code, and OpenClaw-style
+  workflows to the right CortexPilot adoption lane without overclaiming hosted,
+  write-capable MCP, or published listing support.
+homepage: https://github.com/xiaojiou176-open/CortexPilot-public
+repository: https://github.com/xiaojiou176-open/CortexPilot-public
+license: MIT
+authors:
+  - name: CortexPilot
+entrypoints:
+  skill_markdown: SKILL.md
+  bundle_root: ../../
+  codex_plugin_metadata: ../../.codex-plugin/plugin.json
+  claude_plugin_metadata: ../../.claude-plugin/plugin.json
+  shared_mcp_config: ../../.mcp.json
+compatibility:
+  codex:
+    mode: local marketplace bundle or vendored skill
+    published_listing: false
+  claude_code:
+    mode: local plugin-dir bundle or vendored skill
+    published_listing: false
+  openclaw:
+    mode: local bundle or copied skill workspace item
+    published_listing: false
+capabilities:
+  - route to the truthful CortexPilot adoption lane
+  - keep read order anchored to repo docs and MCP truth
+  - preserve hosted, OAuth, and write-MCP stop signs
+boundaries:
+  hosted_operator: false
+  write_capable_mcp: false
+  oauth_login: false
+  official_listing_live: false
+canonical_docs:
+  - ../../README.md
+  - ../../../../README.md
+  - ../../../../docs/README.md
+  - ../../../../docs/compatibility/index.html
+  - ../../../../docs/integrations/index.html
+  - ../../../../docs/skills/index.html
+  - ../../../../docs/mcp/index.html
+distribution_notes:
+  shipped_shape: repo-owned skill artifact inside the local coding-agent bundle
+  current_claim: publish-ready metadata is present, but no external Codex / Claude Code / OpenClaw listing is live yet
+  later_phase:
+    - Codex directory submission
+    - Claude Code marketplace submission
+    - OpenClaw or ClawHub registry submission
+verification:
+  repo_commands:
+    - npm run docs:check
+    - bash scripts/check_repo_hygiene.sh