Skill: xiaojiou176/sourceharbor-watchlist-briefing (version 1.0.0)

--- 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`

path: README.md
content: # 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


path: manifest.yaml
content: 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


path: references/CAPABILITIES.md
content: # 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


path: references/DEMO.md
content: # 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


path: references/INSTALL.md
content: # 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
```


path: references/OPENCLAW_MCP_CONFIG.json
content: {
  "mcp": {
    "servers": {
      "sourceharbor": {
        "command": "./bin/dev-mcp",
        "cwd": "/ABSOLUTE/PATH/TO/sourceharbor"
      }
    }
  }
}


path: references/OPENHANDS_MCP_CONFIG.json
content: {
  "mcpServers": {
    "sourceharbor": {
      "command": "./bin/dev-mcp",
      "cwd": "/ABSOLUTE/PATH/TO/sourceharbor"
    }
  }
}


path: references/README.md
content: # 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


path: references/TROUBLESHOOTING.md
content: # 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.


path: references/capability-map.md
content: # 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


path: references/example-output.md
content: # 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.
```


path: references/http-fallback.md
content: # 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.


path: references/mcp-and-http-setup.md
content: # 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)