KalshiPolymarket US Agent workflows (no trading)
Short answer: A Claude Code skill is a folder with a SKILL.md file: YAML frontmatter (a description that tells Claude when to use it) plus Markdown instructions. Project skills live in .claude/skills/<name>/SKILL.md, and you run one with /name or let Claude load it when relevant. For bot builders, skills are great for repeatable checks, but they're instructions, not enforcement: hard rules belong in hooks, deny rules and code.
SKILL.md: frontmatter between --- lines, then instructions. The directory name (or name field) becomes the /command.~/.claude/skills/<name>/ (all your projects), .claude/skills/<name>/ (this repo, commit it). Older .claude/commands/*.md files still work.description is recommended; Claude uses it to decide when to load the skill. A skill's full body only loads when it's used, so long reference material costs little until then.disable-model-invocation: true means only you can run the skill with /name. The docs suggest it for anything with side effects or timing you want to control.allowed-tools grants tools without asking during that turn; it doesn't restrict anything. Never pre-approve order scripts or broad Bash(*) in a trading repo, and review allowed-tools in skills you didn't write..claude/skills/; Codex reads .agents/skills/.Three project skills in .claude/skills/: /docs-check (verify every endpoint the bot uses against the official docs), /paper-review (summarize a paper-trading log without ever touching keys) and /preflight-live (a go-live checklist only you can trigger, which never places orders).
Claude Code users building Kalshi or Polymarket US bots who keep pasting the same "check the docs" and "review my paper log" instructions.
Not for: Skills that place trades, read keys or decide what to trade. None of these do.
Each skill is one folder with one SKILL.md. Copy them as-is, or paste the prompt below and let Claude Code create them.
1. .claude/skills/docs-check/SKILL.md: Claude can load this on its own whenever it's about to write API code.
---
name: docs-check
description: Verify every Kalshi or Polymarket US endpoint, field and auth step in this repo against the official docs. Use before writing or changing API client code, or when a request fails with 400/401/404.
---
Check the API usage in this repo against the official docs only:
- Kalshi: https://docs.kalshi.com
- Polymarket US: https://docs.polymarket.us
1. List every endpoint, HTTP method, request field and auth header the code uses.
2. For each one, find the page in the official docs that documents it.
3. Report a table: endpoint | file:line | documented? | doc URL | mismatch.
4. Flag anything undocumented or deprecated. Do not invent endpoints.
5. Don't edit code in this skill. Suggest fixes; I'll ask for them.
Never open .env, *.pem or *.key files.
2. .claude/skills/paper-review/SKILL.md: reads the bot's own paper log (no keys involved).
---
name: paper-review
description: Summarize the bot's paper-trading or demo log in logs/. Use when asked how the bot did, what it traded, or whether it broke a limit.
---
Read the newest file in logs/ (JSON lines written by the bot). Report:
- simulated orders, fills and rejections, by market
- every limit check that fired, and every kill-switch event
- simulated P&L after fees, with the caveat that paper fills are optimistic
- anything that looks like a bug (repeated orders, missing exits)
Don't recommend trades or say the strategy "works". Paper and demo results
don't predict live results. Never open .env, *.pem or *.key files.
3. .claude/skills/preflight-live/SKILL.md: only you can trigger it, and it never starts the bot.
---
name: preflight-live
description: Pre-live checklist for this bot. Checks only; never starts trading.
disable-model-invocation: true
---
Go through this checklist and report PASS/FAIL with evidence for each item.
Do not run the bot, place orders, or change any file.
1. Live mode needs both a --live flag and a typed confirmation in code.
2. limits.json has max order size, max exposure and max daily loss, and
risk.py enforces each one (show the lines). tests/test_limits.py passes.
3. A KILL file stops new orders (show the check), and cancel-all uses the
venue's official endpoint.
4. .env and key files are gitignored and not tracked (git ls-files).
5. The last paper/demo log covers at least several days with no limit
breaches or unexplained errors.
End with: "Starting live mode is your decision. Run it yourself."
Notice what's not here: no allowed-tools, no ! shell injection, no order scripts. Those are the parts of a skill that can act on their own, so a trading repo should add them only on purpose.
Works in Claude Code, Cursor, Codex/ChatGPT, Grok or any agent that can write files. Paste it into an empty folder. Read what it builds before you run anything.
Create three Claude Code project skills in this bot repo. Follow the
official skills docs at https://code.claude.com/docs/en/skills (SKILL.md
with YAML frontmatter between --- lines, then Markdown instructions).
1. .claude/skills/docs-check/SKILL.md
description: verify every Kalshi / Polymarket US endpoint, field and auth
step in this repo against https://docs.kalshi.com and
https://docs.polymarket.us; use before writing API code or on 4xx errors.
Body: list endpoints with file:line, find the doc page for each, report a
table with mismatches, never invent endpoints, don't edit code.
2. .claude/skills/paper-review/SKILL.md
description: summarize the newest paper/demo log in logs/.
Body: orders, fills, rejections, limit checks, kill-switch events, P&L
after fees with an "optimistic paper fills" caveat. No trade advice.
3. .claude/skills/preflight-live/SKILL.md with
disable-model-invocation: true
Body: PASS/FAIL checklist (live gate, limits enforced in code with
tests passing, kill file + cancel-all, secrets gitignored, several days
of clean paper logs). Never run the bot or change files.
Rules for all three: no allowed-tools, no !`command` injection, never open
.env, *.pem or *.key files. Show me the files when done.claude..claude/skills/./ and look for docs-check, paper-review and preflight-live. Claude Code watches skill folders, so edits apply without a restart./docs-check before your next API change. It's the fastest way to catch an outdated endpoint, such as Kalshi's move to Create Order V2 at POST /portfolio/events/orders./paper-review after a day of paper or demo trading./preflight-live only when you're considering live mode. Because of disable-model-invocation: true, Claude can't start it on its own..claude/skills/ so the skills travel with the repo. If you also use Codex, symlink .agents/skills to .claude/skills (Claude Code follows symlinked skill folders).None of these skills trade. /paper-review is built for the paper and demo phase: it reads the log your bot already writes, so you get a consistent summary every time without giving the agent keys or account access.
Treat its P&L line with suspicion. Paper fills assume you got the price you saw, and Kalshi notes demo markets may not behave like real ones. The skill is told to say so every time.
Tick every box before the bot touches real money. The full rules file, .gitignore and pre-commit hook are in the Safety Pack.
.env and *.pem are in .gitignore, and your AI tool is blocked from reading them (see the Safety Pack).touch KILL) stops new orders immediately, and a second command cancels every resting order through the venue's cancel-all endpoint.--live flag and a typed confirmation, and you only flip it after days of clean paper logs.allowed-tools pre-approves tools for the turn that invokes a skill, even in folders you haven't trusted. Read the frontmatter of any skill you didn't write before running Claude Code in that repo.! lines in a skill run shell commands before Claude sees the skill. Never inject commands that could print secrets or place orders.disable-model-invocation: true, so only you can trigger it.Endpoints and rules were checked against these pages on Oct 19, 2026. APIs change, so if something here disagrees with the official docs, trust the docs and tell us.
Reusable instruction packages. Each is a folder with a SKILL.md file. Claude adds the skill's description to its context and loads the full instructions when the skill is relevant, or when you type /skill-name.
Personal skills go in ~/.claude/skills/<name>/SKILL.md and work in all your projects. Project skills go in .claude/skills/<name>/SKILL.md and can be committed to the repo. Plugins and managed settings can also ship skills.
CLAUDE.md loads every session, so it's for short, always-true facts. A skill's body loads only when it's used, so it suits longer procedures like a docs check or a pre-live checklist.
A skill tells Claude what to do. A hook is a script Claude Code runs every time an event happens, and it can block a tool call. Use skills for workflows and hooks for rules that must never be broken.
Skills follow the open Agent Skills standard. Cursor loads skills from .claude/skills/ and .agents/skills/, Grok Build reads .claude/skills/, and Codex reads .agents/skills/. Claude Code-only frontmatter fields may be ignored elsewhere.
It could if you wrote one that runs order scripts, which is exactly why we don't. Keep order placement in your bot's code behind its own live gate and limits, not in an AI skill.
One new build recipe, one safety tip, and API changes worth knowing about. Free. No picks, ever.
A copy-paste AI prompt and step-by-step guide to the Polymarket US API: public market data with no key, then authenticated reads. Includes the international Gamma API, read-only, with a geoblock check.
Step-by-step: use Claude Code to build a Polymarket US trading bot that runs in paper mode by default, with a local paper ledger, order preview, hard position limits and a kill switch.
Get started with the Kalshi API using an AI coding tool: public market data with no key, then RSA-PSS or Ed25519 signed requests against the Kalshi demo environment. Endpoints checked against the official docs.