Add AI skill for agentic CLI usage

.agents/skills/polymarket-cli/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: polymarket-cli
+description: Browse prediction markets, place orders, manage positions, and interact with Polymarket onchain contracts via the polymarket CLI. Use when a user asks to search markets, check prices, trade, manage wallets, view portfolios, or translate a task into safe polymarket-cli commands with correct flags, output format, and confirmations.
+---
+
+# Polymarket CLI
+
+## Overview
+
+polymarket-cli is a Rust terminal tool for interacting with [Polymarket](https://polymarket.com). It supports browsing markets, placing limit and market orders, managing wallets and positions, interacting with on-chain conditional token contracts, and retrieving leaderboard and portfolio data. Every command supports table (default) and JSON output.
+
+> **Warning:** This is early, experimental software. Do not use with large amounts of funds. APIs, commands, and behavior may change without notice. Always verify transactions before confirming.
+
+## Installation
+
+```bash
+# Install script (macOS/Linux, verifies SHA256 checksum)
+curl -sSL https://raw.githubusercontent.com/Polymarket/polymarket-cli/main/install.sh | sh
+
+# Build from source
+git clone https://github.com/Polymarket/polymarket-cli
+cd polymarket-cli && cargo install --path .
+
+# Upgrade
+polymarket upgrade
+```
+
+## Defaults and safety
+
+- Confirm the target wallet and resolve key precedence: `--private-key` flag > `POLYMARKET_PRIVATE_KEY` env var > config file (`~/.config/polymarket/config.json`).
+- Never pass private keys in flags when possible; prefer the config file or env var.
+- Require confirmation for destructive or financial actions (placing orders, canceling orders, approving contracts, splitting/merging/redeeming tokens).
+- Trading commands require USDC balance on Polygon. On-chain operations (`approve set`, `ctf split/merge/redeem`) require MATIC for gas.
+- Default signature type is `proxy`. Override with `--signature-type eoa` or `--signature-type gnosis-safe` only when the user explicitly requests it.
+- Choose output format: table by default, `-o json` for structured output.
+
+## What needs a wallet
+
+Most commands work without a wallet (browsing markets, viewing order books, checking prices, on-chain data lookups). A wallet is required only for:
+- Placing and canceling orders (`clob create-order`, `clob market-order`, `clob cancel-*`)
+- Checking your balances and trades (`clob balance`, `clob trades`, `clob orders`)
+- On-chain operations (`approve set`, `ctf split/merge/redeem`)
+- Reward and API key management (`clob rewards`, `clob create-api-key`)
+
+## Quick start
+
+```bash
+# Browse markets (no wallet needed)
+polymarket markets list --limit 5
+polymarket markets search "election"
+polymarket events list --tag politics
+
+# Check a specific market
+polymarket markets get will-trump-win-the-2024-election
+
+# JSON output for scripts
+polymarket -o json markets list --limit 3
+
+# Set up a wallet to trade
+polymarket setup
+# Or manually:
+polymarket wallet create
+polymarket approve set
+```
+
+## Task guidance
+
+### Browsing and research
+- Use `markets list` with `--limit`, `--offset`, `--order`, `--ascending`, `--active`, `--closed` for filtered browsing.
+- Use `markets search "<query>"` to find markets by keyword.
+- Use `markets get <id-or-slug>` for a single market detail.
+- Use `events list` with `--tag` to browse grouped markets by topic.
+- Use `clob book <token_id>` and `clob price-history <token_id> --interval 1d` for order book and price data.
+
+### Trading
+- Use `clob create-order --token <id> --side buy --price 0.50 --size 10` for limit orders.
+- Use `clob market-order --token <id> --side buy --amount 5` for market orders.
+- Use `clob post-orders` with `--tokens`, `--prices`, `--sizes` for batch orders.
+- Order types: `GTC` (default), `FOK`, `GTD`, `FAK`. Add `--post-only` for limit orders.
+- Cancel: `clob cancel <order_id>`, `clob cancel-orders "<id1>,<id2>"`, `clob cancel-market --market <condition_id>`, `clob cancel-all`.
+
+### Portfolio monitoring
+- Use `data positions <address>` and `data value <address>` for portfolio info.
+- Use `clob orders` and `clob trades` to view your order and trade history.
+- Use `clob balance --asset-type collateral` to check USDC balance.
+- Use `clob balance --asset-type conditional --token <id>` to check token balances.
+
+### Wallet management
+- Use `wallet create` to generate a new random wallet (saved to config).
+- Use `wallet import <key>` to import an existing key.
+- Use `wallet show` to display current wallet info.
+- Use `wallet reset` to delete config (prompts confirmation; `--force` to skip).
+
+### On-chain operations
+- Use `approve check` to view current contract approvals (read-only).
+- Use `approve set` to approve all contracts (sends 6 on-chain txns, needs MATIC).
+- Use `ctf split --condition <id> --amount 10` to split USDC into YES/NO tokens.
+- Use `ctf merge --condition <id> --amount 10` to merge tokens back to USDC.
+- Use `ctf redeem --condition <id>` to redeem winning tokens after resolution.
+- `--amount` is in USDC (e.g., `10` = $10). On-chain operations require MATIC for gas on Polygon.
+
+### Scripting with JSON output
+- Use `-o json` for machine-readable output: `polymarket -o json markets list --limit 100 | jq '.[].question'`.
+- Errors in JSON mode print `{"error": "..."}` to stdout with non-zero exit code.
+- Table mode prints `Error: ...` to stderr.
+
+## Configuration
+
+Config file: `~/.config/polymarket/config.json`
+
+```json
+{
+  "private_key": "0x...",
+  "chain_id": 137,
+  "signature_type": "proxy"
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| private_key | Ethereum private key (hex with 0x prefix) |
+| chain_id | 137 (Polygon mainnet) |
+| signature_type | `proxy` (default), `eoa`, or `gnosis-safe` |
+
+Override signature type per-command with `--signature-type` or via `POLYMARKET_SIGNATURE_TYPE` env var.
+
+## Reference
+
+Read `references/commands.md` for the full command and flag reference.

.agents/skills/polymarket-cli/references/commands.md

@@ -0,0 +1,156 @@
+# polymarket-cli command reference
+
+## Global flags
+- `-h, --help` — show help
+- `--version` — print version
+- `-o, --output <table|json>` — output format (default: table)
+- `--private-key <key>` — private key for signing
+- `--signature-type <proxy|eoa|gnosis-safe>` — override signature type
+
+## Environment variables
+- `POLYMARKET_PRIVATE_KEY` — private key (checked if no flag provided)
+- `POLYMARKET_SIGNATURE_TYPE` — override signature type
+
+## Commands
+
+### markets
+- `markets list [--limit N] [--offset N] [--order <field>] [--ascending] [--active true|false] [--closed true|false]` — list markets with filters
+- `markets get <id|slug>` — get a single market by ID or slug
+- `markets search "<query>" [--limit N]` — search markets by keyword
+- `markets tags <market_id>` — get tags for a market
+
+### events
+- `events list [--limit N] [--offset N] [--order <field>] [--ascending] [--active true|false] [--closed true|false] [--tag <tag>]` — list events
+- `events get <event_id>` — get a single event
+- `events tags <event_id>` — get tags for an event
+
+### tags
+- `tags list` — list all tags
+- `tags get <tag>` — get tag details
+- `tags related <tag>` — related markets
+- `tags related-tags <tag>` — related tags
+
+### series
+- `series list [--limit N]` — list recurring event series
+- `series get <series_id>` — get a single series
+
+### comments
+- `comments list --entity-type <event|market> --entity-id <id>` — list comments
+- `comments get <comment_id>` — get a single comment
+- `comments by-user <address>` — comments by a user
+
+### profiles
+- `profiles get <address>` — get a public profile
+
+### sports
+- `sports list` — list sports
+- `sports market-types` — list market types
+- `sports teams --league <league> [--limit N]` — list teams by league
+
+### clob (read-only, no wallet needed)
+- `clob ok` — API health check
+- `clob price <token_id> --side <buy|sell>` — get price
+- `clob midpoint <token_id>` — get midpoint price
+- `clob spread <token_id>` — get spread
+- `clob batch-prices "<token1>,<token2>" --side <buy|sell>` — batch prices
+- `clob midpoints "<token1>,<token2>"` — batch midpoints
+- `clob spreads "<token1>,<token2>"` — batch spreads
+- `clob book <token_id>` — order book for a token
+- `clob books "<token1>,<token2>"` — batch order books
+- `clob last-trade <token_id>` — last trade price
+- `clob market <condition_id>` — market info by condition ID
+- `clob markets` — list all CLOB markets
+- `clob price-history <token_id> --interval <1m|1h|6h|1d|1w|max> [--fidelity N]` — price history
+- `clob tick-size <token_id>` — tick size
+- `clob fee-rate <token_id>` — fee rate
+- `clob neg-risk <token_id>` — neg-risk status
+- `clob time` — server time
+- `clob geoblock` — geoblock status
+
+### clob (authenticated, wallet required)
+- `clob create-order --token <id> --side <buy|sell> --price <0-1> --size <N> [--type GTC|FOK|GTD|FAK] [--post-only]` — place a limit order
+- `clob market-order --token <id> --side <buy|sell> --amount <N>` — place a market order
+- `clob post-orders --tokens "<t1>,<t2>" --side <buy|sell> --prices "<p1>,<p2>" --sizes "<s1>,<s2>"` — batch orders
+- `clob cancel <order_id>` — cancel a single order
+- `clob cancel-orders "<id1>,<id2>"` — cancel multiple orders
+- `clob cancel-market --market <condition_id>` — cancel all orders for a market
+- `clob cancel-all` — cancel all open orders
+- `clob orders [--market <condition_id>]` — list your orders
+- `clob order <order_id>` — get a single order
+- `clob trades` — list your trades
+- `clob balance --asset-type <collateral|conditional> [--token <id>]` — check balance
+- `clob update-balance --asset-type <collateral>` — refresh balance
+
+### clob rewards & API keys (authenticated)
+- `clob rewards --date <YYYY-MM-DD>` — rewards for a date
+- `clob earnings --date <YYYY-MM-DD>` — earnings for a date
+- `clob earnings-markets --date <YYYY-MM-DD>` — earnings by market
+- `clob reward-percentages` — reward percentages
+- `clob current-rewards` — current reward rates
+- `clob market-reward <condition_id>` — reward for a market
+- `clob order-scoring <order_id>` — check if order is scoring rewards
+- `clob orders-scoring "<id1>,<id2>"` — batch scoring check
+- `clob api-keys` — list API keys
+- `clob create-api-key` — create an API key
+- `clob delete-api-key` — delete an API key
+- `clob account-status` — account status
+- `clob notifications` — list notifications
+- `clob delete-notifications "<id1>,<id2>"` — delete notifications
+
+### data (public, no wallet needed)
+- `data positions <address>` — open positions
+- `data closed-positions <address>` — closed positions
+- `data value <address>` — portfolio value
+- `data traded <address>` — traded status
+- `data trades <address> [--limit N]` — trade history
+- `data activity <address>` — activity feed
+- `data holders <condition_id>` — token holders
+- `data open-interest <condition_id>` — open interest
+- `data volume <event_id>` — event volume
+- `data leaderboard --period <day|week|month|all> --order-by <pnl|volume> [--limit N]` — leaderboard
+- `data builder-leaderboard --period <day|week|month|all>` — builder leaderboard
+- `data builder-volume --period <day|week|month|all>` — builder volume
+
+### approve
+- `approve check [<address>]` — check current approvals (read-only)
+- `approve set` — approve all Polymarket contracts (6 on-chain txns, needs MATIC)
+
+### ctf (on-chain, wallet required)
+- `ctf split --condition <id> --amount <N> [--partition <indices>]` — split USDC into YES/NO tokens
+- `ctf merge --condition <id> --amount <N> [--partition <indices>]` — merge tokens back to USDC
+- `ctf redeem --condition <id>` — redeem winning tokens
+- `ctf redeem-neg-risk --condition <id> --amounts "<a1>,<a2>"` — redeem neg-risk positions
+- `ctf condition-id --oracle <addr> --question <id> --outcomes <N>` — calculate condition ID (read-only)
+- `ctf collection-id --condition <id> --index-set <N>` — calculate collection ID (read-only)
+- `ctf position-id --collection <id>` — calculate position ID (read-only)
+
+### bridge
+- `bridge deposit <address>` — get deposit addresses (EVM, Solana, Bitcoin)
+- `bridge supported-assets` — list supported chains and tokens
+- `bridge status <deposit_address>` — check deposit status
+
+### wallet
+- `wallet create [--force]` — generate new random wallet
+- `wallet import <key>` — import existing private key
+- `wallet address` — print wallet address
+- `wallet show` — full wallet info (address, source, config path)
+- `wallet reset [--force]` — delete config (prompts confirmation)
+
+### other
+- `setup` — guided first-time setup wizard
+- `shell` — interactive REPL (all commands without `polymarket` prefix)
+- `status` — API health check
+- `upgrade` — update to latest version
+
+## Config
+- Config file: `~/.config/polymarket/config.json`
+- Fields: `private_key` (hex with 0x), `chain_id` (137), `signature_type` (proxy|eoa|gnosis-safe)
+- Key precedence: `--private-key` flag > `POLYMARKET_PRIVATE_KEY` env > config file
+
+## Notes
+- Amounts in `ctf` commands are in USDC (e.g., `10` = $10)
+- Default partition for split/merge is binary (`1,2`)
+- On-chain operations require MATIC for gas on Polygon (chain ID 137)
+- Price values for orders are between 0 and 1 (e.g., 0.50 = 50 cents)
+- Token IDs are long numeric strings (e.g., `48331043336612883...`)
+- Condition IDs are hex strings (e.g., `0xABC123...`)

README.md

@@ -467,6 +467,10 @@ if ! result=$(polymarket -o json clob balance --asset-type collateral 2>/dev/nul
 fi
 ```
 
+## Agentic AI Skill
+
+This repository includes a [AI Skill](https://skills.sh/) at `.agents/skills/polymarket-cli/` that enables AI agents to operate the CLI on your behalf. Copy the skill into your project or reference it from your Claude Code configuration to let Claude browse markets, place orders, manage wallets, and interact with Polymarket contracts using natural language.
+
 ## Architecture
 
 ```