Building Skills

clawhub install simmer-skill-builder

your-skill-slug/
  SKILL.md          # AgentSkills-compliant metadata + docs
  clawhub.json      # ClawHub + automaton config
  your_script.py    # Main trading logic

---
name: your-skill-slug
description: One sentence describing what it does and when to use it.
metadata:
  author: "Your Name"
  version: "1.0.0"
  displayName: "Your Skill Name"
  difficulty: "intermediate"
---

{
  "emoji": "your-emoji",
  "primaryEnv": "SIMMER_API_KEY",
  "requires": {
    "pip": ["simmer-sdk"],
    "env": ["SIMMER_API_KEY"]
  },
  "envVars": [
    {
      "name": "SIMMER_API_KEY",
      "required": true,
      "description": "Your Simmer SDK API key — get from simmer.markets/dashboard"
    },
    {
      "name": "WALLET_PRIVATE_KEY",
      "required": false,
      "description": "Only needed for external-wallet self-custody trading."
    }
  ],
  "cron": "*/15 * * * *",
  "automaton": {
    "managed": true,
    "entrypoint": "your_script.py"
  }
}

import os
from simmer_sdk import SimmerClient

_client = None
def get_client():
    global _client
    if _client is None:
        _client = SimmerClient(
            api_key=os.environ["SIMMER_API_KEY"],
            venue="polymarket"
        )
    return _client

TRADE_SOURCE = "sdk:your-skill-slug"
SKILL_SLUG = "your-skill-slug"  # Must match ClawHub slug

# Always include reasoning
client = get_client()
client.trade(
    market_id=market_id,
    side="yes",
    amount=10.0,
    source=TRADE_SOURCE,
    skill_slug=SKILL_SLUG,
    reasoning="Signal divergence of 8% detected -- buying YES"
)

> **This is a template.** The default signal is [your signal source] —
> remix it with [alternative signals, different models, etc.].
> The skill handles all the plumbing (market discovery, trade execution,
> safeguards). Your agent provides the alpha.

def get_market_context(market_id, my_probability=None):
    """Fetch context with safeguards and optional edge analysis."""
    params = {}
    if my_probability is not None:
        params["my_probability"] = my_probability
    return get_client().get_market_context(market_id, **params)

# Before buying
context = get_market_context(market_id, my_probability=0.85)

# Check warnings
trading = context.get("trading", {})
flip_flop = trading.get("flip_flop_warning")
if flip_flop and "SEVERE" in flip_flop:
    print(f"Skipping: {flip_flop}")
    # Don't trade -- you've been reversing too much

slippage = context.get("slippage", {})
if slippage.get("slippage_pct", 0) > 0.15:
    print("Skipping: slippage too high")
    # Market is too illiquid for this size

# Check edge (requires my_probability)
edge = context.get("edge_analysis", {})
if edge.get("recommendation") == "HOLD":
    print("Skipping: edge below threshold")

def ensure_market_indexed(polymarket_url, cache):
    """Return (simmer_market_id, error). Hits cache, then check (free), then
    import (consumes quota)."""
    if polymarket_url in cache:
        return cache[polymarket_url], None

    # Free pre-flight — does NOT consume import quota
    check = client.check_market_exists(url=polymarket_url)
    if check["exists"]:
        cache[polymarket_url] = check["market_id"]
        return check["market_id"], None

    # Not indexed — consume one import from the daily quota
    result = client.import_market(polymarket_url)
    if result.get("status") in ("imported", "already_exists"):
        cache[polymarket_url] = result["market_id"]
        return result["market_id"], None
    return None, f"import status={result.get('status')}"

# I only paper-trade on sim
trades = client.get_trades(venue="sim")

# I'm a real-money Polymarket skill
positions = client.get_portfolio(venue="polymarket")

# I want everything (default)
all_state = client.get_briefing()

briefing = client.get_briefing()
# briefing.venues.sim        → {balance, pnl, positions_count, positions_needing_attention}
# briefing.venues.polymarket → {balance, pnl, positions_count, redeemable_count, ...}
# briefing.venues.kalshi     → {balance, pnl, positions_count, ...}

for trade in client.get_trades(limit=20)["trades"]:
    print(f"{trade['venue']}: {trade['side']} {trade['shares']} @ {trade['avg_price']}")

portfolio = client.get_portfolio()  # default venue=all
print(f"Sim exposure: {portfolio['sim']['total_exposure']} $SIM")
print(f"Polymarket exposure: ${portfolio['polymarket']['total_exposure']}")
print(f"Total position count: {portfolio['total']['positions_count']}")

ctx = client.get_market_context(market_id)
sim_pos = ctx["positions"]["sim"]
if sim_pos and sim_pos["has_position"]:
    print(f"Holding {sim_pos['shares']} $SIM shares")

# At the start or end of each cycle -- safe to call frequently
results = get_client().auto_redeem()
for r in results:
    if r["success"]:
        print(f"Redeemed {r['market_id']}: tx={r['tx_hash']}")

from simmer_sdk.sizing import size_position

amount = size_position(
    p_win=0.70,         # your model's probability
    market_price=0.55,  # current YES price
    bankroll=bankroll,
    min_ev=0.03,        # skip trades with edge < 3%
)
if amount > 0:
    client.trade(market_id=..., side="BUY", outcome="YES",
                 amount=amount, reasoning="...")

# From inside your skill folder
npx clawhub@latest publish . --slug your-skill-slug --version 1.0.0

# Or auto-bump version
npx clawhub@latest publish . --slug your-skill-slug --bump patch

npx clawhub@latest install your-skill-slug

npx clawhub@latest publish . --slug your-skill-slug --bump patch