# Backtesting Skill

> Use when a user wants reproducible ziplime backtests from a constrained JSON schema, with optional Yahoo ingestion and optional grid search, in any CLI agent environment.

- **Type:** Skill
- **Install:** `agentstack add skill-garroshub-backtesting-skill-backtesting-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [garroshub](https://agentstack.voostack.com/s/garroshub)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [garroshub](https://github.com/garroshub)
- **Source:** https://github.com/garroshub/backtesting-skill

## Install

```sh
agentstack add skill-garroshub-backtesting-skill-backtesting-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Backtesting Skill

## Overview
Run ziplime backtests from deterministic templates and a constrained JSON schema.
Map the user strategy into schema fields, run the script, and report results in one standard format.

## Workflow
1. Identify whether the user request maps to a supported template:
   - `oversold_bounce_long_only`
   - `sma_crossover_long_only`
   - `trend_dip_buy_long_only`
2. Build a schema JSON using `references/schema.md`.
3. Run the backtest script:
    - `python scripts/run_backtest_from_schema.py --schema `
4. If bundle is missing and user allows Yahoo ingestion, run with:
   - `python scripts/run_backtest_from_schema.py --schema  --ingest-if-missing`
5. If the user asks for OOS checks, enable `validation_split` in schema and report train/test results explicitly.
6. Return concise results using the global output standard (all templates):
      - Core metrics (`total_return`, `sharpe`, `max_drawdown`, `alpha`, `beta`, `algo_volatility`)
      - Extended performance metrics (`Performance`, `Win Days`, `Sharpe`, `Avg. Drawdown`, `Beta`, `Avg. Drawdown Days`, `Alpha`, `Volatility`, `Recovery Factor`, `Profit Factor`, `Calmar`)
      - Trade summary (`trade_count`, `win_rate`, `avg_hold_days`, `avg_trade_return`, `expectancy_return`, `best_trade_return`, `worst_trade_return`)
      - Capacity diagnostics (`avg_daily_turnover`, `annualized_turnover`, `participation_vs_adv_floor`, `participation_risk`)
      - Risk attribution (`corr_with_benchmark`, up/down beta, up/down capture, rolling risk endpoints)
      - Stability diagnostics for grid runs (`stability_diagnostics`)
      - Final equity
     - Chosen params or top grid-search params
    - Practical tradability assessment (required, brief):
      - Future-leakage check (signal timestamp vs execution semantics)
      - Slippage and commission assumptions, and likely live impact direction
      - Overfitting risk comment (grid size, parameter concentration, need for OOS/walk-forward)
      - Capacity/liquidity note (turnover sensitivity and instrument suitability)

## Global Output Standard (All Runs)
- Apply this output contract to every backtest result, regardless of template or symbol.
- Always include: core metrics, extended metrics, final equity, chosen params/top grid params.
- Always include a brief practical tradability assessment with all 4 checks:
  - future leakage / execution semantics
  - slippage + commission realism
  - overfitting risk
  - capacity/liquidity constraints
- Keep grid search defaults small and fast; only run exhaustive grids when explicitly requested.

## Template Mapping Rules
- If user asks for waterfall/panic-reversal mean reversion and long-only, use `oversold_bounce_long_only`.
- If user asks for moving-average cross long-only, use `sma_crossover_long_only`.
- If user asks for trend-dip long-only with MA regime filter, use `trend_dip_buy_long_only`.
- If request cannot map safely to supported templates, ask for a template-constrained restatement.

## Execution Notes
- Keep `max_leverage=1.0` and no short orders.
- Prefer existing bundles. Only ingest when explicitly requested or enabled.
- Use the same frequency for bundle load and `emission_rate`.
- Use out-of-sample checks by date split when user requests robustness.
- Default to quick, reasonable grid sizes; run exhaustive grids only when explicitly requested.
- Use `execution` schema fields when the user asks to tune slippage, commission, or fill behavior.
- Use `data.symbols` for multi-symbol runs on `sma_crossover_long_only` and `trend_dip_buy_long_only`.
- Use `max_positions`, `rank_metric`, and `rebalance_rule` for lightweight portfolio construction controls.
- Keep runtime `data.source` on `bundle`; treat other data sources as reserved interface checks unless adapter support is added.
- Use `live_data` fields only as reserved interface validation (for example `ibkr`), not for live order execution in this runner.

## Commands
- Single run:
  - `python scripts/run_backtest_from_schema.py --schema schema.json`
- Grid search:
  - set `"grid_search": {"enabled": true, ...}` in schema, then run the same command.
- Optional ingestion path:
  - `python scripts/run_backtest_from_schema.py --schema schema.json --ingest-if-missing`
- Validation-only (no ziplime runtime required):
  - `python scripts/run_backtest_from_schema.py --schema schema.json --validate-only`

## Common Mistakes
- Bundle frequency mismatch (`5m` bundle but daily emission or inverse).
- Running intraday templates against daily-only bundles.
- Expecting Yahoo minute data to cover very long history windows.
- Adding unconstrained custom logic instead of using schema parameters.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [garroshub](https://github.com/garroshub)
- **Source:** [garroshub/backtesting-skill](https://github.com/garroshub/backtesting-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-garroshub-backtesting-skill-backtesting-skill
- Seller: https://agentstack.voostack.com/s/garroshub
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.