Skip to content
Get packs

Guide · Agent skill

How to use the Vibe-Trading Finance Toolkit agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The vibe-trading skill gives an AI agent a finance research toolkit: backtesting across 11 market engines, factor and options analysis, market data from about 29 sources, and a trade journal analyzer that looks for rules behind your past trades. This guide explains what the skill does, how to install it, how to ask for things in plain language, and what it needs and sends over the network. It is research tooling and does not place orders by itself.

Vibe-Trading Finance ToolkitHKUDS/Vibe-Trading · MIT

Quick start

  1. 1Install Python 3.11 or newer. Confirm you have Python 3.11 or a later version available on your machine.
  2. 2Install the package. Run pip install vibe-trading-ai to add the runtime and its three commands.
  3. 3Place the skill folder. Unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload it under Settings, Capabilities, Skills in the Claude apps.
  4. 4Add the MCP server. Add the vibe-trading-mcp command to your agent's MCP configuration so its tools are available.
  5. 5Set optional keys. Export TUSHARE_TOKEN or other provider keys only if you need premium data or run_swarm.
  6. 6Make a request. Ask for a backtest, a data pull or a trade journal analysis in plain language, naming the market, symbol and period.

What an agent skill is and what this one lets the agent do

An agent skill is a folder with a SKILL.md file that tells an AI agent when and how to use a set of tools. Once the skill is loaded, the agent can pick up requests that match its description without you naming the tool each time.

The vibe-trading skill covers backtesting (11 engines, including ChinaA, GlobalEquity, Crypto and ChinaFutures), an Alpha Zoo of 478 pre-built alphas, options pricing, 90 finance skills, 30 multi-agent swarm teams, and a Shadow Account loop. The Shadow Account loop takes a CSV broker export, profiles your trading behaviour, extracts rules from your profitable trades, backtests those rules, and renders an HTML or PDF report.

Install the Vibe-Trading skill with the ZIP or the Claude apps

Option 1: download the skill ZIP from this page and unzip it into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder.

Option 2: in the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP.

The skill's runtime is a Python package. You need Python 3.11 or newer, then install the pip package named vibe-trading-ai.

  • Requires Python 3.11 or newer
  • Pip package: vibe-trading-ai
pip install vibe-trading-ai

Connect the MCP server to your agent

After installing, the package provides three commands. vibe-trading starts the interactive CLI or TUI, vibe-trading serve launches the FastAPI web server, and vibe-trading-mcp starts the MCP server used by Claude Desktop, OpenClaw, Cursor and similar clients.

To connect an MCP-compatible agent, add the server to its MCP configuration as shown below.

  • vibe-trading: interactive CLI / TUI
  • vibe-trading serve: FastAPI web server
  • vibe-trading-mcp: MCP server for MCP-compatible agents
{"mcpServers": {"vibe-trading": {"command": "vibe-trading-mcp"}}}

Ask for things in plain language

You do not need to name internal tools. The skill's description covers backtesting, factor analysis, options pricing, market data, trade journals and shadow accounts, so requests that describe a finance task should trigger it. Be specific about the market, the symbol and the period.

The Shadow Account flow runs in five steps: analyze_trade_journal profiles your behaviour, extract_shadow_strategy distills 3-5 if-then rules from profitable roundtrips, run_shadow_backtest tests them and compares delta-PnL with your realised trades, render_shadow_report produces the HTML or PDF report, and scan_shadow_signals lists today's matching symbols for research.

  • Analyse my broker CSV export and tell me my holding period, win rate and whether I chase breakouts.
  • Extract the rules behind my profitable trades and backtest them on A-shares and US stocks.
  • Backtest a simple moving-average crossover on HK equities over the last several years and summarise the drawdown.
  • List today's symbols that match my shadow account's entry pattern. This is research only.
  • Render an HTML report from my last shadow backtest.

Know what it needs and what it sends over the network

Core research tools work with no API keys for HK, US, Canada and crypto data. China A-share data works without a key through free sources, with TUSHARE_TOKEN optional for premium quality. Premium US providers (FINNHUB_API_KEY, ALPHAVANTAGE_API_KEY, TIINGO_API_KEY, FMP_API_KEY) are optional and fall back to free sources if absent. The run_swarm tool needs OPENAI_API_KEY and LANGCHAIN_MODEL_NAME. IBKR tools need a local TWS or IB Gateway session.

Safety: this skill runs scripts and uses the network. It fetches market data from third-party providers, and some features send requests to an LLM API. Treat your trade journal and any keys as data you are sending to those services. Keys belong in environment variables, not in files you share.

  • Works with no key: HK, US, Canada and crypto data; A-shares via free sources
  • Optional: TUSHARE_TOKEN, OPENAI_API_KEY, LANGCHAIN_MODEL_NAME, FINNHUB / ALPHAVANTAGE / TIINGO / FMP keys
  • Broker-specific: LONGBRIDGE keys, or a local TWS / IB Gateway session for IBKR
  • Runs scripts: yes. Uses network: yes

Read backtest results with care

A backtest shows how a rule would have performed on historical data. It does not predict future returns, and results can change with the data source, costs and the period chosen. Market-specific engines model local rules, such as T+1 delivery in India and long-only trading for Korea and Vietnam, so check the engine that matches your market.

Use the benchmark comparison panel and the diagnose output to test whether a result holds up across periods before you rely on it.

  • Test several time periods, not just the best one
  • Check the cost and slippage settings for your market
  • Treat output as research, not financial advice

What people use it for

  • Test a moving-average or momentum rule on A-shares, HK, US or crypto history across 11 engines.
  • Analyse a broker CSV export for holding period, win rate, disposition effect and overtrading.
  • Compare alphas from the Alpha Zoo on a universe such as CSI 300 or S&P 500.
  • Price options and review factor exposures for a research note.
  • Produce an HTML or PDF report from a shadow backtest.

Frequently asked questions

Is the Vibe-Trading skill free?

The skill is published under the MIT licence. Many data sources need no API key, but some premium providers and the run_swarm LLM feature need keys or accounts from those providers. Check each provider's terms for its own costs.

What do I need to install vibe-trading?

You need Python 3.11 or newer and the pip package vibe-trading-ai. For the agent to use it, add the vibe-trading-mcp server to your MCP configuration or place the skill folder in your skills directory.

How do I install the Vibe-Trading skill in Claude?

Download the skill ZIP and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, Capabilities, Skills.

Does the skill place trades for me?

No. It is research tooling. The Shadow Account scanner lists symbols that match rules for research, and the skill does not place orders by itself.

Which market data sources does it use?

It lists 29 sources, including yfinance, stooq, yahoo, OKX, CCXT, AKShare, baostock, tushare, pykrx, Longbridge and Futu. Many work with no key, and it falls back to other sources when one is unavailable.

Can I use it without sending data to third parties?

Not fully. The skill fetches market data from the internet, and some features send requests to an LLM API. If you cannot allow that, do not use the features that call those services.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you are a quantitative researcher testing strategies across several markets, or a retail trader who wants a structured review of your own trade history, and you are comfortable with Python tooling and network data calls. Pick something else if you want guaranteed returns, financial advice, or a tool that places trades for you.

Download the skill