From 15e583ae38b9b558936c17db78289b167851ac97 Mon Sep 17 00:00:00 2001
From: "Yifeng[Terry] Yu" <125581657+xiaojiou176@users.noreply.github.com>
Date: Wed, 8 Apr 2026 01:40:09 -0700
Subject: [PATCH 1/4] Add DealWatch and CortexPilot public skills

---
 marketplaces/default.json                    | 26 +++++++++++
 skills/cortexpilot-adoption-router/README.md | 19 ++++++++
 skills/cortexpilot-adoption-router/SKILL.md  | 46 ++++++++++++++++++++
 skills/dealwatch-readonly-builder/README.md  | 19 ++++++++
 skills/dealwatch-readonly-builder/SKILL.md   | 22 ++++++++++
 5 files changed, 132 insertions(+)
 create mode 100644 skills/cortexpilot-adoption-router/README.md
 create mode 100644 skills/cortexpilot-adoption-router/SKILL.md
 create mode 100644 skills/dealwatch-readonly-builder/README.md
 create mode 100644 skills/dealwatch-readonly-builder/SKILL.md

diff --git a/marketplaces/default.json b/marketplaces/default.json
index 1120ee86..0ac0b27b 100644
--- a/marketplaces/default.json
+++ b/marketplaces/default.json
@@ -471,6 +471,32 @@
                 "verification",
                 "sample"
             ]
+        },
+        {
+            "name": "dealwatch-readonly-builder",
+            "source": "./dealwatch-readonly-builder",
+            "description": "Safe-first DealWatch builder route for local-first compare, proof, and read-only MCP workflows.",
+            "category": "integration",
+            "keywords": [
+                "dealwatch",
+                "builder",
+                "mcp",
+                "compare",
+                "local-first"
+            ]
+        },
+        {
+            "name": "cortexpilot-adoption-router",
+            "source": "./cortexpilot-adoption-router",
+            "description": "Route CortexPilot users to the right read-only MCP, builder, and proof-first adoption lane without overclaiming hosted support.",
+            "category": "productivity",
+            "keywords": [
+                "cortexpilot",
+                "router",
+                "mcp",
+                "proof",
+                "adoption"
+            ]
         }
     ]
 }
diff --git a/skills/cortexpilot-adoption-router/README.md b/skills/cortexpilot-adoption-router/README.md
new file mode 100644
index 00000000..2fd9a310
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/README.md
@@ -0,0 +1,19 @@
+# CortexPilot Adoption Router
+
+This public skill package exposes the current CortexPilot adoption router as a
+registry-friendly skill surface.
+
+It is designed for host ecosystems that want a single skill folder with a
+`SKILL.md` contract and semver-friendly manifest.
+
+## What it does
+
+- routes operators to the right CortexPilot adoption lane
+- keeps read-only MCP vs starter vs builder boundaries honest
+- points back to the current public repo and Pages front door
+
+## What it does not claim
+
+- no hosted operator service
+- no write-capable public MCP
+- no live marketplace / registry listing unless independently confirmed
diff --git a/skills/cortexpilot-adoption-router/SKILL.md b/skills/cortexpilot-adoption-router/SKILL.md
new file mode 100644
index 00000000..0c0fb86a
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/SKILL.md
@@ -0,0 +1,46 @@
+---
+name: cortexpilot-adoption-router
+description: Route the current job to the right CortexPilot surface without overclaiming hosted, write-capable MCP, or published plugin support.
+---
+
+# Purpose
+
+Use this skill when a coding-agent workflow needs the shortest honest CortexPilot
+entrypoint.
+
+The job is to pick the right adoption lane first instead of treating every host
+tool as the same kind of plugin system.
+
+# Read Order
+
+1. `README.md`
+2. `docs/README.md`
+3. `docs/compatibility/index.html`
+4. `docs/integrations/index.html`
+5. One deeper lane only:
+   - `docs/mcp/index.html`
+   - `docs/skills/index.html`
+   - `docs/builders/index.html`
+   - `docs/use-cases/index.html`
+
+# Use It To Choose A Lane
+
+- Start with **read-only MCP** when the first need is machine-readable
+  inspection.
+- Start with **skills** when the first need is repeatable repo-owned behavior.
+- Start with **builders** when the first need is package-level reuse.
+- Start with **use cases** when the first need is proof-first product
+  understanding.
+
+# Guardrails
+
+- Do not describe CortexPilot as a hosted operator product.
+- Do not describe the public MCP surface as write-capable.
+- Do not claim this bundle is a published Codex or OpenClaw listing.
+- Do not describe Claude Code as if it has a CortexPilot marketplace package.
+- Keep `task_contract` as the only execution authority.
+
+# Done Signal
+
+The adoption path is correct only when the chosen lane matches the real job and
+the wording stays below official-listing or hosted-product claims.
diff --git a/skills/dealwatch-readonly-builder/README.md b/skills/dealwatch-readonly-builder/README.md
new file mode 100644
index 00000000..b197b42d
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/README.md
@@ -0,0 +1,19 @@
+# DealWatch Read-only Builder
+
+This public skill package turns the current DealWatch builder front door into a
+registry-friendly skill surface.
+
+It is meant for host ecosystems that accept skill directories built around a
+`SKILL.md` contract plus a manifest.
+
+## What it does
+
+- routes builders to the safe first DealWatch entry path
+- keeps the workflow local-first and read-only
+- points back to the current builder starter pack and compare preview loop
+
+## What it does not claim
+
+- no hosted DealWatch control plane
+- no write-side MCP surface
+- no official marketplace listing unless the registry itself confirms one
diff --git a/skills/dealwatch-readonly-builder/SKILL.md b/skills/dealwatch-readonly-builder/SKILL.md
new file mode 100644
index 00000000..f1c44c3d
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/SKILL.md
@@ -0,0 +1,22 @@
+---
+name: dealwatch-readonly-builder
+description: Safe-first builder route for DealWatch. Start with runtime readiness and the builder starter pack before deeper reads.
+---
+
+# DealWatch Read-only Builder
+
+Use DealWatch as a local-first, read-only decision backend.
+
+## Safe First Flow
+
+1. `get_runtime_readiness`
+2. `get_builder_starter_pack`
+3. `compare_preview`
+4. one read-only detail route
+
+## Do Not Assume
+
+- write-side MCP
+- hosted control plane
+- official marketplace or registry listing
+- autonomous recommendation support

From d8ccf056ab4f2db5a8dd0eb33219bc4ac3f48fa8 Mon Sep 17 00:00:00 2001
From: "Yifeng[Terry] Yu" <125581657+xiaojiou176@users.noreply.github.com>
Date: Wed, 8 Apr 2026 15:32:05 -0700
Subject: [PATCH 2/4] Refine DealWatch and CortexPilot skill bundles

---
 marketplaces/default.json                     |  4 +-
 skills/cortexpilot-adoption-router/README.md  | 26 ++++--
 skills/cortexpilot-adoption-router/SKILL.md   | 93 ++++++++++++-------
 .../references/example-tasks.md               |  6 ++
 .../references/mcp-install.md                 | 25 +++++
 .../references/tool-map.md                    | 27 ++++++
 skills/dealwatch-readonly-builder/README.md   | 26 ++++--
 skills/dealwatch-readonly-builder/SKILL.md    | 73 ++++++++++++---
 .../references/example-tasks.md               |  6 ++
 .../references/mcp-install.md                 | 26 ++++++
 .../references/tool-map.md                    | 23 +++++
 11 files changed, 270 insertions(+), 65 deletions(-)
 create mode 100644 skills/cortexpilot-adoption-router/references/example-tasks.md
 create mode 100644 skills/cortexpilot-adoption-router/references/mcp-install.md
 create mode 100644 skills/cortexpilot-adoption-router/references/tool-map.md
 create mode 100644 skills/dealwatch-readonly-builder/references/example-tasks.md
 create mode 100644 skills/dealwatch-readonly-builder/references/mcp-install.md
 create mode 100644 skills/dealwatch-readonly-builder/references/tool-map.md

diff --git a/marketplaces/default.json b/marketplaces/default.json
index 0ac0b27b..af0fc12d 100644
--- a/marketplaces/default.json
+++ b/marketplaces/default.json
@@ -475,7 +475,7 @@
         {
             "name": "dealwatch-readonly-builder",
             "source": "./dealwatch-readonly-builder",
-            "description": "Safe-first DealWatch builder route for local-first compare, proof, and read-only MCP workflows.",
+            "description": "Teach the agent how to install and use the published DealWatch read-only MCP package for compare-first grocery workflows.",
             "category": "integration",
             "keywords": [
                 "dealwatch",
@@ -488,7 +488,7 @@
         {
             "name": "cortexpilot-adoption-router",
             "source": "./cortexpilot-adoption-router",
-            "description": "Route CortexPilot users to the right read-only MCP, builder, and proof-first adoption lane without overclaiming hosted support.",
+            "description": "Teach the agent how to install and use the published CortexPilot read-only MCP package and choose the right public lane.",
             "category": "productivity",
             "keywords": [
                 "cortexpilot",
diff --git a/skills/cortexpilot-adoption-router/README.md b/skills/cortexpilot-adoption-router/README.md
index 2fd9a310..7aa19bb7 100644
--- a/skills/cortexpilot-adoption-router/README.md
+++ b/skills/cortexpilot-adoption-router/README.md
@@ -1,19 +1,25 @@
 # CortexPilot Adoption Router
 
-This public skill package exposes the current CortexPilot adoption router as a
-registry-friendly skill surface.
+Public OpenHands skill for connecting the published CortexPilot read-only MCP
+package and choosing the right public lane.
 
-It is designed for host ecosystems that want a single skill folder with a
-`SKILL.md` contract and semver-friendly manifest.
+## What this skill teaches
 
-## What it does
+- how to install the published `cortexpilot-orchestrator==0.1.0a4` MCP package
+- which read-only CortexPilot tools are safe-first
+- how to choose between run/workflow inspection, queue/approval reads, and
+  proof/incident reads
+- which claims stay out of bounds
 
-- routes operators to the right CortexPilot adoption lane
-- keeps read-only MCP vs starter vs builder boundaries honest
-- points back to the current public repo and Pages front door
+## Included files
 
-## What it does not claim
+- `SKILL.md` — the agent-facing prompt
+- `references/mcp-install.md` — exact OpenHands install snippet
+- `references/tool-map.md` — the stable CortexPilot MCP tool map
+- `references/example-tasks.md` — concrete tasks this skill is meant to handle
+
+## Hard boundaries
 
 - no hosted operator service
 - no write-capable public MCP
-- no live marketplace / registry listing unless independently confirmed
+- no first-party marketplace claim unless the host independently confirms it
diff --git a/skills/cortexpilot-adoption-router/SKILL.md b/skills/cortexpilot-adoption-router/SKILL.md
index 0c0fb86a..b38ad6a7 100644
--- a/skills/cortexpilot-adoption-router/SKILL.md
+++ b/skills/cortexpilot-adoption-router/SKILL.md
@@ -1,46 +1,75 @@
 ---
 name: cortexpilot-adoption-router
-description: Route the current job to the right CortexPilot surface without overclaiming hosted, write-capable MCP, or published plugin support.
+description: Teach the agent how to connect the published CortexPilot read-only MCP package, choose the right public lane, and use the stable read-only tools without overclaiming hosted or write-capable support.
+triggers:
+  - cortexpilot
+  - cortexpilot setup
+  - cortexpilot mcp
+  - cortexpilot proof
+  - cortexpilot workflow
 ---
 
-# Purpose
+# CortexPilot Adoption Router
 
-Use this skill when a coding-agent workflow needs the shortest honest CortexPilot
-entrypoint.
+Use this skill when the user needs the shortest truthful path into CortexPilot.
 
-The job is to pick the right adoption lane first instead of treating every host
-tool as the same kind of plugin system.
+## What this skill helps the agent do
 
-# Read Order
+- install the published CortexPilot MCP package
+- choose the right read-only tool for the current job
+- start with one public lane instead of mixing every CortexPilot surface together
+- keep the answer inside the current read-only public boundary
 
-1. `README.md`
-2. `docs/README.md`
-3. `docs/compatibility/index.html`
-4. `docs/integrations/index.html`
-5. One deeper lane only:
-   - `docs/mcp/index.html`
-   - `docs/skills/index.html`
-   - `docs/builders/index.html`
-   - `docs/use-cases/index.html`
+## When to use this skill
 
-# Use It To Choose A Lane
+Use this skill when the user asks to:
 
-- Start with **read-only MCP** when the first need is machine-readable
-  inspection.
-- Start with **skills** when the first need is repeatable repo-owned behavior.
-- Start with **builders** when the first need is package-level reuse.
-- Start with **use cases** when the first need is proof-first product
-  understanding.
+- connect CortexPilot to OpenHands
+- inspect runs or workflows through the public read-only MCP
+- understand which public lane should come first
+- inspect approvals, queue state, proof, compare, or incident summaries without
+  mutating anything
 
-# Guardrails
+## If the MCP is not connected yet
 
-- Do not describe CortexPilot as a hosted operator product.
-- Do not describe the public MCP surface as write-capable.
-- Do not claim this bundle is a published Codex or OpenClaw listing.
-- Do not describe Claude Code as if it has a CortexPilot marketplace package.
-- Keep `task_contract` as the only execution authority.
+Open `references/mcp-install.md` and use the published-package config snippet.
+Do not assume the user has a local checkout of the source repo.
 
-# Done Signal
+## Safe-first workflow
 
-The adoption path is correct only when the chosen lane matches the real job and
-the wording stays below official-listing or hosted-product claims.
+1. `list_runs` or `list_workflows`
+2. `get_run` or `get_workflow`
+3. `list_queue`, `get_pending_approvals`, or `get_diff_gate_state`
+4. `get_run_reports`, `get_compare_summary`, `get_proof_summary`, or
+   `get_incident_summary`
+
+## Tool-selection rule
+
+- choose run/workflow reads for “what is happening now?”
+- choose queue/approval reads for “what is blocked or pending?”
+- choose proof/compare/incident reads only after the user already has one run to
+  inspect
+- do not mix multiple lanes unless the user explicitly asks for a broader audit
+
+## What to return
+
+Return a short answer with:
+
+1. the chosen lane
+2. the next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet
+
+## Guardrails
+
+- no hosted operator service
+- no write-capable public MCP
+- no first-party marketplace claim unless the host independently confirms it
+- keep `task_contract` as the execution authority for real runs; this MCP is
+  read-only inspection only
+
+## Read next
+
+- `references/mcp-install.md`
+- `references/tool-map.md`
+- `references/example-tasks.md`
diff --git a/skills/cortexpilot-adoption-router/references/example-tasks.md b/skills/cortexpilot-adoption-router/references/example-tasks.md
new file mode 100644
index 00000000..c3144ea9
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/example-tasks.md
@@ -0,0 +1,6 @@
+# Example Tasks
+
+- “Connect CortexPilot to OpenHands and inspect the run ledger.”
+- “Show me which CortexPilot MCP tool I should call first.”
+- “Inspect pending approvals or queue state without mutating anything.”
+- “Open proof or incident summaries for one run.”
diff --git a/skills/cortexpilot-adoption-router/references/mcp-install.md b/skills/cortexpilot-adoption-router/references/mcp-install.md
new file mode 100644
index 00000000..4faf6480
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/mcp-install.md
@@ -0,0 +1,25 @@
+# Install The Published CortexPilot MCP
+
+Use the published PyPI package, not a repo-local checkout.
+
+## Published package
+
+- package: `cortexpilot-orchestrator==0.1.0a4`
+- executable: `cortexpilot-readonly-mcp`
+- transport: `stdio`
+
+## OpenHands config example
+
+Add this to `~/.openhands/config.toml`:
+
+```toml
+[mcp]
+stdio_servers = [
+  { name = "cortexpilot-readonly", command = "uvx", args = ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"] }
+]
+```
+
+## Smoke check
+
+After the host attaches the server, request `tools/list` and confirm the
+read-only run/workflow tools are present.
diff --git a/skills/cortexpilot-adoption-router/references/tool-map.md b/skills/cortexpilot-adoption-router/references/tool-map.md
new file mode 100644
index 00000000..08a793e5
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/tool-map.md
@@ -0,0 +1,27 @@
+# CortexPilot MCP Tool Map
+
+## Safe-first tools
+
+1. `list_runs`
+2. `get_run`
+3. `list_workflows`
+4. `get_workflow`
+
+Use these first when the job is “inspect current truth”.
+
+## Queue and approval tools
+
+- `list_queue`
+- `get_pending_approvals`
+- `get_diff_gate_state`
+
+Use these when the job is “inspect blocked or pending work”.
+
+## Proof and incident tools
+
+- `get_run_reports`
+- `get_compare_summary`
+- `get_proof_summary`
+- `get_incident_summary`
+
+Use these after the user already has a specific run in hand.
diff --git a/skills/dealwatch-readonly-builder/README.md b/skills/dealwatch-readonly-builder/README.md
index b197b42d..adfb6c6c 100644
--- a/skills/dealwatch-readonly-builder/README.md
+++ b/skills/dealwatch-readonly-builder/README.md
@@ -1,19 +1,25 @@
 # DealWatch Read-only Builder
 
-This public skill package turns the current DealWatch builder front door into a
-registry-friendly skill surface.
+Public OpenHands skill for connecting the published DealWatch MCP package and
+using its read-only tools safely.
 
-It is meant for host ecosystems that accept skill directories built around a
-`SKILL.md` contract plus a manifest.
+## What this skill teaches
 
-## What it does
+- how to install the published `dealwatch==1.0.1` MCP package
+- which DealWatch MCP tools are safe-first
+- how to move from runtime readiness into compare preview and then into deeper
+  detail reads
+- which claims stay out of bounds
 
-- routes builders to the safe first DealWatch entry path
-- keeps the workflow local-first and read-only
-- points back to the current builder starter pack and compare preview loop
+## Included files
 
-## What it does not claim
+- `SKILL.md` — the agent-facing prompt
+- `references/mcp-install.md` — exact OpenHands install snippet
+- `references/tool-map.md` — the stable DealWatch MCP tool map
+- `references/example-tasks.md` — concrete tasks this skill is meant to handle
+
+## Hard boundaries
 
 - no hosted DealWatch control plane
 - no write-side MCP surface
-- no official marketplace listing unless the registry itself confirms one
+- no first-party marketplace claim unless the host independently confirms it
diff --git a/skills/dealwatch-readonly-builder/SKILL.md b/skills/dealwatch-readonly-builder/SKILL.md
index f1c44c3d..1e1160fd 100644
--- a/skills/dealwatch-readonly-builder/SKILL.md
+++ b/skills/dealwatch-readonly-builder/SKILL.md
@@ -1,22 +1,73 @@
 ---
 name: dealwatch-readonly-builder
-description: Safe-first builder route for DealWatch. Start with runtime readiness and the builder starter pack before deeper reads.
+description: Teach the agent how to connect the published DealWatch MCP package, choose the right read-only tool, and guide the user through the compare-first safe path without claiming hosted or write-capable features.
+triggers:
+  - dealwatch
+  - dealwatch setup
+  - dealwatch mcp
+  - compare preview
+  - watch group
 ---
 
 # DealWatch Read-only Builder
 
-Use DealWatch as a local-first, read-only decision backend.
+Use this skill when the user wants the shortest truthful path into DealWatch.
 
-## Safe First Flow
+## What this skill helps the agent do
+
+- install the published DealWatch MCP package
+- choose the right read-only tool for the current job
+- start with runtime readiness and compare preview before deeper reads
+- keep the answer inside the current local-first boundary
+
+## When to use this skill
+
+Use this skill when the user asks to:
+
+- connect DealWatch to OpenHands
+- check whether DealWatch is ready for a local read-only session
+- compare grocery product URLs before creating durable state
+- inspect watch tasks, watch groups, or recovery state without mutating anything
+
+## If the MCP is not connected yet
+
+Open `references/mcp-install.md` and use the published-package config snippet.
+Do not assume a repo-local checkout is available.
+
+## Safe-first workflow
 
 1. `get_runtime_readiness`
-2. `get_builder_starter_pack`
-3. `compare_preview`
-4. one read-only detail route
+2. `compare_preview`
+3. `get_builder_starter_pack`
+4. `list_watch_tasks` or `list_watch_groups`
+5. one detail read
+6. recovery or notification reads only if the user is already in that lane
+
+## Tool-selection rule
+
+- choose `compare_preview` for “Which URL is the right target?”
+- choose `get_runtime_readiness` for “Is the local runtime healthy?”
+- choose `get_builder_starter_pack` for “How do I connect the agent?”
+- choose watch-task/group reads only after the user already has durable state
+
+## What to return
+
+Return a short answer with:
+
+1. the chosen lane
+2. the next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet
+
+## Guardrails
+
+- no write-side MCP
+- no hosted control plane
+- no first-party marketplace claim unless the host independently confirms it
+- no autonomous recommendation support
 
-## Do Not Assume
+## Read next
 
-- write-side MCP
-- hosted control plane
-- official marketplace or registry listing
-- autonomous recommendation support
+- `references/mcp-install.md`
+- `references/tool-map.md`
+- `references/example-tasks.md`
diff --git a/skills/dealwatch-readonly-builder/references/example-tasks.md b/skills/dealwatch-readonly-builder/references/example-tasks.md
new file mode 100644
index 00000000..e70dcd66
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/example-tasks.md
@@ -0,0 +1,6 @@
+# Example Tasks
+
+- “Connect DealWatch to OpenHands and check whether the runtime is ready.”
+- “Compare these grocery URLs before creating any watch task.”
+- “Show me which read-only DealWatch tool I should call first.”
+- “Inspect one watch group without mutating any state.”
diff --git a/skills/dealwatch-readonly-builder/references/mcp-install.md b/skills/dealwatch-readonly-builder/references/mcp-install.md
new file mode 100644
index 00000000..327078a6
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/mcp-install.md
@@ -0,0 +1,26 @@
+# Install The Published DealWatch MCP
+
+Use the published PyPI package, not a repo-local checkout.
+
+## Published package
+
+- package: `dealwatch==1.0.1`
+- executable: `dealwatch-mcp`
+- transport: `stdio`
+
+## OpenHands config example
+
+Add this to `~/.openhands/config.toml`:
+
+```toml
+[mcp]
+stdio_servers = [
+  { name = "dealwatch", command = "uvx", args = ["--from", "dealwatch==1.0.1", "dealwatch-mcp", "serve"] }
+]
+```
+
+## Smoke check
+
+```bash
+uvx --from dealwatch==1.0.1 dealwatch-mcp list-tools --json
+```
diff --git a/skills/dealwatch-readonly-builder/references/tool-map.md b/skills/dealwatch-readonly-builder/references/tool-map.md
new file mode 100644
index 00000000..0e6cda7b
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/tool-map.md
@@ -0,0 +1,23 @@
+# DealWatch MCP Tool Map
+
+## Safe-first tools
+
+1. `get_runtime_readiness`
+2. `compare_preview`
+3. `get_builder_starter_pack`
+
+Use those three before any deeper watch or recovery reads.
+
+## Detail reads
+
+- `list_watch_tasks`
+- `get_watch_task_detail`
+- `list_watch_groups`
+- `get_watch_group_detail`
+- `get_recovery_inbox`
+- `list_notifications`
+- `get_notification_settings`
+- `list_store_bindings`
+- `get_store_onboarding_cockpit`
+
+Use detail reads only after the safe-first path is already clear.

From d15ecde8452fbd608df7a181fcd66581965482d0 Mon Sep 17 00:00:00 2001
From: "Yifeng[Terry] Yu" <125581657+xiaojiou176@users.noreply.github.com>
Date: Wed, 8 Apr 2026 19:13:50 -0700
Subject: [PATCH 3/4] docs: refresh dealwatch and cortexpilot skill packets

---
 skills/cortexpilot-adoption-router/README.md  | 37 +++++++++----
 skills/cortexpilot-adoption-router/SKILL.md   | 51 ++++++++++--------
 .../cortexpilot-adoption-router/manifest.yaml | 42 +++++++++++++++
 .../references/CAPABILITIES.md                | 33 ++++++++++++
 .../references/DEMO.md                        | 24 +++++++++
 .../references/INSTALL.md                     | 22 ++++++++
 .../references/OPENCLAW_MCP_CONFIG.json       | 10 ++++
 .../references/OPENHANDS_MCP_CONFIG.json      |  8 +++
 .../references/README.md                      | 19 +++++++
 .../references/TROUBLESHOOTING.md             | 35 ++++++++++++
 .../references/example-tasks.md               | 15 ++++--
 .../references/mcp-install.md                 | 25 +++++++--
 .../references/tool-map.md                    | 14 +++--
 skills/dealwatch-readonly-builder/README.md   | 40 ++++++++++----
 skills/dealwatch-readonly-builder/SKILL.md    | 54 +++++++++++--------
 .../dealwatch-readonly-builder/manifest.yaml  | 42 +++++++++++++++
 .../references/CAPABILITIES.md                | 38 +++++++++++++
 .../references/DEMO.md                        | 34 ++++++++++++
 .../references/INSTALL.md                     | 26 +++++++++
 .../references/OPENCLAW_MCP_CONFIG.json       | 10 ++++
 .../references/OPENHANDS_MCP_CONFIG.json      |  8 +++
 .../references/README.md                      | 19 +++++++
 .../references/TROUBLESHOOTING.md             | 34 ++++++++++++
 .../references/example-tasks.md               | 15 ++++--
 .../references/mcp-install.md                 | 26 +++++++--
 .../references/tool-map.md                    | 24 +++++++--
 26 files changed, 620 insertions(+), 85 deletions(-)
 create mode 100644 skills/cortexpilot-adoption-router/manifest.yaml
 create mode 100644 skills/cortexpilot-adoption-router/references/CAPABILITIES.md
 create mode 100644 skills/cortexpilot-adoption-router/references/DEMO.md
 create mode 100644 skills/cortexpilot-adoption-router/references/INSTALL.md
 create mode 100644 skills/cortexpilot-adoption-router/references/OPENCLAW_MCP_CONFIG.json
 create mode 100644 skills/cortexpilot-adoption-router/references/OPENHANDS_MCP_CONFIG.json
 create mode 100644 skills/cortexpilot-adoption-router/references/README.md
 create mode 100644 skills/cortexpilot-adoption-router/references/TROUBLESHOOTING.md
 create mode 100644 skills/dealwatch-readonly-builder/manifest.yaml
 create mode 100644 skills/dealwatch-readonly-builder/references/CAPABILITIES.md
 create mode 100644 skills/dealwatch-readonly-builder/references/DEMO.md
 create mode 100644 skills/dealwatch-readonly-builder/references/INSTALL.md
 create mode 100644 skills/dealwatch-readonly-builder/references/OPENCLAW_MCP_CONFIG.json
 create mode 100644 skills/dealwatch-readonly-builder/references/OPENHANDS_MCP_CONFIG.json
 create mode 100644 skills/dealwatch-readonly-builder/references/README.md
 create mode 100644 skills/dealwatch-readonly-builder/references/TROUBLESHOOTING.md

diff --git a/skills/cortexpilot-adoption-router/README.md b/skills/cortexpilot-adoption-router/README.md
index 7aa19bb7..05537ceb 100644
--- a/skills/cortexpilot-adoption-router/README.md
+++ b/skills/cortexpilot-adoption-router/README.md
@@ -1,25 +1,42 @@
 # CortexPilot Adoption Router
 
-Public OpenHands skill for connecting the published CortexPilot read-only MCP
-package and choosing the right public lane.
+This bundle teaches an agent how to connect the published CortexPilot read-only
+MCP package and choose the right public adoption lane.
 
-## What this skill teaches
+## What the agent learns here
 
 - how to install the published `cortexpilot-orchestrator==0.1.0a4` MCP package
-- which read-only CortexPilot tools are safe-first
+- which read-only CortexPilot tools exist and which are safe-first
 - how to choose between run/workflow inspection, queue/approval reads, and
   proof/incident reads
-- which claims stay out of bounds
+- which hosted or write-capable claims stay out of bounds
 
 ## Included files
 
-- `SKILL.md` — the agent-facing prompt
-- `references/mcp-install.md` — exact OpenHands install snippet
-- `references/tool-map.md` — the stable CortexPilot MCP tool map
-- `references/example-tasks.md` — concrete tasks this skill is meant to handle
+- `SKILL.md` — the progressive-disclosure prompt for the agent
+- `README.md` — the human-facing overview for reviewers and operators
+- `manifest.yaml` — listing metadata for host skill registries
+- `references/README.md` — the local index for every supporting file
+- `references/INSTALL.md` — exact install snippets for OpenHands/OpenClaw
+- `references/OPENHANDS_MCP_CONFIG.json` — a ready-to-edit `mcpServers` snippet
+- `references/OPENCLAW_MCP_CONFIG.json` — a ready-to-edit `mcp.servers` snippet
+- `references/CAPABILITIES.md` — the stable read-only tool inventory
+- `references/DEMO.md` — the first-success walkthrough and expected return shape
+- `references/TROUBLESHOOTING.md` — the first checks when launch or inspection fails
+
+## The shortest install path
+
+Use the published package, not a repo-local checkout:
+
+```bash
+uvx --from cortexpilot-orchestrator==0.1.0a4 cortexpilot-readonly-mcp
+```
+
+If the host needs a saved MCP config snippet, use the host-specific examples in
+`references/INSTALL.md`.
 
 ## Hard boundaries
 
 - no hosted operator service
 - no write-capable public MCP
-- no first-party marketplace claim unless the host independently confirms it
+- no first-party marketplace claim unless that host independently confirms it
diff --git a/skills/cortexpilot-adoption-router/SKILL.md b/skills/cortexpilot-adoption-router/SKILL.md
index b38ad6a7..072909ce 100644
--- a/skills/cortexpilot-adoption-router/SKILL.md
+++ b/skills/cortexpilot-adoption-router/SKILL.md
@@ -13,43 +13,48 @@ triggers:
 
 Use this skill when the user needs the shortest truthful path into CortexPilot.
 
-## What this skill helps the agent do
+## What this skill teaches
 
-- install the published CortexPilot MCP package
-- choose the right read-only tool for the current job
-- start with one public lane instead of mixing every CortexPilot surface together
-- keep the answer inside the current read-only public boundary
+- how to install the published CortexPilot MCP package
+- how to choose the right read-only tool for the current job
+- how to start with one public lane instead of mixing every surface together
+- how to keep the answer inside the current read-only public boundary
 
 ## When to use this skill
 
 Use this skill when the user asks to:
 
-- connect CortexPilot to OpenHands
+- connect CortexPilot to OpenHands or OpenClaw
 - inspect runs or workflows through the public read-only MCP
-- understand which public lane should come first
+- understand which public CortexPilot lane to choose first
 - inspect approvals, queue state, proof, compare, or incident summaries without
   mutating anything
 
 ## If the MCP is not connected yet
 
-Open `references/mcp-install.md` and use the published-package config snippet.
-Do not assume the user has a local checkout of the source repo.
+Open `README.md` in this folder and follow `references/INSTALL.md`.
+Do not invent repo-local startup paths when the published package already
+exists.
 
 ## Safe-first workflow
 
 1. `list_runs` or `list_workflows`
+   Use these first when the user needs the top-level ledger.
 2. `get_run` or `get_workflow`
+   Use these after the user already has the specific run or workflow to inspect.
 3. `list_queue`, `get_pending_approvals`, or `get_diff_gate_state`
+   Use these for queue, approval, or diff-gate posture.
 4. `get_run_reports`, `get_compare_summary`, `get_proof_summary`, or
    `get_incident_summary`
+   Use these after the user is already inside one run and needs a specific
+   proof-oriented read model.
 
 ## Tool-selection rule
 
-- choose run/workflow reads for “what is happening now?”
-- choose queue/approval reads for “what is blocked or pending?”
-- choose proof/compare/incident reads only after the user already has one run to
-  inspect
-- do not mix multiple lanes unless the user explicitly asks for a broader audit
+- Choose run/workflow reads for “what is happening now?”
+- Choose queue/approval reads for “what is blocked or pending?”
+- Choose compare/proof/incident reads for “what evidence exists for this run?”
+- Do not mix multiple lanes unless the user explicitly asks for a broader audit
 
 ## What to return
 
@@ -62,14 +67,16 @@ Return a short answer with:
 
 ## Guardrails
 
-- no hosted operator service
-- no write-capable public MCP
-- no first-party marketplace claim unless the host independently confirms it
-- keep `task_contract` as the execution authority for real runs; this MCP is
-  read-only inspection only
+- Do not describe CortexPilot as a hosted operator product.
+- Do not describe the public MCP surface as write-capable.
+- Do not claim a first-party marketplace listing unless that host independently
+  confirms it.
+- Keep `task_contract` as the execution authority for real runs; this MCP is
+  read-only inspection only.
 
 ## Read next
 
-- `references/mcp-install.md`
-- `references/tool-map.md`
-- `references/example-tasks.md`
+- `references/INSTALL.md`
+- `references/CAPABILITIES.md`
+- `references/DEMO.md`
+- `references/TROUBLESHOOTING.md`
diff --git a/skills/cortexpilot-adoption-router/manifest.yaml b/skills/cortexpilot-adoption-router/manifest.yaml
new file mode 100644
index 00000000..cb13f7f0
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/manifest.yaml
@@ -0,0 +1,42 @@
+schema_version: 1
+artifact: public-skill-listing-manifest
+
+skill:
+  name: cortexpilot-adoption-router
+  display_name: CortexPilot Adoption Router
+  version: 1.1.0
+  entrypoint: SKILL.md
+  package_shape: skill-folder
+
+registry_targets:
+  clawhub:
+    status: listed-live
+    package_shape: skill-folder
+    listing_url: https://www.clawhub.ai/skills/cortexpilot-adoption-router
+    submit_via: clawhub publish . --slug cortexpilot-adoption-router --name "CortexPilot Adoption Router" --version 1.1.0 --tags mcp,workflow,proof,read-only,cortexpilot
+  openhands-extensions:
+    status: review-pending
+    package_shape: skill-folder
+    submission_url: https://github.com/OpenHands/extensions/pull/151
+    submit_via: submit this folder as skills/cortexpilot-adoption-router/ in OpenHands/extensions
+
+boundaries:
+  product_identity: Proof-first CortexPilot adoption routing through the published read-only MCP surface.
+  canonical_repo_version: 0.1.0a4
+  official_listing_state: clawhub-live-other-hosts-pending
+  not_claimed:
+    - No hosted operator service is claimed
+    - No write-capable public MCP surface is claimed
+    - No first-party marketplace listing is claimed unless independently confirmed
+    - No live OpenHands/extensions listing is claimed until the PR lands
+
+pair_with:
+  - SKILL.md
+  - README.md
+  - references/README.md
+  - references/INSTALL.md
+  - references/OPENHANDS_MCP_CONFIG.json
+  - references/OPENCLAW_MCP_CONFIG.json
+  - references/CAPABILITIES.md
+  - references/DEMO.md
+  - references/TROUBLESHOOTING.md
diff --git a/skills/cortexpilot-adoption-router/references/CAPABILITIES.md b/skills/cortexpilot-adoption-router/references/CAPABILITIES.md
new file mode 100644
index 00000000..58a9eeab
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/CAPABILITIES.md
@@ -0,0 +1,33 @@
+# CortexPilot MCP Capabilities
+
+These are the stable read-only tools exposed by the published CortexPilot MCP.
+
+## Safe-first tools
+
+1. `list_runs`
+   - use first when the user needs the current run ledger
+2. `get_run`
+   - use when the user already has one run identifier and needs the run snapshot
+3. `list_workflows`
+   - use when the user needs the current workflow ledger
+4. `get_workflow`
+   - use when the user already has one workflow identifier
+
+## Queue and approval tools
+
+- `list_queue`
+- `get_pending_approvals`
+- `get_diff_gate_state`
+
+Use these when the user is inspecting queue state, pending approvals, or diff
+gate posture.
+
+## Proof and incident tools
+
+- `get_run_reports`
+- `get_compare_summary`
+- `get_proof_summary`
+- `get_incident_summary`
+
+Use these after the user is already inside a specific run and wants the proof,
+compare, or incident read model.
diff --git a/skills/cortexpilot-adoption-router/references/DEMO.md b/skills/cortexpilot-adoption-router/references/DEMO.md
new file mode 100644
index 00000000..beb094fe
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/DEMO.md
@@ -0,0 +1,24 @@
+# OpenHands / OpenClaw Demo Walkthrough
+
+This is the shortest concrete demo you can run to prove the skill is doing real
+inspection work instead of only describing one.
+
+## Demo prompt
+
+Connect CortexPilot and inspect the current public run ledger. Start with
+`list_runs` or `list_workflows`, then inspect one specific run or workflow.
+If the user is really asking what is blocked, pivot into `list_queue` or
+`get_pending_approvals` and explain the safest next lane.
+
+## Expected tool sequence
+
+1. `list_runs` or `list_workflows`
+2. `get_run` or `get_workflow`
+3. optionally `list_queue` or `get_pending_approvals`
+
+## Visible success criteria
+
+- the agent names one real run or workflow instead of speaking in the abstract
+- the answer stays on the read-only lane
+- the agent points the user at the next inspection step instead of inventing a
+  write workflow
diff --git a/skills/cortexpilot-adoption-router/references/INSTALL.md b/skills/cortexpilot-adoption-router/references/INSTALL.md
new file mode 100644
index 00000000..328d2ff2
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/INSTALL.md
@@ -0,0 +1,22 @@
+# Install The Published CortexPilot MCP
+
+Use the published PyPI package, not a repo-local checkout.
+
+## Published package
+
+- package: `cortexpilot-orchestrator==0.1.0a4`
+- executable: `cortexpilot-readonly-mcp`
+- transport: `stdio`
+
+## OpenHands example
+
+Use `OPENHANDS_MCP_CONFIG.json` as the starting point for your host config.
+
+## OpenClaw example
+
+Use `OPENCLAW_MCP_CONFIG.json` as the starting point for your host config.
+
+## Smoke check
+
+Use a minimal MCP handshake and `tools/list` request after the host attaches the
+server.
diff --git a/skills/cortexpilot-adoption-router/references/OPENCLAW_MCP_CONFIG.json b/skills/cortexpilot-adoption-router/references/OPENCLAW_MCP_CONFIG.json
new file mode 100644
index 00000000..d287b044
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/OPENCLAW_MCP_CONFIG.json
@@ -0,0 +1,10 @@
+{
+  "mcp": {
+    "servers": {
+      "cortexpilot-readonly": {
+        "command": "uvx",
+        "args": ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"]
+      }
+    }
+  }
+}
diff --git a/skills/cortexpilot-adoption-router/references/OPENHANDS_MCP_CONFIG.json b/skills/cortexpilot-adoption-router/references/OPENHANDS_MCP_CONFIG.json
new file mode 100644
index 00000000..ea2a1827
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/OPENHANDS_MCP_CONFIG.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "cortexpilot-readonly": {
+      "command": "uvx",
+      "args": ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"]
+    }
+  }
+}
diff --git a/skills/cortexpilot-adoption-router/references/README.md b/skills/cortexpilot-adoption-router/references/README.md
new file mode 100644
index 00000000..fb4ddc77
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/README.md
@@ -0,0 +1,19 @@
+# CortexPilot Skill References
+
+This directory keeps the practical material that a reviewer or agent needs
+without depending on repo-root docs.
+
+## Included references
+
+- `INSTALL.md`
+  - install the published MCP package and wire it into a host
+- `OPENHANDS_MCP_CONFIG.json`
+  - a ready-to-edit `mcpServers` snippet
+- `OPENCLAW_MCP_CONFIG.json`
+  - a ready-to-edit `mcp.servers` snippet
+- `CAPABILITIES.md`
+  - the stable read-only tool surface and recommended safe-first order
+- `DEMO.md`
+  - the first-success walkthrough and expected return shape
+- `TROUBLESHOOTING.md`
+  - the first places to check when attach or inspection fails
diff --git a/skills/cortexpilot-adoption-router/references/TROUBLESHOOTING.md b/skills/cortexpilot-adoption-router/references/TROUBLESHOOTING.md
new file mode 100644
index 00000000..83e476d2
--- /dev/null
+++ b/skills/cortexpilot-adoption-router/references/TROUBLESHOOTING.md
@@ -0,0 +1,35 @@
+# CortexPilot Troubleshooting
+
+Use this page when the packet looks correct but the first attach or read-only
+inspection still fails.
+
+## 1. The MCP server does not launch
+
+Check these first:
+
+- `uvx` is available on the machine
+- the package version from `INSTALL.md` still resolves
+- the host config matches the command and args in the JSON snippets
+
+If launch still fails, report it as a package or host-config problem instead of
+claiming the packet is attach-ready.
+
+## 2. The top-level list tools return nothing useful
+
+Confirm:
+
+- you started with `list_runs` or `list_workflows`
+- the public read-only MCP actually has access to the expected environment
+- the user is not asking for a hosted or write-capable surface this packet does
+  not expose
+
+## 3. The user wants to mutate state
+
+Stop and explain the boundary. This packet only covers the published read-only
+inspection lane.
+
+## 4. Boundary reminder
+
+This packet is for the public, read-only CortexPilot MCP surface. It does not
+claim a hosted operator service, a write-capable public MCP, or a live
+OpenHands/extensions listing until the PR lands.
diff --git a/skills/cortexpilot-adoption-router/references/example-tasks.md b/skills/cortexpilot-adoption-router/references/example-tasks.md
index c3144ea9..ce4efb82 100644
--- a/skills/cortexpilot-adoption-router/references/example-tasks.md
+++ b/skills/cortexpilot-adoption-router/references/example-tasks.md
@@ -1,6 +1,15 @@
 # Example Tasks
 
+Use this bundle for tasks like:
+
 - “Connect CortexPilot to OpenHands and inspect the run ledger.”
-- “Show me which CortexPilot MCP tool I should call first.”
-- “Inspect pending approvals or queue state without mutating anything.”
-- “Open proof or incident summaries for one run.”
+- “Which CortexPilot MCP tool should I call first for workflow truth?”
+- “Show me the safest read-only lane for approvals or queue state.”
+- “Inspect proof or incident summaries without mutating anything.”
+
+Return shapes should stay short and operational:
+
+1. chosen lane
+2. next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet
diff --git a/skills/cortexpilot-adoption-router/references/mcp-install.md b/skills/cortexpilot-adoption-router/references/mcp-install.md
index 4faf6480..589823e1 100644
--- a/skills/cortexpilot-adoption-router/references/mcp-install.md
+++ b/skills/cortexpilot-adoption-router/references/mcp-install.md
@@ -8,9 +8,9 @@ Use the published PyPI package, not a repo-local checkout.
 - executable: `cortexpilot-readonly-mcp`
 - transport: `stdio`
 
-## OpenHands config example
+## OpenHands example
 
-Add this to `~/.openhands/config.toml`:
+Add the server to `~/.openhands/config.toml`:
 
 ```toml
 [mcp]
@@ -19,7 +19,24 @@ stdio_servers = [
 ]
 ```
 
+## OpenClaw example
+
+Add the server to your saved MCP server config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "cortexpilot-readonly": {
+        "command": "uvx",
+        "args": ["--from", "cortexpilot-orchestrator==0.1.0a4", "cortexpilot-readonly-mcp"]
+      }
+    }
+  }
+}
+```
+
 ## Smoke check
 
-After the host attaches the server, request `tools/list` and confirm the
-read-only run/workflow tools are present.
+Use a minimal MCP handshake and `tools/list` request after the host attaches the
+server.
diff --git a/skills/cortexpilot-adoption-router/references/tool-map.md b/skills/cortexpilot-adoption-router/references/tool-map.md
index 08a793e5..83201a23 100644
--- a/skills/cortexpilot-adoption-router/references/tool-map.md
+++ b/skills/cortexpilot-adoption-router/references/tool-map.md
@@ -1,13 +1,17 @@
 # CortexPilot MCP Tool Map
 
+These are the stable read-only tools exposed by the published CortexPilot MCP.
+
 ## Safe-first tools
 
 1. `list_runs`
+   Use first when the user needs the current run ledger.
 2. `get_run`
+   Use when the user already has one run identifier and needs the run snapshot.
 3. `list_workflows`
+   Use when the user needs the current Workflow Case ledger.
 4. `get_workflow`
-
-Use these first when the job is “inspect current truth”.
+   Use when the user already has one workflow identifier.
 
 ## Queue and approval tools
 
@@ -15,7 +19,8 @@ Use these first when the job is “inspect current truth”.
 - `get_pending_approvals`
 - `get_diff_gate_state`
 
-Use these when the job is “inspect blocked or pending work”.
+Use these when the user is inspecting queue state, pending approvals, or diff
+gate posture.
 
 ## Proof and incident tools
 
@@ -24,4 +29,5 @@ Use these when the job is “inspect blocked or pending work”.
 - `get_proof_summary`
 - `get_incident_summary`
 
-Use these after the user already has a specific run in hand.
+Use these after the user is already inside a specific run and wants the proof,
+compare, or incident read model.
diff --git a/skills/dealwatch-readonly-builder/README.md b/skills/dealwatch-readonly-builder/README.md
index adfb6c6c..5c7f66e5 100644
--- a/skills/dealwatch-readonly-builder/README.md
+++ b/skills/dealwatch-readonly-builder/README.md
@@ -1,25 +1,43 @@
 # DealWatch Read-only Builder
 
-Public OpenHands skill for connecting the published DealWatch MCP package and
-using its read-only tools safely.
+This bundle teaches an agent how to connect the published DealWatch MCP package
+and use its read-only tools safely.
 
-## What this skill teaches
+## What the agent learns here
 
 - how to install the published `dealwatch==1.0.1` MCP package
-- which DealWatch MCP tools are safe-first
-- how to move from runtime readiness into compare preview and then into deeper
-  detail reads
+- which DealWatch MCP tools exist and which three are safe-first
+- how to choose between runtime-readiness, builder-starter, compare, watch, and
+  recovery reads
 - which claims stay out of bounds
 
 ## Included files
 
-- `SKILL.md` — the agent-facing prompt
-- `references/mcp-install.md` — exact OpenHands install snippet
-- `references/tool-map.md` — the stable DealWatch MCP tool map
-- `references/example-tasks.md` — concrete tasks this skill is meant to handle
+- `SKILL.md` — the progressive-disclosure prompt for the agent
+- `README.md` — the human-facing overview for reviewers and operators
+- `manifest.yaml` — listing metadata for host skill registries
+- `references/README.md` — the local index for every supporting file
+- `references/INSTALL.md` — exact install snippets for OpenHands/OpenClaw
+- `references/OPENHANDS_MCP_CONFIG.json` — a ready-to-edit `mcpServers` snippet
+- `references/OPENCLAW_MCP_CONFIG.json` — a ready-to-edit `mcp.servers` snippet
+- `references/CAPABILITIES.md` — read-only tool inventory and first-use order
+- `references/DEMO.md` — the first-success walkthrough and expected output shape
+- `references/TROUBLESHOOTING.md` — the first checks when attach or compare fails
+
+## The shortest install path
+
+Use the published package, not a repo-local checkout:
+
+```bash
+uvx --from dealwatch==1.0.1 dealwatch-mcp serve
+```
+
+If the host needs a saved MCP config snippet, use the host-specific examples in
+`references/INSTALL.md`.
 
 ## Hard boundaries
 
 - no hosted DealWatch control plane
 - no write-side MCP surface
-- no first-party marketplace claim unless the host independently confirms it
+- no autonomous recommendation claim
+- no first-party marketplace claim unless that host independently confirms it
diff --git a/skills/dealwatch-readonly-builder/SKILL.md b/skills/dealwatch-readonly-builder/SKILL.md
index 1e1160fd..28cc8937 100644
--- a/skills/dealwatch-readonly-builder/SKILL.md
+++ b/skills/dealwatch-readonly-builder/SKILL.md
@@ -13,42 +13,53 @@ triggers:
 
 Use this skill when the user wants the shortest truthful path into DealWatch.
 
-## What this skill helps the agent do
+## What this skill teaches
 
-- install the published DealWatch MCP package
-- choose the right read-only tool for the current job
-- start with runtime readiness and compare preview before deeper reads
-- keep the answer inside the current local-first boundary
+- how to install the published DealWatch MCP package
+- how to choose the right read-only tool for the current job
+- how to start with runtime readiness and compare preview before deeper reads
+- how to keep the answer inside the current local-first boundary
 
 ## When to use this skill
 
 Use this skill when the user asks to:
 
-- connect DealWatch to OpenHands
+- connect DealWatch to OpenHands or OpenClaw
 - check whether DealWatch is ready for a local read-only session
 - compare grocery product URLs before creating durable state
 - inspect watch tasks, watch groups, or recovery state without mutating anything
 
 ## If the MCP is not connected yet
 
-Open `references/mcp-install.md` and use the published-package config snippet.
-Do not assume a repo-local checkout is available.
+Open `README.md` in this folder and follow `references/INSTALL.md`.
+Do not invent repo-local launch commands when the published package already
+exists.
 
 ## Safe-first workflow
 
 1. `get_runtime_readiness`
+   Use this first when setup, environment, or startup truth is unclear.
 2. `compare_preview`
+   Use this first when the user wants to compare candidate grocery URLs without
+   creating tasks.
 3. `get_builder_starter_pack`
+   Use this when the user needs the integration contract or host setup path.
 4. `list_watch_tasks` or `list_watch_groups`
-5. one detail read
-6. recovery or notification reads only if the user is already in that lane
+   Use these after the first-safe path is already clear.
+5. `get_watch_task_detail` or `get_watch_group_detail`
+   Use these for one deeper read-only follow-up.
+6. `get_recovery_inbox`, `get_notification_settings`, or
+   `get_store_onboarding_cockpit`
+   Use these only after the user is already inside a recovery or operator
+   diagnostic workflow.
 
 ## Tool-selection rule
 
-- choose `compare_preview` for “Which URL is the right target?”
-- choose `get_runtime_readiness` for “Is the local runtime healthy?”
-- choose `get_builder_starter_pack` for “How do I connect the agent?”
-- choose watch-task/group reads only after the user already has durable state
+- Choose `compare_preview` for “Which URL is the right target?”
+- Choose `get_runtime_readiness` for “Is the local runtime healthy?”
+- Choose `get_builder_starter_pack` for “How do I connect an agent or host?”
+- Choose watch-task/group reads only after the user already has durable state to
+  inspect
 
 ## What to return
 
@@ -61,13 +72,14 @@ Return a short answer with:
 
 ## Guardrails
 
-- no write-side MCP
-- no hosted control plane
-- no first-party marketplace claim unless the host independently confirms it
-- no autonomous recommendation support
+- write-side MCP
+- hosted control plane
+- official marketplace or registry listing
+- autonomous recommendation support
 
 ## Read next
 
-- `references/mcp-install.md`
-- `references/tool-map.md`
-- `references/example-tasks.md`
+- `references/INSTALL.md`
+- `references/CAPABILITIES.md`
+- `references/DEMO.md`
+- `references/TROUBLESHOOTING.md`
diff --git a/skills/dealwatch-readonly-builder/manifest.yaml b/skills/dealwatch-readonly-builder/manifest.yaml
new file mode 100644
index 00000000..eb7549c8
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/manifest.yaml
@@ -0,0 +1,42 @@
+schema_version: 1
+artifact: public-skill-listing-manifest
+
+skill:
+  name: dealwatch-readonly-builder
+  display_name: DealWatch Read-only Builder
+  version: 1.1.0
+  entrypoint: SKILL.md
+  package_shape: skill-folder
+
+registry_targets:
+  clawhub:
+    status: listed-live
+    package_shape: skill-folder
+    listing_url: https://www.clawhub.ai/skills/dealwatch-readonly-builder
+    submit_via: clawhub publish . --slug dealwatch-readonly-builder --name "DealWatch Read-only Builder" --version 1.1.0 --tags groceries,compare-first,mcp,read-only,dealwatch
+  openhands-extensions:
+    status: review-pending
+    package_shape: skill-folder
+    submission_url: https://github.com/OpenHands/extensions/pull/151
+    submit_via: submit this folder as skills/dealwatch-readonly-builder/ in OpenHands/extensions
+
+boundaries:
+  product_identity: Local-first grocery comparison and watch-state inspection through the DealWatch read-only MCP.
+  canonical_repo_version: 1.0.1
+  official_listing_state: clawhub-live-other-hosts-pending
+  not_claimed:
+    - No hosted DealWatch control plane is claimed
+    - No write-capable MCP surface is claimed
+    - No autonomous recommendation support is claimed
+    - No first-party marketplace listing is claimed unless independently confirmed
+
+pair_with:
+  - SKILL.md
+  - README.md
+  - references/README.md
+  - references/INSTALL.md
+  - references/OPENHANDS_MCP_CONFIG.json
+  - references/OPENCLAW_MCP_CONFIG.json
+  - references/CAPABILITIES.md
+  - references/DEMO.md
+  - references/TROUBLESHOOTING.md
diff --git a/skills/dealwatch-readonly-builder/references/CAPABILITIES.md b/skills/dealwatch-readonly-builder/references/CAPABILITIES.md
new file mode 100644
index 00000000..263b04ac
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/CAPABILITIES.md
@@ -0,0 +1,38 @@
+# DealWatch MCP Capabilities
+
+These are the stable read-only tools exposed by the published DealWatch MCP.
+
+## Safe-first tools
+
+1. `get_runtime_readiness`
+   - use first when setup, environment, or startup truth is unclear
+2. `compare_preview`
+   - use first when the user wants to compare candidate grocery URLs without
+     creating durable state
+3. `get_builder_starter_pack`
+   - use when the user needs the integration contract, launch commands, and
+     host setup path
+
+## Watch-task tools
+
+- `list_watch_tasks`
+- `get_watch_task_detail`
+
+Use these after the safe-first path is already clear.
+
+## Watch-group tools
+
+- `list_watch_groups`
+- `get_watch_group_detail`
+
+Use these after the user is already inside an existing watch-group flow.
+
+## Recovery and runtime follow-up
+
+- `get_recovery_inbox`
+- `list_notifications`
+- `get_notification_settings`
+- `list_store_bindings`
+- `get_store_onboarding_cockpit`
+
+Use these only after the safe-first path is grounded in a real runtime state.
diff --git a/skills/dealwatch-readonly-builder/references/DEMO.md b/skills/dealwatch-readonly-builder/references/DEMO.md
new file mode 100644
index 00000000..5387b07d
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/DEMO.md
@@ -0,0 +1,34 @@
+# OpenHands / OpenClaw Demo Walkthrough
+
+This is the shortest concrete demo you can run to prove the skill is doing real
+work instead of only describing one.
+
+## Demo prompt
+
+Connect DealWatch, confirm whether the runtime is ready, and compare two
+candidate grocery URLs without creating any durable state.
+
+Start with `get_runtime_readiness`. If the runtime is healthy, run
+`compare_preview` on the submitted product URLs. Then explain which lane the
+user should choose next and why.
+
+## Expected tool sequence
+
+1. `get_runtime_readiness`
+2. `compare_preview`
+3. optionally `get_builder_starter_pack`
+
+## Visible success criteria
+
+- the agent reports whether the local runtime is ready
+- the compare step returns a real preview instead of creating durable state
+- the agent names the safest next lane instead of widening into write flows
+
+## What the output should look like
+
+Return a compact answer with:
+
+1. the chosen lane
+2. the next 1-3 actions
+3. one boundary reminder
+4. one exact MCP tool or install snippet
diff --git a/skills/dealwatch-readonly-builder/references/INSTALL.md b/skills/dealwatch-readonly-builder/references/INSTALL.md
new file mode 100644
index 00000000..fc1b4a6c
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/INSTALL.md
@@ -0,0 +1,26 @@
+# Install The Published DealWatch MCP
+
+Use the published PyPI package, not a repo-local `PYTHONPATH=src` shortcut.
+
+## Published package
+
+- package: `dealwatch==1.0.1`
+- executable: `dealwatch-mcp`
+- transport: `stdio`
+
+## OpenHands example
+
+Use `OPENHANDS_MCP_CONFIG.json` as the starting point for your host config.
+
+## OpenClaw example
+
+Use `OPENCLAW_MCP_CONFIG.json` as the starting point for your host config.
+
+## Smoke check
+
+```bash
+uvx --from dealwatch==1.0.1 dealwatch-mcp list-tools --json
+```
+
+If that command returns the tool inventory, the published MCP package is wired
+correctly.
diff --git a/skills/dealwatch-readonly-builder/references/OPENCLAW_MCP_CONFIG.json b/skills/dealwatch-readonly-builder/references/OPENCLAW_MCP_CONFIG.json
new file mode 100644
index 00000000..223e4807
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/OPENCLAW_MCP_CONFIG.json
@@ -0,0 +1,10 @@
+{
+  "mcp": {
+    "servers": {
+      "dealwatch": {
+        "command": "uvx",
+        "args": ["--from", "dealwatch==1.0.1", "dealwatch-mcp", "serve"]
+      }
+    }
+  }
+}
diff --git a/skills/dealwatch-readonly-builder/references/OPENHANDS_MCP_CONFIG.json b/skills/dealwatch-readonly-builder/references/OPENHANDS_MCP_CONFIG.json
new file mode 100644
index 00000000..691e6705
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/OPENHANDS_MCP_CONFIG.json
@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "dealwatch": {
+      "command": "uvx",
+      "args": ["--from", "dealwatch==1.0.1", "dealwatch-mcp", "serve"]
+    }
+  }
+}
diff --git a/skills/dealwatch-readonly-builder/references/README.md b/skills/dealwatch-readonly-builder/references/README.md
new file mode 100644
index 00000000..a58c0333
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/README.md
@@ -0,0 +1,19 @@
+# DealWatch Skill References
+
+This directory keeps the practical material that a reviewer or agent needs
+without depending on repo-root docs.
+
+## Included references
+
+- `INSTALL.md`
+  - install the published MCP package and wire it into a host
+- `OPENHANDS_MCP_CONFIG.json`
+  - a ready-to-edit `mcpServers` snippet
+- `OPENCLAW_MCP_CONFIG.json`
+  - a ready-to-edit `mcp.servers` snippet
+- `CAPABILITIES.md`
+  - the stable read-only tool surface and recommended safe-first order
+- `DEMO.md`
+  - the first-success walkthrough and expected output shape
+- `TROUBLESHOOTING.md`
+  - the first places to check when launch or compare fails
diff --git a/skills/dealwatch-readonly-builder/references/TROUBLESHOOTING.md b/skills/dealwatch-readonly-builder/references/TROUBLESHOOTING.md
new file mode 100644
index 00000000..027a1d9b
--- /dev/null
+++ b/skills/dealwatch-readonly-builder/references/TROUBLESHOOTING.md
@@ -0,0 +1,34 @@
+# DealWatch Troubleshooting
+
+Use this page when the packet looks right on paper but the first real attach or
+compare attempt still fails.
+
+## 1. The MCP server does not launch
+
+Check these first:
+
+- `uvx` is available on the machine
+- the package version in `INSTALL.md` still resolves
+- the host config matches the command and args in the JSON snippets
+
+If launch still fails, report it as a package or host-config problem instead of
+claiming the skill is attach-ready.
+
+## 2. `get_runtime_readiness` fails
+
+That usually means the local DealWatch runtime is not healthy yet. Stop there
+and report the runtime problem before trying `compare_preview`.
+
+## 3. `compare_preview` fails
+
+Re-check:
+
+- the submitted URLs are valid and reachable
+- the runtime readiness step already passed
+- the user really wants a read-only compare, not a durable task or watch write
+
+## 4. Boundary reminder
+
+This packet is for the local-first, read-only DealWatch MCP surface. It does
+not claim a hosted control plane, a write-capable MCP lane, or autonomous
+recommendation support.
diff --git a/skills/dealwatch-readonly-builder/references/example-tasks.md b/skills/dealwatch-readonly-builder/references/example-tasks.md
index e70dcd66..c0cace02 100644
--- a/skills/dealwatch-readonly-builder/references/example-tasks.md
+++ b/skills/dealwatch-readonly-builder/references/example-tasks.md
@@ -1,6 +1,15 @@
 # Example Tasks
 
+Use this skill bundle for tasks like:
+
 - “Connect DealWatch to OpenHands and check whether the runtime is ready.”
-- “Compare these grocery URLs before creating any watch task.”
-- “Show me which read-only DealWatch tool I should call first.”
-- “Inspect one watch group without mutating any state.”
+- “Compare these grocery product URLs before creating any watch task.”
+- “Show me which DealWatch read-only tool I should call first.”
+- “Inspect one watch task or watch group without mutating state.”
+
+Return shapes should stay short and operational:
+
+1. chosen lane
+2. next 1-3 actions
+3. one boundary reminder
+4. one MCP tool or one install snippet
diff --git a/skills/dealwatch-readonly-builder/references/mcp-install.md b/skills/dealwatch-readonly-builder/references/mcp-install.md
index 327078a6..0736131e 100644
--- a/skills/dealwatch-readonly-builder/references/mcp-install.md
+++ b/skills/dealwatch-readonly-builder/references/mcp-install.md
@@ -1,6 +1,6 @@
 # Install The Published DealWatch MCP
 
-Use the published PyPI package, not a repo-local checkout.
+Use the published PyPI package, not a repo-local `PYTHONPATH=src` shortcut.
 
 ## Published package
 
@@ -8,9 +8,9 @@ Use the published PyPI package, not a repo-local checkout.
 - executable: `dealwatch-mcp`
 - transport: `stdio`
 
-## OpenHands config example
+## OpenHands example
 
-Add this to `~/.openhands/config.toml`:
+Add the server to `~/.openhands/config.toml`:
 
 ```toml
 [mcp]
@@ -19,8 +19,28 @@ stdio_servers = [
 ]
 ```
 
+## OpenClaw example
+
+Add the server to your saved MCP server config:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "dealwatch": {
+        "command": "uvx",
+        "args": ["--from", "dealwatch==1.0.1", "dealwatch-mcp", "serve"]
+      }
+    }
+  }
+}
+```
+
 ## Smoke check
 
 ```bash
 uvx --from dealwatch==1.0.1 dealwatch-mcp list-tools --json
 ```
+
+If that command returns the tool inventory, the published MCP package is wired
+correctly.
diff --git a/skills/dealwatch-readonly-builder/references/tool-map.md b/skills/dealwatch-readonly-builder/references/tool-map.md
index 0e6cda7b..61aa998f 100644
--- a/skills/dealwatch-readonly-builder/references/tool-map.md
+++ b/skills/dealwatch-readonly-builder/references/tool-map.md
@@ -1,23 +1,39 @@
 # DealWatch MCP Tool Map
 
+These are the stable read-only tools exposed by the published DealWatch MCP.
+
 ## Safe-first tools
 
 1. `get_runtime_readiness`
+   Use first when the user needs to know whether the local runtime is ready.
 2. `compare_preview`
+   Use first when the user wants to compare submitted product URLs without
+   creating durable state.
 3. `get_builder_starter_pack`
+   Use when the user needs the integration contract, launch commands, and host
+   config guidance.
 
-Use those three before any deeper watch or recovery reads.
-
-## Detail reads
+## Watch-task tools
 
 - `list_watch_tasks`
 - `get_watch_task_detail`
+
+Use these after the user is already inside an existing watch-task flow.
+
+## Watch-group tools
+
 - `list_watch_groups`
 - `get_watch_group_detail`
+
+Use these after the user is already inside an existing watch-group flow.
+
+## Recovery and runtime follow-up
+
 - `get_recovery_inbox`
 - `list_notifications`
 - `get_notification_settings`
 - `list_store_bindings`
 - `get_store_onboarding_cockpit`
 
-Use detail reads only after the safe-first path is already clear.
+Use these only after the safe-first path is clear and the user needs a deeper
+read-only diagnostic.

From e8db42b78c9e25a163db98d2a91dd5f455b3f21e Mon Sep 17 00:00:00 2001
From: "Yifeng[Terry] Yu" <125581657+xiaojiou176@users.noreply.github.com>
Date: Wed, 8 Apr 2026 19:18:39 -0700
Subject: [PATCH 4/4] docs: sync public skill versions with clawhub

---
 skills/cortexpilot-adoption-router/manifest.yaml | 4 ++--
 skills/dealwatch-readonly-builder/manifest.yaml  | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/skills/cortexpilot-adoption-router/manifest.yaml b/skills/cortexpilot-adoption-router/manifest.yaml
index cb13f7f0..8df48135 100644
--- a/skills/cortexpilot-adoption-router/manifest.yaml
+++ b/skills/cortexpilot-adoption-router/manifest.yaml
@@ -4,7 +4,7 @@ artifact: public-skill-listing-manifest
 skill:
   name: cortexpilot-adoption-router
   display_name: CortexPilot Adoption Router
-  version: 1.1.0
+  version: 1.1.1
   entrypoint: SKILL.md
   package_shape: skill-folder
 
@@ -13,7 +13,7 @@ registry_targets:
     status: listed-live
     package_shape: skill-folder
     listing_url: https://www.clawhub.ai/skills/cortexpilot-adoption-router
-    submit_via: clawhub publish . --slug cortexpilot-adoption-router --name "CortexPilot Adoption Router" --version 1.1.0 --tags mcp,workflow,proof,read-only,cortexpilot
+    submit_via: clawhub publish . --slug cortexpilot-adoption-router --name "CortexPilot Adoption Router" --version 1.1.1 --tags mcp,workflow,proof,read-only,cortexpilot
   openhands-extensions:
     status: review-pending
     package_shape: skill-folder
diff --git a/skills/dealwatch-readonly-builder/manifest.yaml b/skills/dealwatch-readonly-builder/manifest.yaml
index eb7549c8..e5206da8 100644
--- a/skills/dealwatch-readonly-builder/manifest.yaml
+++ b/skills/dealwatch-readonly-builder/manifest.yaml
@@ -4,7 +4,7 @@ artifact: public-skill-listing-manifest
 skill:
   name: dealwatch-readonly-builder
   display_name: DealWatch Read-only Builder
-  version: 1.1.0
+  version: 1.1.1
   entrypoint: SKILL.md
   package_shape: skill-folder
 
@@ -13,7 +13,7 @@ registry_targets:
     status: listed-live
     package_shape: skill-folder
     listing_url: https://www.clawhub.ai/skills/dealwatch-readonly-builder
-    submit_via: clawhub publish . --slug dealwatch-readonly-builder --name "DealWatch Read-only Builder" --version 1.1.0 --tags groceries,compare-first,mcp,read-only,dealwatch
+    submit_via: clawhub publish . --slug dealwatch-readonly-builder --name "DealWatch Read-only Builder" --version 1.1.1 --tags groceries,compare-first,mcp,read-only,dealwatch
   openhands-extensions:
     status: review-pending
     package_shape: skill-folder