Prediction Market Arbitrage

Orchestrates monitoring, market odds, and execution proxy tools to detect news-market price gaps and emit arbitrage alerts with optional trade plans.

Security Scan

This meta-skill is internally coherent for orchestrating local monitoring, market lookup, and an execution-proxy tool, but it requires a trading API key (SIMMER_API_KEY) even though execution can be alert-only — you should be aware of that and lock down the key and agent autonomy before enabling execution.

Purpose & Capability

The skill's name and description match the actions in SKILL.md: it orchestrates topic-monitor, polymarket-odds, and simmer-weather for arbitrage alerting. Requiring python3/node/npx is expected because the upstream skills are Python/Node and installation uses npx. One minor mismatch: SIMMER_API_KEY is declared as required even though the workflow explicitly supports an 'alert-only' execution_mode; making the API key mandatory is not strictly necessary for alert-only operation.

Instruction Scope

The SKILL.md confines runtime actions to invoking the three upstream skills, normalizing values, applying hard decision rules, and emitting alerts or execution plans. It does not instruct the agent to read unrelated system files, other environment variables, or external endpoints beyond the described ClawHub skills and Simmer endpoints. It explicitly warns not to auto-trade unless the user asks.

Install Mechanism

This is instruction-only (no install spec or code blobs). The recommended install uses npx clawhub@latest to install upstream skills — a reasonable, traceable approach. No downloads from arbitrary URLs or archive extractions are present in the skill itself.

Credentials

Only one env var is requested: SIMMER_API_KEY. That is expected for the simmer-weather execution proxy, but declaring it as required (rather than optional) is disproportionate if users will run in alert-only mode. SIMMER_API_KEY is a trading credential; supplying it enables live trading via the cited execution proxy if downstream components or operators invoke execution. Users should treat this key as sensitive, store it in a secrets manager, and avoid providing it unless they intend to permit trade execution.

Persistence & Privilege

The skill does not request always:true, does not modify other skills' configs, and does not demand persistent system-wide privileges. user-invocable is true and autonomous invocation is allowed (disable-model-invocation:false) — this is platform-default and acceptable here, but users should be mindful that an agent with this skill could be asked to perform repeated monitoring and, if credentials are supplied, to prepare execution plans.

Assessment

This skill appears to do what it says: orchestrate monitoring, market lookups, and optional execution guidance. Before installing, consider these steps: (1) Only provide SIMMER_API_KEY if you explicitly want the agent to be able to produce execution plans or run dry-run/live trades; otherwise keep it unset and use alert-only mode. (2) Store SIMMER_API_KEY in a secrets manager or environment that is not broadly accessible, and rotate it regularly. (3) Audit the upstream skills (topic-monitor, polymarket-odds, simmer-weather) that this meta-skill orchestrates — the meta-skill delegates behavior to them. (4) Run the workflow in dry-run mode first and verify that alerts and decision logic behave as expected. (5) Limit agent autonomy and review logs before enabling any live execution path. If you want a stricter review, provide the upstream skills' code or the Simmer SDK docs so I can check exactly how the API key is used and whether any hidden network endpoints are contacted.

Purpose

Use this meta-skill to coordinate three existing ClawHub skills into one causal arbitrage workflow:

1. Detect new high-signal news about a target event.
2. Fetch current market-implied probability from Polymarket.
3. Compare news confidence vs market probability.
4. Emit actionable alert, optionally followed by explicit execution guidance.

This skill does not replace the underlying skills. It defines how to combine them correctly.

Required Installed Skills

This meta-skill assumes these are already installed locally:

• topic-monitor (inspected: latest 1.3.4)
• polymarket-odds (inspected: latest 1.0.0)
• simmer-weather (inspected: latest 1.7.1, execution proxy pattern)

Install/refresh with ClawHub:

npx -y clawhub@latest install topic-monitor
npx -y clawhub@latest install polymarket-odds
npx -y clawhub@latest install simmer-weather
npx -y clawhub@latest update --all

Verify:

npx -y clawhub@latest list
python3 skills/topic-monitor/scripts/monitor.py --help
node skills/polymarket-odds/polymarket.mjs --help
python3 skills/simmer-weather/weather_trader.py --help

If any command fails, stop and report missing dependency or wrong install path.

Inputs the LM Must Collect First

• ceo_name
• company_name
• event_hypothesis (for example: CEO X resigns within 30 days)
• market_query (for polymarket search)
• topic_id (stable ID in topic-monitor)
• monitor_interval_minutes (default: 5)
• min_news_confidence (default: 0.80)
• min_delta (default: 0.25)
• execution_mode (alert-only or execution-plan)

Do not continue with implicit trading assumptions if these are missing.

Skill Responsibilities (What Each Tool Actually Does)

topic-monitor

Use for continuous signal discovery and scoring.

Operationally relevant behavior:

• Topic config via scripts/manage_topics.py.
• Monitoring loop via scripts/monitor.py.
• Priority/score generated by its scoring logic.
• Alert queue retrieval via scripts/process_alerts.py --json.

This is the source of news confidence candidates.

polymarket-odds

Use for live market probability lookups.

Operationally relevant behavior:

• search <query> to find matching events/markets.
• market <slug> to inspect specific market pricing.
• Outputs percentage-formatted odds that must be normalized to [0,1].

This is the source of market probability.

simmer-weather

Primary design is weather strategy, but in this chain it is treated as execution proxy reference because it uses Simmer SDK trade endpoints and live/dry-run safety pattern.

Operationally relevant behavior:

• Requires SIMMER_API_KEY.
• Supports dry-run and live execution modes.
• Demonstrates guarded trading workflow and position checks.

In this meta-skill, it is not the signal engine. It is the execution pattern reference.

Canonical Causal Chain

Use this exact chain:

1. topic-monitor heartbeat every 5 minutes.
2. Match target rumor pattern (resignation, ceo_name, company_name).
3. Accept only high-confidence signal (news_confidence >= 0.80).
4. Query polymarket-odds for matching market and read current yes probability.
5. Compute delta = news_confidence - market_probability.
6. If delta >= min_delta, trigger arbitrage alert.
7. If execution_mode=execution-plan, output explicit next trading step; do not auto-trade unless user explicitly asks.

Data Contract Between Skills

Normalize all values into one record before decisioning:

{
  "topic_id": "ceo-resignation-acme",
  "event_hypothesis": "CEO X resigns",
  "news_confidence": 0.82,
  "news_signal_time": "2026-02-14T14:05:00Z",
  "market_slug": "will-ceo-x-resign",
  "market_probability": 0.40,
  "market_snapshot_time": "2026-02-14T14:06:00Z",
  "delta": 0.42,
  "decision": "buy_yes_candidate"
}

Hard rules:

• Reject stale signal if news_signal_time is older than 30 minutes.
• Reject stale market snapshot older than 5 minutes.
• Never compare percentages and decimals mixed. Convert all to decimals first.

LM Execution Playbook

Step A: Configure topic once

python3 skills/topic-monitor/scripts/manage_topics.py add \
  "CEO Resignation - <company_name>" \
  --id <topic_id> \
  --query "<ceo_name> resignation <company_name> CEO stepping down" \
  --keywords "resignation,<ceo_name>,<company_name>,CEO,board,step down" \
  --frequency hourly \
  --importance high \
  --channels telegram \
  --context "Prediction market mispricing detection"

Step B: Run heartbeat loop externally (every 5 min)

python3 skills/topic-monitor/scripts/monitor.py --topic <topic_id> --force
python3 skills/topic-monitor/scripts/process_alerts.py --json

Use max recent score for confidence extraction.

Step C: Pull market probability

node skills/polymarket-odds/polymarket.mjs search "<market_query>"
node skills/polymarket-odds/polymarket.mjs market <market_slug>

Extract yes-price and normalize (40% -> 0.40).

Step D: Decide

Formula:

• delta = news_confidence - market_probability
• Trigger if news_confidence >= min_news_confidence and delta >= min_delta

Step E: Emit output

If triggered, emit:

🚨 ARBITRAGE: News bestätigen, Markt schläft. Kauf empfohlen.

Plus structured fields:

• news_confidence
• market_probability
• delta
• signal_age_minutes
• market_age_minutes
• recommendation

Output Modes

alert-only

Return recommendation and confidence math only. No execution step.

execution-plan

Return recommendation plus explicit manual next actions using installed simmer-weather runtime pattern:

• check API key present
• run dry-run first
• require explicit user confirmation before any live action

Guardrails for the LM

• Do not fabricate market slugs or prices.
• Do not promote execution when confidence math is below threshold.
• Do not issue live-trade instructions without clear user opt-in.
• Surface uncertainty explicitly when matching query to market is ambiguous.
• Prefer false-negative over false-positive when news credibility is weak.

Failure Handling

• Missing skill install: output exact missing path/command.
• Missing env var (SIMMER_API_KEY): degrade to alert-only.
• No market match: return no_trade with retry query suggestions.
• Conflicting signals: require two independent high-confidence hits before alerting.

Why This Meta-Skill Exists

Without orchestration, each tool solves only a fragment:

• topic-monitor detects events but has no market-price context.
• polymarket-odds shows prices but no external signal confidence.
• simmer-weather demonstrates execution mechanics but is not a generic event detector.

This meta-skill binds those fragments into one coherent arbitrage decision process that an LM can execute consistently.