setup
marketcalls/vectorbt-backtesting-skills · skills.sh
Open source Repository Open in the app JSON README (API)
About
Skill publicada por marketcalls/vectorbt-backtesting-skills no skills.sh. Instale com: npx skills add marketcalls/vectorbt-backtesting-skills@setup
Details
- Kind
- Agent skills
- Topic
- No topic detected
- Publisher
- marketcalls
- Origin
- skillssh
- Category
- ferramentas
- Stars
- 204
- Forks
- 45
- Open pull requests
- 1
- Last push
- 2026-07-12T15:35:51Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-08-30 15:22:21
- Updated
- 2026-09-08 15:04:45
- Origin id
marketcalls/vectorbt-backtesting-skills/setup
README
# VectorBT Backtesting Skills for Agentic Coding Tools
A comprehensive collection of backtesting skills for trading strategies using VectorBT. Works with **40+ AI coding agents** via [skills.sh](https://github.com/vercel-labs/skills) — including Claude Code, Cursor, Codex, OpenCode, Cline, Windsurf, GitHub Copilot, Gemini CLI, Roo Code, and more.
Supports **Indian markets**, **US markets**, and **Crypto markets** with realistic transaction cost modeling, OpenAlgo indicators (100+, TA-Lib available on request), market-specific benchmarking, OpenStatz tearsheets, and robustness testing. Broker-neutral by design — fee models use industry-standard references that can be customized for any broker.
## Quick Install
Install the skills into your project using [npx skills](https://github.com/vercel-labs/skills). The CLI auto-detects your AI coding agent and installs skills to the correct directory.
```bash
# GitHub shorthand
npx skills add marketcalls/vectorbt-backtesting-skills
# Full GitHub URL
npx skills add https://github.com/marketcalls/vectorbt-backtesting-skills
```
Install a specific skill only:
```bash
npx skills add marketcalls/vectorbt-backtesting-skills -s backtest
npx skills add marketcalls/vectorbt-backtesting-skills -s optimize
npx skills add marketcalls/vectorbt-backtesting-skills -s vectorbt-expert
npx skills add marketcalls/vectorbt-backtesting-skills -s setup
```
List available skills before installing:
```bash
npx skills add marketcalls/vectorbt-backtesting-skills -l
```
Install globally (available across all projects):
```bash
npx skills add marketcalls/vectorbt-backtesting-skills -g
```
### Supported AI Coding Agents
Skills are installed via [skills.sh](https://github.com/vercel-labs/skills) which supports 40+ agents. Each agent reads skills from its own directory:
| Agent | Skills Directory |
|-------|-----------------|
| Claude Code | `.claude/skills/` |
| Cursor | `.agents/skills/` |
| Codex | `.agents/skills/` |
| OpenCode | `.agents/skills/` |
| Cline | `.agents/skills/` |
| Windsurf | `.agents/skills/` |
| GitHub Copilot | `.agents/skills/` |
| Gemini CLI | `.agents/skills/` |
| Roo Code | `.agents/skills/` |
| + 30 more | Auto-detected by `npx skills` |
The `npx skills add` command detects which agents you have installed and places the skill files in the correct paths automatically.
## Supported Markets
| Market | Data Source | Fee Reference | Default Benchmark |
|--------|------------|---------------|-------------------|
| **India** | OpenAlgo (NSE, BSE, NFO, MCX) | Delivery, Intraday, F&O (4-segment) | NIFTY 50 |
| **US** | yfinance (NYSE, NASDAQ) | Stocks, Options, Futures (per-share + per-contract) | S&P 500 |
| **Crypto** | yfinance / CCXT | Spot, Perpetual Futures (maker/taker) | Bitcoin |
| **Custom** | Any provider via extensible pattern | User-defined | User-defined |
> **Broker-neutral**: Fee models use realistic industry-standard defaults and can be adjusted for any broker by changing the `fees` and `fixed_fees` constants.
## Capabilities
### Skills (User-Invocable Commands)
| Command | What It Does |
|---------|-------------|
| `/setup` | Detects OS, creates venv, installs OpenAlgo + all packages (TA-Lib optional), creates `backtesting/` folders, configures `.env` with API keys |
| `/backtest` | Generates a complete backtest script with signals, market-specific fees, benchmark comparison, plain-language report, OpenStatz tearsheet |
| `/optimize` | Parameter grid search with OpenAlgo ta indicators, tqdm progress bars, Plotly heatmaps, best params vs benchmark |
| `/quick-stats` | Inline code block (no file) — fetch data, run EMA crossover, print compact stats + benchmark alpha |
| `/strategy-compare` | Side-by-side comparison of multiple strategies on same symbol, overlaid equity curves |
### Pre-Built Strategy Templates (12)
| Strategy | Type | Description |
|----------|------|-------------|
| EMA Crossover | Trend | EMA 10/20 crossover |
| RSI | Mean-reversion | RSI(14) oversold/overbought |
| Donchian Channel | Breakout | Channel breakout with shifted levels (no lookahead) |
| Supertrend | Trend | Supertrend with intraday session windows (9:30-15:00, exit 15:15) |
| MACD | Trend + Breakout | MACD zero-line regime + signal-candle breakout |
| SDA2 | Trend | WMA + STDDEV + ATR band system |
| Double Momentum | Momentum | MOM + MOM-of-MOM with next-bar fill |
| Dual Momentum | Rotation | Quarterly ETF rotation (NIFTYBEES vs GOLDBEES) |
| Buy & Hold | Passive | Static multi-asset allocation with FD benchmark |
| RSI Accumulation | Accumulation | Weekly RSI slab-wise buying (5%/10%/20% by RSI level) |
| Walk-Forward | Validation | Rolling train/test optimization with WFE scoring |
| Realistic Costs | Analysis | Same strategy across 5 fee tiers (zero to full delivery) |
### Knowledge Base (20 Rule Files)
| Category | What's Covered |
|----------|---------------|
| **Data** | OpenAlgo (India), yfinance (US/Global), CCXT (Crypto), custom providers, `.env` + `python-dotenv`, CSV loading, resampling |
| **Indicators** | OpenAlgo ta by default - 100+ indicators (EMA, SMA, RSI, MACD, BBands, ATR, ADX, STDDEV, MOM, Supertrend, Donchian, Ichimoku, HMA, KAMA, ALMA, ZLEMA, VWMA, oscillators, statistical, hybrid). TA-Lib only if explicitly requested |
| **Signals** | `ta.exrem()` signal cleaning, `ta.crossover()`, `ta.crossunder()`, `ta.flip()` regime detection |
| **Simulation** | `from_signals`, `from_orders`, `from_holding`, long/short/both directions |
| **Sizing** | Percent, Value, TargetPercent, whole shares (`min_size=1`), futures lot sizes, fractional crypto |
| **Costs** | **India**: 4-segment model (Delivery 0.111%, Intraday 0.0225%, Futures 0.018%, Options 0.098%). **US**: Per-share + per-contract model (Stocks ~0.01%, Options ~0.2%, Futures ~0.001%). **Crypto**: Maker/taker model (Spot 0.1%, Futures 0.02%/0.05%, funding rates). All customizable. |
| **Futures** | SEBI revised lot sizes (Dec 2025): NIFTY=65, BANKNIFTY=30, FINNIFTY=60. US: E-mini/Micro contract specs |
| **Risk** | Stop loss, take profit, trailing stop (`sl_trail`) |
| **Optimization** | Loop-based (OpenAlgo ta / TA-Lib compliant) + broadcasting (vbt.MA exception for parameter sweeps) |
| **Benchmarking** | India: NIFTY 50 via OpenAlgo. US: S&P 500 (`^GSPC`). Crypto: Bitcoin (`BTC-USD`). Strategy vs Benchmark table always produced |
| **Reporting** | Plain-language backtest explanation for normal traders. OpenStatz HTML tearsheets with 30+ metrics, Monte Carlo simulations |
| **Plotting** | Plotly dark theme, candlestick with `xaxis type="category"` (no weekend gaps), VectorBT 7-panel plot pack |
| **Validation** | Walk-forward analysis (WFE ratio), robustness testing (Monte Carlo trade shuffle, noise injection, parameter sensitivity, entry/exit delay, cross-symbol validation) |
| **Safety** | 10 common pitfalls with prevention, checklist before going live |
## Prerequisites
### 1. AI Coding Agent
Install any supported AI coding agent. For example:
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — `npm install -g @anthropic-ai/claude-code`
- [Cursor](https://cursor.com) — Desktop IDE with built-in AI
- [Codex](https://github.com/openai/codex) — `npm install -g @openai/codex`
- [OpenCode](https://github.com/opencode-ai/opencode) — `go install github.com/opencode-ai/opencode@latest`
- [Cline](https://github.com/cline/cline) — VS Code extension
- [Windsurf](https://windsurf.com) — Desktop IDE with AI
- Or any of the [40+ supported agents](https://github.com/vercel-labs/skills)
Then install the skills:
```bash
npx skills add marketcalls/vectorbt-backtesting-skills
```
### 2. Data Source Setup
**Indian Markets** — requires [OpenAlgo](https://github.com/marketcalls/openalgo):
```bash
git clone https://github.com/marketcalls/openalgo.git
cd openalgo
pip install -r requirements.txt
python app.py
```
OpenAlgo runs locally at `http://127.0.0.1:5000`. You need a broker account connected via OpenAlgo and an API key from the dashboard. See [OpenAlgo documentation](https://docs.openalgo.in/).
**US Markets** — no setup needed. Uses yfinance (public Yahoo Finance data).
**Crypto Markets** — no setup needed for public data (yfinance or CCXT). Exchange API keys are optional (only for private endpoints).
### 3. Python Environment Setup
Use the `/setup` skill for automated setup, or manually:
```bash
python -m venv venv
source venv/bin/activate # Linux/Mac
# venv\Scripts\activate # Windows
# Install Python packages (OpenAlgo ta is the default indicator library - no C library needed)
pip install openalgo vectorbt plotly anywidget nbformat pandas numpy yfinance python-dotenv tqdm scipy numba ipywidgets openstatz ccxt
# Optional: only if you want to be able to request TA-Lib explicitly in a backtest
brew install ta-lib # macOS
# sudo apt install libta-lib-dev # Linux
pip install ta-lib
```
### 4. Configure API Keys
```bash
cp .env.sample .env
# Edit .env with your API keys
```
## Usage Examples
### `/setup` - Environment Setup
Detects OS, creates venv, installs dependencies, creates folder structure, and collects API keys into `.env`.
```
/setup
/setup python3.12
```
### `/backtest` - Quick Backtest
Create a complete backtest script with market-specific fees, benchmark comparison, plain-language report, and OpenStatz tearsheet.
```
# Indian Markets
/backtest ema-crossover SBIN NSE D
/backtest rsi RELIANCE NSE D
/backtest supertrend NIFTY NFO 5m
# US Markets
/backtest ema-crossover AAPL
/backtest rsi MSFT
# Crypto Markets
/backtest ema-crossover BTC-USD
```
### `/optimize` - Parameter Optimization
Optimize strategy parameters, generate Plotly heatmaps, and compare best parameters vs benchmark.
```
/optimize ema-crossover SBIN NSE D
/optimize rsi AAPL
```
### `/quick-stats` - Inline Stats
Print key backtest stats with benchmark comparison without creating a file.
```
/quick-stats RELIANCE
/quick-stats AAPL
/quick-stats BTC-USD
```
### `/strategy-compare` - Compare Strategies
Compare multiple strategies side-by-side with benchmark.
```
/strategy-compare RELIANCE ema-crossover rsi donchian
/strategy-compare AAPL ema-crossover rsi macd
```
## Key Features
### Multi-Market Transaction Costs
Realistic fee models for each market, auto-selected based on the asset. All fee constants are configurable — adjust for your broker by changing the `fees` and `fixed_fees` values.
#### Indian Market Fees
| Segment | `fees` | `fixed_fees` |
|---------|--------|-------------|
| Delivery Equity | 0.00111 (0.111%) | Rs 20/order |
| Intraday Equity | 0.000225 (0.0225%) | Rs 20/order |
| F&O Futures | 0.00018 (0.018%) | Rs 20/order |
| F&O Options | 0.00098 (0.098%) | Rs 20/order |
#### US Market Fees
| Segment | `fees` | `fixed_fees` |
|---------|--------|-------------|
| Stocks (Pro/Fixed) | 0.0001 (0.01%) | $1.00/order |
| Stocks (Commission-Free) | 0.00001 (~0.001%) | $0 |
| Options | 0.002 (0.2%) | $0.65/contract |
| E-mini Futures (ES, NQ) | 0.000009 (~0.001%) | $2.25/contract |
| Micro Futures (MES, MNQ) | 0.00002 (~0.002%) | $0.55/contract |
#### Crypto Market Fees
| Segment | `fees` | `fixed_fees` |
|---------|--------|-------------|
| Spot (Base) | 0.001 (0.1%) | $0 |
| Spot (Discounted) | 0.00075 (0.075%) | $0 |
| USDT-M Futures (Taker) | 0.0005 (0.05%) | $0 |
| USDT-M Futures (Maker) | 0.0002 (0.02%) | $0 |
| COIN-M Futures (Taker) | 0.0005 (0.05%) | $0 |
> **Using a different broker?** Simply override the fee constants in your backtest script. The rule files include detailed breakdowns (STT, exchange fees, regulatory fees, clearing fees) so you can recalculate for any broker.
### OpenAlgo ta Indicators (Default)
All strategies use `openalgo.ta` for technical indicators by default - 100+ indicators across trend, momentum, volatility, volume, oscillators, statistical, and hybrid categories. VectorBT built-in indicators are never used.
```python
from openalgo import ta
ema_fast = ta.ema(close, 10)
st_line, st_direction = ta.supertrend(high, low, close, period=10, multiplier=3.0)
entries = ta.exrem(buy_raw.fillna(False), sell_raw.fillna(False))
```
Specialty indicators with no TA-Lib equivalent (Supertrend, Donchian, Ichimoku, HMA, KAMA, ALMA, ZLEMA, VWMA) plus signal utilities (`exrem`, `crossover`, `crossunder`, `flip`) always come from `openalgo.ta`.
### TA-Lib (Opt-In Only)
Only used when the user explicitly asks for "talib"/"TA-Lib" in their request:
```python
import talib as tl
ema_fast = pd.Series(tl.EMA(close.values, timeperiod=10), index=close.index)
```
### Market-Specific Benchmarks
| Market | Default Benchmark | Source |
|--------|-------------------|--------|
| India | NIFTY 50 | OpenAlgo (`NSE_INDEX`) |
| US | S&P 500 | yfinance (`^GSPC` or `SPY`) |
| Crypto | Bitcoin | yfinance (`BTC-USD`) |
Every backtest produces a Strategy vs Benchmark comparison table.
### OpenStatz Tearsheets
A modern interactive tearsheet with 30+ metrics, drawdown analysis, rolling statistics, monthly heatmaps, and Monte Carlo simulations. `ostz.dashboard(...)` renders the same interactive dashboard as `openstatz serve` into a single self-contained offline HTML file - no server, no `[app]` extra, no network. OpenStatz replaces QuantStats project-wide and keeps a numerical-parity contract on its metrics.
```python
import openstatz as ostz # alias as ostz, not os - avoids shadowing the stdlib os module
# dashboard() needs the benchmark as a returns Series (not a ticker string)
benchmark = ostz.providers.download_returns("^NSEI").reindex(pf.returns().index).fillna(0)
ostz.dashboard(pf.returns(), benchmark=benchmark, output="tearsheet.html")
```
### Plain-Language Report Explanation
Every backtest explains results so normal traders can understand:
```
* Total Return: Your strategy made 45.23% while NIFTY 50 made 32.10%
-> BEAT the market by 13.13%
* Max Drawdown: -12.34% - the biggest drop from peak
-> On Rs 10,00,000 capital, worst temporary loss = Rs 1,23,400
* Sharpe Ratio: 1.45 (return per unit of risk, >1 decent, >2 excellent)
```
### Extensible Data Providers
Built-in support for OpenAlgo, yfinance, and CCXT. Add custom providers (Alpaca, Twelve Data, etc.) following the pattern in `data-fetching.md`. All API keys stored in `.env` via `python-dotenv`.
### SEBI Revised Lot Sizes (Effective 31 Dec 2025)
| Index | Lot Size | Exchange |
|-------|----------|----------|
| Nifty 50 | 65 | NFO |
| Nifty Bank | 30 | NFO |
| Nifty Financial Services | 60 | NFO |
| Nifty Midcap Select | 120 | NFO |
| Nifty Next 50 | 25 | NFO |
| BSE Sensex | 20 | BFO |
| BSE Bankex | 30 | BFO |
| BSE Sensex 50 | 70 | BFO |
### Backtesting Folder Structure
Strategy name = folder name. Symbol name = file prefix. Each strategy folder is self-contained.
```
backtesting/
├── ema_crossover/
│ ├── .env
│ ├── SBIN_ema_crossover_backtest.py
│ ├── SBIN_ema_crossover_trades.csv
│ ├── SBIN_tearsheet.html
│ ├── AAPL_ema_crossover_backtest.py
│ └── AAPL_ema_crossover_trades.csv
├── rsi/
│ ├── .env
│ ├── INFY_rsi_backtest.py
│ └── ...
├── supertrend/
│ └── ...
└── custom/
└── ...
```
## Project Structure
```
.
├── .claude/
│ └── skills/
│ ├── setup/ # /setup - Environment setup
│ │ └── SKILL.md
│ ├── backtest/ # /backtest - Quick backtest
│ │ └── SKILL.md
│ ├── optimize/ # /optimize - Parameter optimization
│ │ └── SKILL.md
│ ├── quick-stats/ # /quick-stats - Inline stats
│ │ └── SKILL.md
│ ├── strategy-compare/ # /strategy-compare - Compare strategies
│ │ └── SKILL.md
│ └── vectorbt-expert/ # Knowledge base (auto-loaded)
│ ├── SKILL.md # Main skill (modular reference hub)
│ └── rules/ # 20 modular rule files
│ ├── data-fetching.md
│ ├── simulation-modes.md
│ ├── position-sizing.md
│ ├── indicators-signals.md
│ ├── openalgo-ta-helpers.md
│ ├── stop-loss-take-profit.md
│ ├── parameter-optimization.md
│ ├── performance-analysis.md
│ ├── plotting.md
│ ├── indian-market-costs.md
│ ├── us-market-costs.md
│ ├── crypto-market-costs.md
│ ├── futures-backtesting.md
│ ├── long-short-trading.md
│ ├── csv-data-resampling.md
│ ├── walk-forward.md
│ ├── robustness-testing.md
│ ├── pitfalls.md
│ ├── strategy-catalog.md
│ ├── openstatz-tearsheet.md
│ └── assets/ # Production-ready templates
│ ├── ema_crossover/backtest.py
│ ├── rsi/backtest.py
│ ├── donchian/backtest.py
│ ├── supertrend/backtest.py
│ ├── macd/backtest.py
│ ├── sda2/backtest.py
│ ├── momentum/backtest.py
│ ├── dual_momentum/backtest.py
│ ├── buy_hold/backtest.py
│ ├── rsi_accumulation/backtest.py
│ ├── walk_forward/template.py
│ └── realistic_costs/template.py
├── .env.sample # Environment template (copy to .env)
├── backtesting/ # Generated backtest scripts (per strategy)
│ ├── ema_crossover/
│ ├── rsi/
│ ├── donchian/
│ ├── supertrend/
│ ├── macd/
│ ├── sda2/
│ ├── momentum/
│ ├── dual_momentum/
│ ├── buy_hold/
│ ├── rsi_accumulation/
│ ├── walk_forward/
│ └── custom/
└── README.md
```
## Rule Files Reference
| Rule File | Description |
|-----------|-------------|
| `data-fetching.md` | OpenAlgo (India), yfinance (US), CCXT (Crypto), custom providers, `.env` setup |
| `simulation-modes.md` | from_signals, from_orders, from_holding, direction types |
| `position-sizing.md` | Amount/Value/Percent/TargetPercent sizing, whole shares |
| `indicators-signals.md` | OpenAlgo ta indicator reference (default), TA-Lib opt-in, signal generation |
| `openalgo-ta-helpers.md` | Complete OpenAlgo ta catalog (100+ indicators): exrem, crossover, Supertrend, Donchian, Ichimoku, MAs |
| `stop-loss-take-profit.md` | Fixed SL, TP, trailing stop configurations |
| `parameter-optimization.md` | Broadcasting and loop-based optimization, heatmaps |
| `performance-analysis.md` | Stats, metrics, benchmark comparison, CAGR calculation |
| `plotting.md` | Candlestick (category x-axis), VectorBT plots, custom Plotly |
| `indian-market-costs.md` | Indian market fee model — delivery, intraday, F&O (4-segment) |
| `us-market-costs.md` | US market fee model — stocks, options, futures (per-share + per-contract) |
| `crypto-market-costs.md` | Crypto fee model — spot, perpetual futures, funding rates (maker/taker) |
| `futures-backtesting.md` | SEBI revised lot sizes (Dec 2025), US contract specs, value sizing |
| `long-short-trading.md` | Simultaneous long/short, direction comparison |
| `csv-data-resampling.md` | Loading CSV data, resampling with Indian market alignment |
| `walk-forward.md` | Walk-forward analysis, WFE ratio, rolling optimization |
| `robustness-testing.md` | Monte Carlo, noise test, parameter sensitivity, delay test |
| `pitfalls.md` | 10 common mistakes and checklist before going live |
| `strategy-catalog.md` | All strategy types with code snippets and asset references |
| `openstatz-tearsheet.md` | OpenStatz interactive offline dashboard, 30+ metrics, Monte Carlo (replaces QuantStats) |
## Data Sources
| Source | Use Case | Tickers/Codes | API Key Required |
|--------|----------|---------------|------------------|
| OpenAlgo | Indian markets (primary) | NSE, BSE, NFO, BFO, CDS, MCX, NSE_INDEX, BSE_INDEX | Yes (`OPENALGO_API_KEY`) |
| yfinance | US markets, global, crypto | `AAPL`, `SPY`, `^GSPC`, `^NSEI`, `BTC-USD`, `ETH-USD` | No |
| CCXT | Crypto exchanges | `BTC/USDT`, `ETH/USDT` (higher resolution data) | Optional |
| Custom | Any provider | User-defined | User-defined |
## Configuration
Copy the `.env.sample` and fill in your API keys:
```bash
cp .env.sample .env
```
The `.env` file supports:
```
# Indian Markets (OpenAlgo)
OPENALGO_API_KEY=your_openalgo_api_key_here
OPENALGO_HOST=http://127.0.0.1:5000
# Crypto Markets (CCXT) — Optional
CRYPTO_API_KEY=
CRYPTO_SECRET_KEY=
# Custom Data Providers - add your own keys
# ALPACA_API_KEY=
# TWELVEDATA_API_KEY=
```
US market data via yfinance does not require an API key.
## License
MIT