diff --git a/marketplaces/default.json b/marketplaces/default.json index 5ee1dd6a..8dfa0dab 100644 --- a/marketplaces/default.json +++ b/marketplaces/default.json @@ -472,6 +472,19 @@ "sample" ] }, + { + "name": "campus-copilot-current-view-triage", + "source": "./campus-copilot-current-view-triage", + "description": "Turn a Campus Copilot snapshot or current-view export into one plain-language what-to-do-first answer for a student.", + "category": "productivity", + "keywords": [ + "campus-copilot", + "student", + "triage", + "snapshot", + "read-only" + ] + }, { "name": "magic-test", "source": "./plugins/magic-test", @@ -497,6 +510,19 @@ "openhands", "slash-command" ] + }, + { + "name": "sourceharbor-watchlist-briefing", + "source": "./sourceharbor-watchlist-briefing", + "description": "Use SourceHarbor watchlists and briefing payloads to answer one operator question with evidence and a concrete next action.", + "category": "productivity", + "keywords": [ + "sourceharbor", + "watchlist", + "briefing", + "mcp", + "operator" + ] } ] } diff --git a/skills/campus-copilot-current-view-triage/README.md b/skills/campus-copilot-current-view-triage/README.md new file mode 100644 index 00000000..aa822547 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/README.md @@ -0,0 +1,39 @@ +# Current View Triage + +This skill is the compact read-only triage card for Campus Copilot. + +It is designed to work like a lightweight plugin bundle: + +- one skill prompt that tells the agent what job to do +- one install/config pack that tells the operator how to connect the runtime +- one capability map that explains which Campus Copilot tools are exposed +- one demo path that shows the shortest first-success flow +- one troubleshooting page that explains where the first failures usually live +- one manifest so the folder can travel into review-driven skill registries + +Use it when you want the shortest truthful answer to: + +- what should the student do first right now + +## What this packet includes + +- `SKILL.md` + - the agent-facing triage workflow +- `README.md` + - the human-facing packet overview +- `manifest.yaml` + - registry-style metadata for host skill registries +- `references/README.md` + - the local index for every supporting file +- `references/INSTALL.md` + - install and host wiring guidance +- `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 read-only Campus Copilot tool surface +- `references/DEMO.md` + - the first-success walkthrough and expected output shape +- `references/TROUBLESHOOTING.md` + - the first places to check when setup or triage fails diff --git a/skills/campus-copilot-current-view-triage/SKILL.md b/skills/campus-copilot-current-view-triage/SKILL.md new file mode 100644 index 00000000..77c586b3 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/SKILL.md @@ -0,0 +1,76 @@ +--- +name: current-view-triage +description: Turn one Campus Copilot snapshot or MCP-backed current view into a plain-language what-to-do-first answer for a student. +--- + +# Current View Triage + +Use this skill when you want one plain-language answer to the question: + +- what should the student do first right now + +Treat it like a **read-only triage plugin card** over one imported workspace snapshot or one local BFF-backed current view, not a live-browser playbook. + +## What this skill teaches + +- how to prefer read-only Campus Copilot MCP or snapshot surfaces first +- how to turn Focus Queue and recent changes into one concrete next action +- how to answer with evidence and trust gaps instead of inventing missing facts + +## Runtime you need + +- one imported snapshot path or one current-view export +- or one connected Campus Copilot MCP server +- use `references/INSTALL.md` if the MCP server still needs to be connected +- use `references/DEMO.md` for the first-success walkthrough +- use `references/TROUBLESHOOTING.md` if setup or input truth is still unclear + +## Exposed MCP abilities + +- `campus_health` +- `providers_status` +- `ask_campus_copilot` +- the four `*_snapshot_view` tools +- `export_snapshot_artifact` + +Use `references/CAPABILITIES.md` when you need the quick map. + +## Inputs + +- `SNAPSHOT_PATH` or one current-view export path +- optional `QUESTION` +- optional `MCP_STATUS` + +## Steps + +1. Decide whether MCP-backed current view is available; otherwise stay on the imported snapshot/current-view export. +2. Build a short workspace summary from the strongest available read-only surface. +3. Inspect the top Focus Queue items and recent updates. +4. If a question is provided, use the cited-answer path instead of guessing. +5. Return: + - `top_action` + - `why_now` + - `evidence_used` + - `trust_gaps` + +## Good fit + +- Codex or Claude-style first-pass triage over a snapshot +- OpenClaw-style local consumers that need one short "what now" brief +- any read-only triage workflow that needs one trustworthy next action without reopening browser automation + +## Hard boundary + +- stay on imported snapshots or the thin local BFF +- do not claim live browser/session truth from snapshot-only evidence +- do not mutate site state + +## Companion references + +- `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/campus-copilot-current-view-triage/manifest.yaml b/skills/campus-copilot-current-view-triage/manifest.yaml new file mode 100644 index 00000000..69457741 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/manifest.yaml @@ -0,0 +1,41 @@ +schema_version: 1 +artifact: public-skill-listing-manifest + +skill: + name: current-view-triage + display_name: Current View Triage + version: 1.0.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/current-view-triage + submit_via: clawhub publish . --slug current-view-triage --name "Current View Triage" --version 1.0.0 --tags campus,student,triage,mcp,read-only + openhands-extensions: + status: review-pending + package_shape: skill-folder + submission_url: https://github.com/OpenHands/extensions/pull/155 + submit_via: submit this folder as skills/current-view-triage/ in OpenHands/extensions + +boundaries: + product_identity: Read-only student triage over Campus Copilot snapshots or current-view MCP output. + canonical_repo_version: 0.1.0 + official_listing_state: clawhub-live-openhands-review-pending + not_claimed: + - No live OpenHands/extensions listing exists yet + - No live browser-session truth is claimed from snapshot-only evidence + - No hosted Campus Copilot service is claimed + +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/campus-copilot-current-view-triage/references/CAPABILITIES.md b/skills/campus-copilot-current-view-triage/references/CAPABILITIES.md new file mode 100644 index 00000000..aa2ff515 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/CAPABILITIES.md @@ -0,0 +1,21 @@ +# Campus Copilot Capability Map + +This skill intentionally stays on the read-only Campus Copilot surfaces. + +## Core MCP tools + +- `campus_health` +- `providers_status` +- `ask_campus_copilot` +- `canvas_snapshot_view` +- `gradescope_snapshot_view` +- `edstem_snapshot_view` +- `myuw_snapshot_view` +- `export_snapshot_artifact` + +## Best default order + +1. `campus_health` +2. one or more `*_snapshot_view` tools +3. `ask_campus_copilot` if a question exists +4. `export_snapshot_artifact` only if the operator needs a saved proof artifact diff --git a/skills/campus-copilot-current-view-triage/references/DEMO.md b/skills/campus-copilot-current-view-triage/references/DEMO.md new file mode 100644 index 00000000..7dc89631 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/DEMO.md @@ -0,0 +1,23 @@ +# OpenHands / OpenClaw Demo Walkthrough + +This is the shortest concrete demo you can run to prove the skill is doing real +triage work instead of only existing as prose. + +## Demo prompt + +Use Campus Copilot to tell the student what to do first right now. Start with +`campus_health`. Then inspect the strongest available snapshot/current-view +surface. If a student question exists, answer it through `ask_campus_copilot`. +Return `top_action`, `why_now`, `evidence_used`, and `trust_gaps`. + +## Expected tool sequence + +1. `campus_health` +2. one or more `*_snapshot_view` tools +3. optionally `ask_campus_copilot` + +## Visible success criteria + +- the agent names one concrete first action +- the answer cites the Focus Queue or snapshot surface instead of guessing +- the boundary stays read-only and snapshot-aware diff --git a/skills/campus-copilot-current-view-triage/references/INSTALL.md b/skills/campus-copilot-current-view-triage/references/INSTALL.md new file mode 100644 index 00000000..28826ab3 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/INSTALL.md @@ -0,0 +1,36 @@ +# Campus Copilot MCP Setup + +Use this when the host runtime does not already have Campus Copilot MCP +connected. + +## Quickest local setup + +1. Clone the public repo: + +```bash +git clone https://github.com/xiaojiou176-open/campus-copilot.git +cd campus-copilot +pnpm install +``` + +2. Build the read-only MCP server: + +```bash +pnpm --filter @campus-copilot/mcp-server build +``` + +3. Start the MCP server directly: + +```bash +pnpm --filter @campus-copilot/mcp-server start +``` + +4. Before loading the host config snippets in this folder, replace + `/ABSOLUTE/PATH/TO/campus-copilot` with the real path to your local clone. + +## If your host supports MCP Bundles + +Campus Copilot also ships a release-hosted MCP bundle: + +- registry name: `io.github.xiaojiou176-open/campus-copilot-mcp` +- release asset: `https://github.com/xiaojiou176-open/campus-copilot/releases/download/v0.1.0/campus-copilot-mcp-0.1.0.mcpb` diff --git a/skills/campus-copilot-current-view-triage/references/OPENCLAW_MCP_CONFIG.json b/skills/campus-copilot-current-view-triage/references/OPENCLAW_MCP_CONFIG.json new file mode 100644 index 00000000..c3d15236 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/OPENCLAW_MCP_CONFIG.json @@ -0,0 +1,11 @@ +{ + "mcp": { + "servers": { + "campus-copilot": { + "command": "pnpm", + "args": ["--filter", "@campus-copilot/mcp-server", "start"], + "cwd": "/ABSOLUTE/PATH/TO/campus-copilot" + } + } + } +} diff --git a/skills/campus-copilot-current-view-triage/references/OPENHANDS_MCP_CONFIG.json b/skills/campus-copilot-current-view-triage/references/OPENHANDS_MCP_CONFIG.json new file mode 100644 index 00000000..6a46e05f --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/OPENHANDS_MCP_CONFIG.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "campus-copilot": { + "command": "pnpm", + "args": ["--filter", "@campus-copilot/mcp-server", "start"], + "cwd": "/ABSOLUTE/PATH/TO/campus-copilot" + } + } +} diff --git a/skills/campus-copilot-current-view-triage/references/README.md b/skills/campus-copilot-current-view-triage/references/README.md new file mode 100644 index 00000000..fec401bc --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/README.md @@ -0,0 +1,19 @@ +# Campus Copilot 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 Campus Copilot MCP server 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 read-only Campus Copilot tool surface and first-use order +- `DEMO.md` + - the shortest first-success walkthrough and expected output shape +- `TROUBLESHOOTING.md` + - the first places to check when setup or triage fails diff --git a/skills/campus-copilot-current-view-triage/references/TROUBLESHOOTING.md b/skills/campus-copilot-current-view-triage/references/TROUBLESHOOTING.md new file mode 100644 index 00000000..aa458b3e --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/TROUBLESHOOTING.md @@ -0,0 +1,26 @@ +# Campus Copilot Troubleshooting + +Use this page when the packet looks right on paper but the first triage answer +still fails. + +## 1. The MCP server does not launch + +Check these first: + +- `pnpm install` finished in the repo root +- the host config points at the right `cwd` +- the MCP server was built before you tried to start it + +If launch still fails, report it as a local MCP setup problem instead of +pretending the triage lane is ready. + +## 2. Only snapshot/current-view files are available + +That is allowed. Stay on the snapshot path and make the trust gap explicit. +Do not claim live browser or session truth. + +## 3. The question is broader than one read-only next action + +Stop after the triage answer and tell the user what extra surface is missing. +This packet is for “what should I do first right now,” not for broad workflow +automation. diff --git a/skills/campus-copilot-current-view-triage/references/capability-map.md b/skills/campus-copilot-current-view-triage/references/capability-map.md new file mode 100644 index 00000000..b4b6ad15 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/capability-map.md @@ -0,0 +1,21 @@ +# Current View Triage Capability Map + +This skill only needs the read-only Campus Copilot surfaces. + +## Core tools + +- `campus_health` +- `providers_status` +- `ask_campus_copilot` +- `canvas_snapshot_view` +- `gradescope_snapshot_view` +- `edstem_snapshot_view` +- `myuw_snapshot_view` +- `export_snapshot_artifact` + +## Best default order + +1. health +2. one or more snapshot-view tools +3. ask, if there is an explicit question +4. export only if the operator needs a saved proof artifact diff --git a/skills/campus-copilot-current-view-triage/references/example-output.md b/skills/campus-copilot-current-view-triage/references/example-output.md new file mode 100644 index 00000000..ccf93e84 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/example-output.md @@ -0,0 +1,8 @@ +# Example Output + +```text +Top action: Finish the Canvas item due tomorrow before the lower-priority backlog. +Why now: It is the nearest due item and it blocks the rest of the week's plan. +Evidence used: Focus Queue rank 1, recent current-view changes, and the Canvas snapshot slice. +Trust gaps: This answer is snapshot-scoped and does not claim live browser truth. +``` diff --git a/skills/campus-copilot-current-view-triage/references/input-shape.md b/skills/campus-copilot-current-view-triage/references/input-shape.md new file mode 100644 index 00000000..b1ab9f43 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/input-shape.md @@ -0,0 +1,43 @@ +# Current View Input Shape + +Use this when Campus Copilot MCP is not connected and the agent only has a snapshot or current-view export. + +## What the triage skill needs + +At minimum, the input should expose: + +- top Focus Queue items +- recent changes or recent updates +- enough site context to decide which area is most urgent + +## Minimal mental model + +The exact JSON can vary, but the triage workflow expects something equivalent to: + +```json +{ + "generatedAt": "2026-04-08T00:00:00Z", + "focusQueue": [ + { + "title": "Homework 1", + "site": "canvas", + "priority": "high" + } + ], + "recentChanges": [ + { + "site": "canvas", + "summary": "New assignment detected" + } + ] +} +``` + +## If you only have a raw workspace snapshot + +Use the smallest helpful transformation first: + +- inspect the `*_snapshot_view` MCP tools, or +- ask for a current-view export that already summarizes Focus Queue and recent changes + +Do not invent overdue items, grades, or browser/session truth that are not present in the provided input. diff --git a/skills/campus-copilot-current-view-triage/references/mcp-setup.md b/skills/campus-copilot-current-view-triage/references/mcp-setup.md new file mode 100644 index 00000000..2bec6007 --- /dev/null +++ b/skills/campus-copilot-current-view-triage/references/mcp-setup.md @@ -0,0 +1,22 @@ +# Current View Triage MCP Setup + +## Fastest local setup + +From the Campus Copilot repo root: + +```bash +pnpm install +pnpm --filter @campus-copilot/mcp-server build +pnpm --filter @campus-copilot/mcp-server start +``` + +## If the host supports MCP Bundles + +- registry name: `io.github.xiaojiou176-open/campus-copilot-mcp` +- release asset: `https://github.com/xiaojiou176-open/campus-copilot/releases/download/v0.1.0/campus-copilot-mcp-0.1.0.mcpb` + +## Minimum handoff to the agent + +- one imported snapshot or current-view export path +- whether Campus Copilot MCP is already connected +- optional student question diff --git a/skills/sourceharbor-watchlist-briefing/README.md b/skills/sourceharbor-watchlist-briefing/README.md new file mode 100644 index 00000000..893bb38f --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/README.md @@ -0,0 +1,37 @@ +# SourceHarbor Watchlist Briefing + +This skill is the OpenClaw-facing watchlist briefing card for SourceHarbor. + +It is designed to behave like a self-contained operator skill package: + +- one skill prompt that teaches the agent the workflow +- one install/config pack for MCP and HTTP fallback +- one capability map over the SourceHarbor operator surfaces +- one first-success demo path +- one troubleshooting page that explains where the first failures live +- one manifest so the folder can travel into review-driven skill registries + +Use it when the agent should start from one watchlist, reuse the current story/briefing context, and answer one operator question with evidence. + +## What this packet includes + +- `SKILL.md` + - the agent-facing watchlist briefing workflow +- `README.md` + - the human-facing packet overview +- `manifest.yaml` + - registry-style metadata for host skill registries +- `references/README.md` + - the local index for every supporting file +- `references/INSTALL.md` + - MCP and HTTP setup guidance +- `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 operator-facing MCP capability map +- `references/DEMO.md` + - the first-success walkthrough and expected output shape +- `references/TROUBLESHOOTING.md` + - the first places to check when MCP or HTTP access fails diff --git a/skills/sourceharbor-watchlist-briefing/SKILL.md b/skills/sourceharbor-watchlist-briefing/SKILL.md new file mode 100644 index 00000000..64a947fe --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/SKILL.md @@ -0,0 +1,102 @@ +--- +name: sourceharbor-watchlist-briefing +description: Use SourceHarbor watchlists, briefings, Ask, MCP, and HTTP API to answer one question with current story context and evidence. +triggers: + - sourceharbor + - watchlist + - briefing + - operator question +--- + +# SourceHarbor Watchlist Briefing + +Use this skill when you want OpenClaw to inspect one SourceHarbor watchlist and +answer a question with the current story and evidence context. + +Think of it as an **operator briefing skill card**: + +- it teaches the agent the workflow +- it names the MCP/HTTP setup needed +- it shows which SourceHarbor capabilities matter +- it keeps the answer evidence-backed and operational + +## Goal + +- start from one watchlist +- reuse the current briefing or story payload +- answer one operator question +- cite the evidence used +- return one concrete next action + +## Runtime you need + +- one connected SourceHarbor MCP server, or +- one running SourceHarbor HTTP API at `SOURCE_HARBOR_API_BASE_URL` +- if either still needs wiring, use `references/INSTALL.md` + +## Exposed MCP abilities + +This skill is built around these SourceHarbor capability groups: + +- health +- retrieval / Ask-style evidence lookup +- jobs and compare views +- artifacts and reports +- workflows, subscriptions, and notifications when the question is really about operator state + +Use `references/CAPABILITIES.md` for the concrete tool map. + +## Inputs To Fill In + +- `WATCHLIST_ID`: the watchlist you want to inspect +- `QUESTION`: the question you want answered +- `SOURCE_HARBOR_API_BASE_URL`: the SourceHarbor API base URL when MCP is not wired +- `SOURCE_HARBOR_MCP_STATUS`: whether SourceHarbor MCP is already connected + +## Workflow + +Use the strongest available path in this order: + +1. SourceHarbor MCP, if it is already connected +2. SourceHarbor HTTP API at `SOURCE_HARBOR_API_BASE_URL` +3. SourceHarbor web routes only as visible proof surfaces + +Required steps: + +1. Load the watchlist object. +2. Load the current watchlist briefing or briefing page payload. +3. Identify the selected story and the recent changes. +4. Answer `QUESTION` using that story context. +5. Return: + - Current story + - What changed + - Evidence used + - Suggested next operator action + +## Output contract + +Return: + +- `current_story` +- `what_changed` +- `evidence_used` +- `suggested_next_action` +- `runtime_gap` if MCP or HTTP access was partial + +## Guardrails + +- Do not pretend SourceHarbor is a hosted SaaS. +- Do not turn sample/demo surfaces into live-proof claims. +- Do not answer without evidence. +- If MCP or HTTP access is partial, say so clearly instead of filling gaps. + +## Companion references + +- `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/sourceharbor-watchlist-briefing/manifest.yaml b/skills/sourceharbor-watchlist-briefing/manifest.yaml new file mode 100644 index 00000000..6391ccff --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/manifest.yaml @@ -0,0 +1,41 @@ +schema_version: 1 +artifact: public-skill-listing-manifest + +skill: + name: sourceharbor-watchlist-briefing + display_name: SourceHarbor Watchlist Briefing + version: 1.0.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/sourceharbor-watchlist-briefing + submit_via: clawhub publish . --slug sourceharbor-watchlist-briefing --name "SourceHarbor Watchlist Briefing" --version 1.0.0 --tags sourceharbor,watchlist,briefing,mcp,operator + openhands-extensions: + status: review-pending + package_shape: skill-folder + submission_url: https://github.com/OpenHands/extensions/pull/155 + submit_via: submit this folder as skills/sourceharbor-watchlist-briefing/ in OpenHands/extensions + +boundaries: + product_identity: Watchlist-first operator briefing skill over SourceHarbor MCP or local HTTP API. + canonical_repo_version: 0.1.14 + official_listing_state: clawhub-live-openhands-review-pending + not_claimed: + - No live OpenHands/extensions listing exists yet + - No hosted SourceHarbor SaaS is claimed + - No answer should be given without evidence + +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/sourceharbor-watchlist-briefing/references/CAPABILITIES.md b/skills/sourceharbor-watchlist-briefing/references/CAPABILITIES.md new file mode 100644 index 00000000..769d46eb --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/CAPABILITIES.md @@ -0,0 +1,22 @@ +# SourceHarbor Capability Map + +This skill focuses on the SourceHarbor surfaces that help answer one operator +question from one watchlist. + +## Relevant MCP capability groups + +- `sourceharbor.health.get` +- `sourceharbor.retrieval.search` +- `sourceharbor.jobs.get` +- `sourceharbor.jobs.compare` +- `sourceharbor.artifacts.get` +- `sourceharbor.reports.daily_send` +- `sourceharbor.workflows.run` + +## Best default order + +1. health +2. watchlist + briefing payload +3. retrieval or ask-style evidence lookup +4. jobs or artifacts only when the answer needs proof of what changed +5. do not drift into subscription or notification changes unless the operator changes the task diff --git a/skills/sourceharbor-watchlist-briefing/references/DEMO.md b/skills/sourceharbor-watchlist-briefing/references/DEMO.md new file mode 100644 index 00000000..c9f99a21 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/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 +operator-briefing work instead of only existing as prose. + +## Demo prompt + +Inspect one SourceHarbor watchlist and answer one operator question with +evidence. Start with the watchlist object and current briefing payload. Then +name the current story, what changed, the evidence used, and the suggested next +operator action. + +## Expected sequence + +1. health +2. watchlist or briefing payload +3. retrieval / search if the briefing is incomplete +4. jobs or artifacts only if the answer needs proof of what changed + +## Visible success criteria + +- the answer starts from one explicit watchlist +- the answer names the current story and what changed +- the answer cites evidence and ends with one concrete next action diff --git a/skills/sourceharbor-watchlist-briefing/references/INSTALL.md b/skills/sourceharbor-watchlist-briefing/references/INSTALL.md new file mode 100644 index 00000000..46bab525 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/INSTALL.md @@ -0,0 +1,27 @@ +# SourceHarbor MCP And HTTP Setup + +Use this when the host runtime does not already have SourceHarbor connected. + +## Local repo setup + +1. Clone the public repo: + +```bash +git clone https://github.com/xiaojiou176-open/sourceharbor.git +cd sourceharbor +``` + +2. Start the local MCP surface: + +```bash +./bin/dev-mcp +``` + +3. Before loading the host config snippets in this folder, replace + `/ABSOLUTE/PATH/TO/sourceharbor` with the real path to your local clone. + +4. If you need the HTTP API fallback, make sure the local API is running and set: + +```bash +export SOURCE_HARBOR_API_BASE_URL=http://127.0.0.1:9000 +``` diff --git a/skills/sourceharbor-watchlist-briefing/references/OPENCLAW_MCP_CONFIG.json b/skills/sourceharbor-watchlist-briefing/references/OPENCLAW_MCP_CONFIG.json new file mode 100644 index 00000000..535def8f --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/OPENCLAW_MCP_CONFIG.json @@ -0,0 +1,10 @@ +{ + "mcp": { + "servers": { + "sourceharbor": { + "command": "./bin/dev-mcp", + "cwd": "/ABSOLUTE/PATH/TO/sourceharbor" + } + } + } +} diff --git a/skills/sourceharbor-watchlist-briefing/references/OPENHANDS_MCP_CONFIG.json b/skills/sourceharbor-watchlist-briefing/references/OPENHANDS_MCP_CONFIG.json new file mode 100644 index 00000000..8df3bfbf --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/OPENHANDS_MCP_CONFIG.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "sourceharbor": { + "command": "./bin/dev-mcp", + "cwd": "/ABSOLUTE/PATH/TO/sourceharbor" + } + } +} diff --git a/skills/sourceharbor-watchlist-briefing/references/README.md b/skills/sourceharbor-watchlist-briefing/references/README.md new file mode 100644 index 00000000..d4e848f9 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/README.md @@ -0,0 +1,19 @@ +# SourceHarbor Skill References + +This directory keeps the practical material that a reviewer or agent needs +without depending on repo-root docs. + +## Included references + +- `INSTALL.md` + - MCP and HTTP setup guidance for the local operator path +- `OPENHANDS_MCP_CONFIG.json` + - a ready-to-edit `mcpServers` snippet +- `OPENCLAW_MCP_CONFIG.json` + - a ready-to-edit `mcp.servers` snippet +- `CAPABILITIES.md` + - the operator-facing MCP capability map and safe-first order +- `DEMO.md` + - the first-success walkthrough and expected output shape +- `TROUBLESHOOTING.md` + - the first places to check when MCP or HTTP access fails diff --git a/skills/sourceharbor-watchlist-briefing/references/TROUBLESHOOTING.md b/skills/sourceharbor-watchlist-briefing/references/TROUBLESHOOTING.md new file mode 100644 index 00000000..4822462c --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/TROUBLESHOOTING.md @@ -0,0 +1,30 @@ +# SourceHarbor Troubleshooting + +Use this page when the packet looks right on paper but the first watchlist +briefing still fails. + +## 1. MCP is unavailable + +Use the HTTP fallback path from `INSTALL.md` and make the runtime gap explicit. +Do not pretend MCP was connected. + +## 2. The HTTP API fallback is unavailable + +Check these first: + +- the local API is running +- `SOURCE_HARBOR_API_BASE_URL` points at the right base URL +- the watchlist id is valid + +If the briefing payload still does not load, report the exact missing endpoint +instead of inventing a story summary. + +## 3. The operator question needs more than the current briefing + +Escalate narrowly: + +1. retrieval / ask-style evidence lookup +2. jobs or compare view only if needed +3. artifacts only if needed + +Do not widen into unrelated subscription or notification changes. diff --git a/skills/sourceharbor-watchlist-briefing/references/capability-map.md b/skills/sourceharbor-watchlist-briefing/references/capability-map.md new file mode 100644 index 00000000..55e58b8b --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/capability-map.md @@ -0,0 +1,21 @@ +# SourceHarbor Capability Map + +This skill focuses on the SourceHarbor surfaces that help answer one operator question from one watchlist. + +## Relevant MCP capability groups + +- `sourceharbor.health.get` +- `sourceharbor.retrieval.search` +- `sourceharbor.jobs.get` +- `sourceharbor.jobs.compare` +- `sourceharbor.artifacts.get` +- `sourceharbor.reports.daily_send` +- `sourceharbor.workflows.run` + +## Best default order + +1. health +2. watchlist + briefing payload +3. retrieval / ask-style evidence lookup +4. jobs or artifacts only when the answer needs proof of what changed +5. do not drift into subscription or notification changes unless the operator changes the task diff --git a/skills/sourceharbor-watchlist-briefing/references/example-output.md b/skills/sourceharbor-watchlist-briefing/references/example-output.md new file mode 100644 index 00000000..86fb1622 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/example-output.md @@ -0,0 +1,9 @@ +# Example Output + +```text +Current story: The selected watchlist still centers on the same claim, but the latest compare window added one new evidence run. +What changed: One source was added, one previous item fell out of the compare window, and the selected story summary shifted. +Evidence used: current briefing payload, latest compare summary, and one artifact lookup. +Suggested next action: Re-run retrieval/search for the selected watchlist before sending the next operator briefing. +Runtime gap: MCP was unavailable, so this answer used the local HTTP fallback. +``` diff --git a/skills/sourceharbor-watchlist-briefing/references/http-fallback.md b/skills/sourceharbor-watchlist-briefing/references/http-fallback.md new file mode 100644 index 00000000..b9626f00 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/http-fallback.md @@ -0,0 +1,38 @@ +# SourceHarbor HTTP Fallback + +Use this path only when SourceHarbor MCP is unavailable and the local HTTP API is already running. + +## Required base URL + +```bash +export SOURCE_HARBOR_API_BASE_URL=http://127.0.0.1:9000 +``` + +## Most relevant endpoints + +1. Get the watchlist object: + +```bash +curl -s "$SOURCE_HARBOR_API_BASE_URL/api/v1/watchlists/$WATCHLIST_ID" +``` + +2. Get the unified briefing payload: + +```bash +curl -s "$SOURCE_HARBOR_API_BASE_URL/api/v1/watchlists/$WATCHLIST_ID/briefing" +``` + +3. If you need the selected-story page payload: + +```bash +curl -s "$SOURCE_HARBOR_API_BASE_URL/api/v1/watchlists/$WATCHLIST_ID/briefing/page?story_id=$STORY_ID" +``` + +## What to extract + +- the current story summary +- what changed across the compare window +- cited evidence cards or artifact references +- the next action implied by the current story + +If the briefing payload is not enough to answer the question, say so instead of inventing a conclusion. diff --git a/skills/sourceharbor-watchlist-briefing/references/mcp-and-http-setup.md b/skills/sourceharbor-watchlist-briefing/references/mcp-and-http-setup.md new file mode 100644 index 00000000..aaf22726 --- /dev/null +++ b/skills/sourceharbor-watchlist-briefing/references/mcp-and-http-setup.md @@ -0,0 +1,28 @@ +# SourceHarbor OpenClaw Setup + +## Fastest local setup + +From the SourceHarbor repo root: + +```bash +./bin/dev-mcp +``` + +If the MCP client is not wired yet, keep the HTTP fallback ready: + +```bash +export SOURCE_HARBOR_API_BASE_URL=http://127.0.0.1:9000 +``` + +## OpenClaw starter-pack files + +- `../../openclaw.plugin.json` +- `../../sourceharbor-mcp-template.json` +- `../../README.md` + +## Minimum handoff to the agent + +- one `WATCHLIST_ID` +- one `QUESTION` +- whether MCP is connected +- the live `SOURCE_HARBOR_API_BASE_URL` if HTTP fallback is needed