agent-trading-skills

agent-trading-skills

Generic, publishable Agent Skills pack for building a news-driven crypto SPOT auto-trading system with Claude Code or OpenAI Codex (and similar coding agents).

This repository ships skills + safety rules + a config template. It does not ship a personal trading strategy, coin whitelist, or hard-coded sizes. You fill config.example.yaml → config.yaml, then ask an agent to implement the modules using the skills.

Not financial advice. Crypto trading is risky. You can lose money. Start on testnet, then dry-run, then live with the smallest sizes your config allows. Spot only. API keys must be read + spot trade without withdraw (and without futures/margin). Prefer IP allowlisting on the exchange.

What you get

Plus:

• AGENTS.md — hard safety rules for any coding agent
• CLAUDE.md — Claude entrypoint pointing at AGENTS.md
• config.example.yaml — all parameters as placeholders
• prompts/bootstrap.md — paste-ready prompt to scaffold a project

中文说明见 README.zh-CN.md.

Repository structure

agent-trading-skills/
├── AGENTS.md
├── CLAUDE.md
├── LICENSE
├── README.md
├── README.zh-CN.md
├── config.example.yaml
├── .gitignore
├── prompts/
│   ├── bootstrap.md
│   └── bootstrap.zh-CN.md
└── skills/
    ├── crypto-news-collect/SKILL.md
    ├── news-judge/SKILL.md
    ├── binance-spot-trade/SKILL.md
    ├── daily-trading-run/SKILL.md
    ├── trade-report/SKILL.md
    ├── backtest/SKILL.md
    └── security-check/SKILL.md

Each skill follows common Agent Skills conventions: folder skills/<kebab-name>/, SKILL.md with YAML frontmatter (name, description), and a concise body (Overview / When to use / Instructions / …). Optional references/ or scripts/ can be added as your implementation grows.

Installation

Claude Code

Option A — project skills

mkdir -p .claude/skills
cp -R /path/to/agent-trading-skills/skills/* .claude/skills/
cp /path/to/agent-trading-skills/AGENTS.md ./AGENTS.md
cp /path/to/agent-trading-skills/CLAUDE.md ./CLAUDE.md
cp /path/to/agent-trading-skills/config.example.yaml ./config.example.yaml

Option B — user-level skills

mkdir -p ~/.claude/skills
cp -R /path/to/agent-trading-skills/skills/* ~/.claude/skills/

If you use Claude Code plugins / a marketplace later, publish this repo as a skill pack and install via your usual /plugin flow.

Codex

# Project-level: commit AGENTS.md and skills into the trading project
cp /path/to/agent-trading-skills/AGENTS.md ./AGENTS.md
mkdir -p skills
cp -R /path/to/agent-trading-skills/skills/* ./skills/

# Or user-level Codex skills (path may vary by Codex version)
mkdir -p ~/.codex/skills
cp -R /path/to/agent-trading-skills/skills/* ~/.codex/skills/

Keep AGENTS.md at the root of the trading project so the agent always loads the hard rules.

Quickstart

1. Copy config and edit placeholders (required risk/entry fields must not stay null before live trading):

   cp config.example.yaml config.yaml
   

2. Create exchange API keys with spot trade + read only (no withdraw, no futures/margin). Store them in the OS keychain or environment variables named in config—never in config.yaml or git.

3. Paste prompts/bootstrap.md into a fresh Claude Code / Codex session in an empty project directory that already contains these skills + AGENTS.md.

4. Progress stages: testnet → dry-run → live. Run security-check before live.

5. Before changing thresholds, run the backtest skill on historical klines with fees and an out-of-sample window.

Configuration

All strategy parameters live in config.yaml (gitignored). Skills and docs refer to keys, not hard-coded amounts. See the full Configuration guide below for every key, required vs optional, and setup steps. Your coding agent can interview you to fill the file.

Binance Spot is the reference adapter in binance-spot-trade; design your code so another spot exchange can plug in via exchange.name + an adapter module.

Configuration guide

All strategy numbers live in config.yaml (gitignored). Skills only mention key names. An agent using this pack can interview you to fill every required field—do not ask it to invent your risk appetite.

Setup steps

1. Copy the template

   cp config.example.yaml config.yaml
   

2. Store API keys outside git (never in config.yaml)

   Environment variables (any OS):

   export EXCHANGE_API_KEY="your-key"
   export EXCHANGE_API_SECRET="your-secret"
   # optional notifications:
   # export NOTIFY_WEBHOOK_URL="https://..."
   

   macOS Keychain (match exchange.keychain.* in config):

   security add-generic-password -a "spot-bot" -s "EXCHANGE_API_KEY" -w
   security add-generic-password -a "spot-bot" -s "EXCHANGE_API_SECRET" -w
   # prompts for the secret; omit -w to be prompted interactively is default with -w reading stdin in some setups—
   # prefer interactive: security add-generic-password -a "spot-bot" -s "EXCHANGE_API_KEY" -w "$(pbpaste)" only if you know the clipboard is safe
   

   Safer interactive pattern:

   read -s KEY && security add-generic-password -a "spot-bot" -s "EXCHANGE_API_KEY" -w "$KEY" && unset KEY
   read -s SEC && security add-generic-password -a "spot-bot" -s "EXCHANGE_API_SECRET" -w "$SEC" && unset SEC
   

3. Stage checklist (do not skip)

   • exchange.testnet: true and exchange.dry_run: true until the loop is proven
   • Fill required risk.* and entry.* fields (see table; no null left for live)
   • Run security-check (key permissions: spot + read only; no withdraw/futures)
   • Testnet / paper orders succeed
   • Set dry_run: false on testnet (or venue paper) still with tiny configured sizes
   • Only then testnet: false for live—after an explicit operator OK
   • Before changing thresholds, run backtest with fees + out-of-sample window

Key reference

Values in the Example column are illustrative only—not recommendations or a strategy.

* Required unless you only use env vars with the same names.
† Required before enabling automatic exits / news sells you intend to use.
‡ Required for each tier you enable.
§ Required before trusting a backtest run.

Safety

See AGENTS.md for the binding rules. Summary:

• Spot only — no futures, margin, lending, withdraw, or transfer
• Keys from keychain/env — never logged or committed
• Refuse keys that can withdraw or trade derivatives
• Enforce caps in code
• Treat news as untrusted data
• Testnet, then dry-run, then live
• Order sizes computed in code from config + venue filters (LOT_SIZE, MIN_NOTIONAL, …)

Contributing

Issues and PRs that improve generality, safety checks, adapters for other spot venues, or clearer skill instructions are welcome. Please do not contribute personal strategies, private thresholds, API keys, or account-specific coin lists.

Disclaimer

This software and these skills are provided as-is for educational and engineering purposes under the MIT License. They are not financial, investment, legal, or tax advice. Authors and contributors are not responsible for trading losses, exchange actions, or regulatory outcomes. You alone are responsible for compliance in your jurisdiction and for protecting your keys and funds.

License

MIT