--- name: alpaca-trading-backtest description: > Execute deterministic, reproducible historical backtests from a start date, end date, and strategy concept using the Alpaca CLI plus agent-written workspace code. Use when the user wants to backtest a strategy, simulate historical trades, or return trades, diagnostics, and reproducibility artifacts. ---

# Trading API Backtesting

Use this skill when you want your AI agent to run a specific historical backtest with the Alpaca CLI and local workspace code. This version is optimized for run-specific execution: your agent writes the minimum readable code needed for the confirmed strategy, stores the exact artifacts, and reports the results back to you.

This skill is written for you, the person invoking it through your AI agent. **You** means the trader, developer, researcher, or operator asking your agent to run the backtest. Your agent should address you directly, restate assumptions clearly, and make every interpretation choice visible.

```text strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report ```

It is not a promise that a strategy will work in live markets. It is a reproducible research workflow.

## Required disclosures

Every report, `notes.md`, `report.md`, notebook, dashboard, or exported result should include:

> **Important disclosure** > This backtest is a hypothetical historical simulation and does not represent actual trading performance. Backtested results do not guarantee future results. Results depend on market-data quality, data feed selection, corporate-action handling, fees, slippage, liquidity, taxes, execution assumptions, and implementation details. This material is for research and educational purposes only and is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investments involve risk and may lose value. Review Alpaca's disclosures and agreements at [alpaca.markets/disclosures](https://alpaca.markets/disclosures).

When paper trading appears in the workflow, add:

> Paper trading is a simulated environment. It does not involve real money or actual securities transactions. Paper results may differ from live trading because of fill assumptions, market impact, liquidity, latency, data differences, order handling, fees, and other market conditions.

When the backtest models Alpaca securities trading-activity fees, `notes.md`, `summary.json`, and `report.md` should link to the Alpaca Brokerage Fee Schedule PDF:

```text https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf ```

Record the PDF revision date, extraction timestamp, modeled fee categories, and any fee items intentionally excluded.

## CLI prerequisites

### Alpaca CLI

Your agent should use the Alpaca CLI for market-data access.

Check whether it is installed:

```bash alpaca version ```

Install with Go when needed:

```bash go install github.com/alpacahq/cli/cmd/alpaca@latest ```

On macOS or Linux with Homebrew:

```bash brew install alpacahq/tap/cli ```

Make sure the binary directory is on `PATH`, commonly `~/go/bin` for Go installs.

### Local execution permissions

Alpaca CLI commands should run in your local workspace where your Alpaca profile, environment variables, network access, and saved artifacts are available. Some agent runtimes express this as:

```text required_permissions: ["all"] ```

Use the equivalent permission model in your agent environment so the CLI can access local auth/config and write run artifacts.

### Connectivity and authentication check

Before any backtest run, verify the CLI and credentials:

```bash alpaca doctor ```

If authentication fails, your agent should stop the run and show you the available login/help command:

```bash alpaca profile login --help ```

For interactive paper setup:

```bash alpaca profile login ```

For API-key setup:

```bash alpaca profile login --api-key ```

For automation, environment variables are preferred because secrets do not need to be written into generated code:

```bash export ALPACA_API_KEY=PK... export ALPACA_SECRET_KEY=... export ALPACA_QUIET=1 ```

Your agent should never print your secret key, commit it to files, include it in reports, or pass it in a way that exposes it to shell history.

### Machine-readable output

Use `--quiet` for commands whose output will be parsed by code:

```bash alpaca account get --quiet alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet ```

Use installed CLI help and schemas as the source of truth for flags and response fields:

```bash alpaca --help-all alpaca data bars --help alpaca data bars --schema alpaca data quotes --schema ```

Because the CLI is generated from API specifications and may evolve, your agent should prefer current `--help`, `--schema`, and `alpaca doctor` output over stale examples.

## Required workflow

Your agent should follow this workflow:

1. Gather required inputs: start date, end date, strategy concept or strategy file. 2. Gather or infer the rest: asset class, symbols or universe, timeframe, initial cash, position sizing, feed, adjustment mode, execution assumptions, benchmark. 3. Work through [run considerations](#run-considerations-checklist): order simulation, indicators, dividends, splits, fees, slippage, spread, market hours, calendar handling, and validation. 4. Translate your freeform idea into precise mathematical rules. 5. Present the formalized interpretation to you before writing code unless your request was already mathematically precise. 6. Check the workspace for reusable data, prior runs, and existing utilities. 7. Create a self-contained run folder. 8. Write `notes.md`, `strategy_spec.json`, `config.json`, and a readable run-specific script. 9. Fetch historical data through the Alpaca CLI, save raw CLI outputs, filter to the chosen market hours, and compute data fingerprints. 10. Run the local simulation. 11. Write artifacts. 12. Return the Teaching Five, first/last trade, assumptions, caveats, data fingerprint, and artifact paths.

## Workspace awareness

Before generating new code or fetching data, your agent should inspect the workspace.

### Data reuse

Look for prior raw data files or cached normalized data that match:

```text symbol asset class feed adjustment mode timeframe start/end range calendar filter regular-hours or extended-hours setting ```

Reuse data only when the data fingerprint matches. If fingerprints differ, your agent should treat the runs as using different input data.

### Run lineage

If this run is a variant of a prior run, `notes.md` should say what changed:

```text changed RSI threshold from 30/70 to 25/75 changed fill model from next_open bar proxy to quote-aware fill changed slippage from 5 bps to 10 bps extended date range from 2020-2024 to 2018-2025 ```

### Existing code

If the workspace already has a backtest engine or shared utility that matches the strategy requirements, your agent may reuse it. Otherwise, the default is a single readable `run.py` in the run folder.

## Run folder and artifact contract

Artifact paths in this skill use `raw/` and `normalized/` as canonical names.

Every run should create a folder like:

```text runs/YYYY-MM-DD_symbol_strategy_timeframe/ notes.md strategy_spec.json config.json run.py requirements.txt or pyproject.toml when needed raw/ bars_SYMBOL.json quotes_SYMBOL.json trades_SYMBOL.json calendar.json corporate_actions.json normalized/ bars_SYMBOL.csv quotes_SYMBOL.csv summary.json report.md trades.csv round_trips.csv equity.csv benchmark_equity.csv data_fingerprint.json warnings.json fee_source.json ```

### `notes.md`

`notes.md` should include your original request, confirmed strategy interpretation, every inferred/defaulted assumption, indicator definitions, fill model, fee model, data feed and adjustment mode, dividend and split treatment, benchmark definitions, calendar and market-hours handling, warnings and caveats, and Alpaca disclosure and fee schedule links.

### Other artifacts

See [reference.md](reference.md) for `summary.json`, `strategy_spec.json`, `data_fingerprint.json`, and `fee_source.json` schemas.

## Code generation rules

For run-specific CLI backtests, your agent should generate a script, not a reusable framework. A single-file `run.py` is the default.

Use readable code:

```python fill_price = bar_open * (1 + friction_pct) ```

instead of compressed expressions that make the artifact hard to audit.

The generated code should:

- read raw or normalized files from the run folder; - implement the confirmed strategy exactly; - implement the chosen indicator definitions exactly (see [Indicator formulas](reference.md#indicator-formulas)); - keep signal timing separate from fill timing; - compute fees, slippage, spread, and settlement according to the confirmed assumptions; - produce all required artifacts; - include deterministic sorting and timezone handling; - avoid hidden network calls after data fetch unless explicitly documented.

Use Python 3 by default. Prefer the standard library plus pandas/numpy when available. Add dependencies only when they materially improve correctness or readability.

## Strategy translation

Your agent should formalize your idea before code generation.

Every rule should specify: data field, trigger, inclusive/exclusive bounds, indicator variant and parameters, warmup behavior, position sizing and rounding, cash handling, order type, fill model, and benchmark.

Example confirmation:

```text I interpreted your strategy as: - Symbol: SPY - Timeframe: 1Day - Data: Alpaca CLI bars, feed=sip, adjustment=split - Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes - Entry: fast SMA crosses above slow SMA - Exit: fast SMA crosses below slow SMA - Signal timing: completed bar close - Fill timing: next trading day's open - Fill model: next_open bar proxy with 5 bps slippage unless quotes are available - Sizing: invest 100% of available cash, fractional shares allowed when supported - Benchmark: SPY buy-and-hold with same assumptions ```

After confirmation, code should match the confirmed interpretation.

## Fill models

Use these model names in confirmations and `notes.md`. Implementation detail is in [Fill model rules](reference.md#fill-model-rules).

- **`next_open`** (default): signal on bar T close; fill on bar T+1 open or quote at T+1 open timestamp. - **`time_based`**: fill at a confirmed time of day; quote bid/ask when available. - **`same_bar`**: only when explicitly requested; document look-ahead risk in `notes.md` and the report. - **Limit and stop orders**: OHLC-bar eligibility rules apply; use conservative intrabar conflict policy when stop and target both touch the same bar.

## Report format

`report.md` should lead with **Performance vs Benchmarks**:

```markdown | | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity | |---|---:|---:|---:|---:|---:| | **Strategy** | ...% | ...% | ...% | ... | $... | | Benchmark | ...% | ...% | ...% | ... | $... | ```

After the table, include strategy configuration, symbols/timeframe/feed/adjustment, fill model and friction, first and last trade, detailed metrics, benchmark explanation, assumptions, data fingerprint, caveats, and the disclosure block.

Metric definitions are in [reference.md](reference.md#metric-formulas).

## In-chat response standard

Lead with the **Teaching Five**:

1. total return versus benchmark; 2. max drawdown; 3. number of trades; 4. win rate; 5. Sharpe ratio versus benchmark.

Then include: annualized return, profit factor, fees paid, first trade, last trade, assumptions made, data fingerprint summary, artifact paths, and most important caveats.

If no trades occurred, say that directly and explain whether this was due to warmup, no signal, insufficient

--- name: alpaca-trading-backtest description: > Execute deterministic, reproducible historical backtests from a start date, end date, and strategy concept using the Alpaca CLI plus agent-written workspace code. Use when the user wants to backtest a strategy, simulate historical trades, or return trades, diagnostics, and reproducibility artifacts. ---

# Trading API Backtesting

Use this skill when you want your AI agent to run a specific historical backtest with the Alpaca CLI and local workspace code. This version is optimized for run-specific execution: your agent writes the minimum readable code needed for the confirmed strategy, stores the exact artifacts, and reports the results back to you.

This skill is written for you, the person invoking it through your AI agent. **You** means the trader, developer, researcher, or operator asking your agent to run the backtest. Your agent should address you directly, restate assumptions clearly, and make every interpretation choice visible.

```text strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report ```

It is not a promise that a strategy will work in live markets. It is a reproducible research workflow.

## Required disclosures

Every report, `notes.md`, `report.md`, notebook, dashboard, or exported result should include:

> **Important disclosure** > This backtest is a hypothetical historical simulation and does not represent actual trading performance. Backtested results do not guarantee future results. Results depend on market-data quality, data feed selection, corporate-action handling, fees, slippage, liquidity, taxes, execution assumptions, and implementation details. This material is for research and educational purposes only and is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investments involve risk and may lose value. Review Alpaca's disclosures and agreements at [alpaca.markets/disclosures](https://alpaca.markets/disclosures).

When paper trading appears in the workflow, add:

> Paper trading is a simulated environment. It does not involve real money or actual securities transactions. Paper results may differ from live trading because of fill assumptions, market impact, liquidity, latency, data differences, order handling, fees, and other market conditions.

When the backtest models Alpaca securities trading-activity fees, `notes.md`, `summary.json`, and `report.md` should link to the Alpaca Brokerage Fee Schedule PDF:

```text https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf ```

Record the PDF revision date, extraction timestamp, modeled fee categories, and any fee items intentionally excluded.

## CLI prerequisites

### Alpaca CLI

Your agent should use the Alpaca CLI for market-data access.

Check whether it is installed:

```bash alpaca version ```

Install with Go when needed:

```bash go install github.com/alpacahq/cli/cmd/alpaca@latest ```

On macOS or Linux with Homebrew:

```bash brew install alpacahq/tap/cli ```

Make sure the binary directory is on `PATH`, commonly `~/go/bin` for Go installs.

### Local execution permissions

Alpaca CLI commands should run in your local workspace where your Alpaca profile, environment variables, network access, and saved artifacts are available. Some agent runtimes express this as:

```text required_permissions: ["all"] ```

Use the equivalent permission model in your agent environment so the CLI can access local auth/config and write run artifacts.

### Connectivity and authentication check

Before any backtest run, verify the CLI and credentials:

```bash alpaca doctor ```

If authentication fails, your agent should stop the run and show you the available login/help command:

```bash alpaca profile login --help ```

For interactive paper setup:

```bash alpaca profile login ```

For API-key setup:

```bash alpaca profile login --api-key ```

For automation, environment variables are preferred because secrets do not need to be written into generated code:

```bash export ALPACA_API_KEY=PK... export ALPACA_SECRET_KEY=... export ALPACA_QUIET=1 ```

Your agent should never print your secret key, commit it to files, include it in reports, or pass it in a way that exposes it to shell history.

### Machine-readable output

Use `--quiet` for commands whose output will be parsed by code:

```bash alpaca account get --quiet alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet ```

Use installed CLI help and schemas as the source of truth for flags and response fields:

```bash alpaca --help-all alpaca data bars --help alpaca data bars --schema alpaca data quotes --schema ```

Because the CLI is generated from API specifications and may evolve, your agent should prefer current `--help`, `--schema`, and `alpaca doctor` output over stale examples.

## Required workflow

Your agent should follow this workflow:

1. Gather required inputs: start date, end date, strategy concept or strategy file. 2. Gather or infer the rest: asset class, symbols or universe, timeframe, initial cash, position sizing, feed, adjustment mode, execution assumptions, benchmark. 3. Work through [run considerations](#run-considerations-checklist): order simulation, indicators, dividends, splits, fees, slippage, spread, market hours, calendar handling, and validation. 4. Translate your freeform idea into precise mathematical rules. 5. Present the formalized interpretation to you before writing code unless your request was already mathematically precise. 6. Check the workspace for reusable data, prior runs, and existing utilities. 7. Create a self-contained run folder. 8. Write `notes.md`, `strategy_spec.json`, `config.json`, and a readable run-specific script. 9. Fetch historical data through the Alpaca CLI, save raw CLI outputs, filter to the chosen market hours, and compute data fingerprints. 10. Run the local simulation. 11. Write artifacts. 12. Return the Teaching Five, first/last trade, assumptions, caveats, data fingerprint, and artifact paths.

## Workspace awareness

Before generating new code or fetching data, your agent should inspect the workspace.

### Data reuse

Look for prior raw data files or cached normalized data that match:

```text symbol asset class feed adjustment mode timeframe start/end range calendar filter regular-hours or extended-hours setting ```

Reuse data only when the data fingerprint matches. If fingerprints differ, your agent should treat the runs as using different input data.

### Run lineage

If this run is a variant of a prior run, `notes.md` should say what changed:

```text changed RSI threshold from 30/70 to 25/75 changed fill model from next_open bar proxy to quote-aware fill changed slippage from 5 bps to 10 bps extended date range from 2020-2024 to 2018-2025 ```

### Existing code

If the workspace already has a backtest engine or shared utility that matches the strategy requirements, your agent may reuse it. Otherwise, the default is a single readable `run.py` in the run folder.

## Run folder and artifact contract

Artifact paths in this skill use `raw/` and `normalized/` as canonical names.

Every run should create a folder like:

```text runs/YYYY-MM-DD_symbol_strategy_timeframe/ notes.md strategy_spec.json config.json run.py requirements.txt or pyproject.toml when needed raw/ bars_SYMBOL.json quotes_SYMBOL.json trades_SYMBOL.json calendar.json corporate_actions.json normalized/ bars_SYMBOL.csv quotes_SYMBOL.csv summary.json report.md trades.csv round_trips.csv equity.csv benchmark_equity.csv data_fingerprint.json warnings.json fee_source.json ```

### `notes.md`

`notes.md` should include your original request, confirmed strategy interpretation, every inferred/defaulted assumption, indicator definitions, fill model, fee model, data feed and adjustment mode, dividend and split treatment, benchmark definitions, calendar and market-hours handling, warnings and caveats, and Alpaca disclosure and fee schedule links.

### Other artifacts

See [reference.md](reference.md) for `summary.json`, `strategy_spec.json`, `data_fingerprint.json`, and `fee_source.json` schemas.

## Code generation rules

For run-specific CLI backtests, your agent should generate a script, not a reusable framework. A single-file `run.py` is the default.

Use readable code:

```python fill_price = bar_open * (1 + friction_pct) ```

instead of compressed expressions that make the artifact hard to audit.

The generated code should:

- read raw or normalized files from the run folder; - implement the confirmed strategy exactly; - implement the chosen indicator definitions exactly (see [Indicator formulas](reference.md#indicator-formulas)); - keep signal timing separate from fill timing; - compute fees, slippage, spread, and settlement according to the confirmed assumptions; - produce all required artifacts; - include deterministic sorting and timezone handling; - avoid hidden network calls after data fetch unless explicitly documented.

Use Python 3 by default. Prefer the standard library plus pandas/numpy when available. Add dependencies only when they materially improve correctness or readability.

## Strategy translation

Your agent should formalize your idea before code generation.

Every rule should specify: data field, trigger, inclusive/exclusive bounds, indicator variant and parameters, warmup behavior, position sizing and rounding, cash handling, order type, fill model, and benchmark.

Example confirmation:

```text I interpreted your strategy as: - Symbol: SPY - Timeframe: 1Day - Data: Alpaca CLI bars, feed=sip, adjustment=split - Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes - Entry: fast SMA crosses above slow SMA - Exit: fast SMA crosses below slow SMA - Signal timing: completed bar close - Fill timing: next trading day's open - Fill model: next_open bar proxy with 5 bps slippage unless quotes are available - Sizing: invest 100% of available cash, fractional shares allowed when supported - Benchmark: SPY buy-and-hold with same assumptions ```

After confirmation, code should match the confirmed interpretation.

## Fill models

Use these model names in confirmations and `notes.md`. Implementation detail is in [Fill model rules](reference.md#fill-model-rules).

- **`next_open`** (default): signal on bar T close; fill on bar T+1 open or quote at T+1 open timestamp. - **`time_based`**: fill at a confirmed time of day; quote bid/ask when available. - **`same_bar`**: only when explicitly requested; document look-ahead risk in `notes.md` and the report. - **Limit and stop orders**: OHLC-bar eligibility rules apply; use conservative intrabar conflict policy when stop and target both touch the same bar.

## Report format

`report.md` should lead with **Performance vs Benchmarks**:

```markdown | | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity | |---|---:|---:|---:|---:|---:| | **Strategy** | ...% | ...% | ...% | ... | $... | | Benchmark | ...% | ...% | ...% | ... | $... | ```

After the table, include strategy configuration, symbols/timeframe/feed/adjustment, fill model and friction, first and last trade, detailed metrics, benchmark explanation, assumptions, data fingerprint, caveats, and the disclosure block.

Metric definitions are in [reference.md](reference.md#metric-formulas).

## In-chat response standard

Lead with the **Teaching Five**:

1. total return versus benchmark; 2. max drawdown; 3. number of trades; 4. win rate; 5. Sharpe ratio versus benchmark.

Then include: annualized return, profit factor, fees paid, first trade, last trade, assumptions made, data fingerprint summary, artifact paths, and most important caveats.

If no trades occurred, say that directly and explain whether this was due to warmup, no signal, insufficient

--- name: alpaca-trading-backtest description: > Execute deterministic, reproducible historical backtests from a start date, end date, and strategy concept using the Alpaca CLI plus agent-written workspace code. Use when the user wants to backtest a strategy, simulate historical trades, or return trades, diagnostics, and reproducibility artifacts. ---

# Trading API Backtesting

Use this skill when you want your AI agent to run a specific historical backtest with the Alpaca CLI and local workspace code. This version is optimized for run-specific execution: your agent writes the minimum readable code needed for the confirmed strategy, stores the exact artifacts, and reports the results back to you.

This skill is written for you, the person invoking it through your AI agent. **You** means the trader, developer, researcher, or operator asking your agent to run the backtest. Your agent should address you directly, restate assumptions clearly, and make every interpretation choice visible.

```text strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report ```

It is not a promise that a strategy will work in live markets. It is a reproducible research workflow.

## Required disclosures

Every report, `notes.md`, `report.md`, notebook, dashboard, or exported result should include:

> **Important disclosure** > This backtest is a hypothetical historical simulation and does not represent actual trading performance. Backtested results do not guarantee future results. Results depend on market-data quality, data feed selection, corporate-action handling, fees, slippage, liquidity, taxes, execution assumptions, and implementation details. This material is for research and educational purposes only and is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investments involve risk and may lose value. Review Alpaca's disclosures and agreements at [alpaca.markets/disclosures](https://alpaca.markets/disclosures).

When paper trading appears in the workflow, add:

> Paper trading is a simulated environment. It does not involve real money or actual securities transactions. Paper results may differ from live trading because of fill assumptions, market impact, liquidity, latency, data differences, order handling, fees, and other market conditions.

When the backtest models Alpaca securities trading-activity fees, `notes.md`, `summary.json`, and `report.md` should link to the Alpaca Brokerage Fee Schedule PDF:

```text https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf ```

Record the PDF revision date, extraction timestamp, modeled fee categories, and any fee items intentionally excluded.

## CLI prerequisites

### Alpaca CLI

Your agent should use the Alpaca CLI for market-data access.

Check whether it is installed:

```bash alpaca version ```

Install with Go when needed:

```bash go install github.com/alpacahq/cli/cmd/alpaca@latest ```

On macOS or Linux with Homebrew:

```bash brew install alpacahq/tap/cli ```

Make sure the binary directory is on `PATH`, commonly `~/go/bin` for Go installs.

### Local execution permissions

Alpaca CLI commands should run in your local workspace where your Alpaca profile, environment variables, network access, and saved artifacts are available. Some agent runtimes express this as:

```text required_permissions: ["all"] ```

Use the equivalent permission model in your agent environment so the CLI can access local auth/config and write run artifacts.

### Connectivity and authentication check

Before any backtest run, verify the CLI and credentials:

```bash alpaca doctor ```

If authentication fails, your agent should stop the run and show you the available login/help command:

```bash alpaca profile login --help ```

For interactive paper setup:

```bash alpaca profile login ```

For API-key setup:

```bash alpaca profile login --api-key ```

For automation, environment variables are preferred because secrets do not need to be written into generated code:

```bash export ALPACA_API_KEY=PK... export ALPACA_SECRET_KEY=... export ALPACA_QUIET=1 ```

Your agent should never print your secret key, commit it to files, include it in reports, or pass it in a way that exposes it to shell history.

### Machine-readable output

Use `--quiet` for commands whose output will be parsed by code:

```bash alpaca account get --quiet alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet ```

Use installed CLI help and schemas as the source of truth for flags and response fields:

```bash alpaca --help-all alpaca data bars --help alpaca data bars --schema alpaca data quotes --schema ```

Because the CLI is generated from API specifications and may evolve, your agent should prefer current `--help`, `--schema`, and `alpaca doctor` output over stale examples.

## Required workflow

Your agent should follow this workflow:

1. Gather required inputs: start date, end date, strategy concept or strategy file. 2. Gather or infer the rest: asset class, symbols or universe, timeframe, initial cash, position sizing, feed, adjustment mode, execution assumptions, benchmark. 3. Work through [run considerations](#run-considerations-checklist): order simulation, indicators, dividends, splits, fees, slippage, spread, market hours, calendar handling, and validation. 4. Translate your freeform idea into precise mathematical rules. 5. Present the formalized interpretation to you before writing code unless your request was already mathematically precise. 6. Check the workspace for reusable data, prior runs, and existing utilities. 7. Create a self-contained run folder. 8. Write `notes.md`, `strategy_spec.json`, `config.json`, and a readable run-specific script. 9. Fetch historical data through the Alpaca CLI, save raw CLI outputs, filter to the chosen market hours, and compute data fingerprints. 10. Run the local simulation. 11. Write artifacts. 12. Return the Teaching Five, first/last trade, assumptions, caveats, data fingerprint, and artifact paths.

## Workspace awareness

Before generating new code or fetching data, your agent should inspect the workspace.

### Data reuse

Look for prior raw data files or cached normalized data that match:

```text symbol asset class feed adjustment mode timeframe start/end range calendar filter regular-hours or extended-hours setting ```

Reuse data only when the data fingerprint matches. If fingerprints differ, your agent should treat the runs as using different input data.

### Run lineage

If this run is a variant of a prior run, `notes.md` should say what changed:

```text changed RSI threshold from 30/70 to 25/75 changed fill model from next_open bar proxy to quote-aware fill changed slippage from 5 bps to 10 bps extended date range from 2020-2024 to 2018-2025 ```

### Existing code

If the workspace already has a backtest engine or shared utility that matches the strategy requirements, your agent may reuse it. Otherwise, the default is a single readable `run.py` in the run folder.

## Run folder and artifact contract

Artifact paths in this skill use `raw/` and `normalized/` as canonical names.

Every run should create a folder like:

```text runs/YYYY-MM-DD_symbol_strategy_timeframe/ notes.md strategy_spec.json config.json run.py requirements.txt or pyproject.toml when needed raw/ bars_SYMBOL.json quotes_SYMBOL.json trades_SYMBOL.json calendar.json corporate_actions.json normalized/ bars_SYMBOL.csv quotes_SYMBOL.csv summary.json report.md trades.csv round_trips.csv equity.csv benchmark_equity.csv data_fingerprint.json warnings.json fee_source.json ```

### `notes.md`

`notes.md` should include your original request, confirmed strategy interpretation, every inferred/defaulted assumption, indicator definitions, fill model, fee model, data feed and adjustment mode, dividend and split treatment, benchmark definitions, calendar and market-hours handling, warnings and caveats, and Alpaca disclosure and fee schedule links.

### Other artifacts

See [reference.md](reference.md) for `summary.json`, `strategy_spec.json`, `data_fingerprint.json`, and `fee_source.json` schemas.

## Code generation rules

For run-specific CLI backtests, your agent should generate a script, not a reusable framework. A single-file `run.py` is the default.

Use readable code:

```python fill_price = bar_open * (1 + friction_pct) ```

instead of compressed expressions that make the artifact hard to audit.

The generated code should:

- read raw or normalized files from the run folder; - implement the confirmed strategy exactly; - implement the chosen indicator definitions exactly (see [Indicator formulas](reference.md#indicator-formulas)); - keep signal timing separate from fill timing; - compute fees, slippage, spread, and settlement according to the confirmed assumptions; - produce all required artifacts; - include deterministic sorting and timezone handling; - avoid hidden network calls after data fetch unless explicitly documented.

Use Python 3 by default. Prefer the standard library plus pandas/numpy when available. Add dependencies only when they materially improve correctness or readability.

## Strategy translation

Your agent should formalize your idea before code generation.

Every rule should specify: data field, trigger, inclusive/exclusive bounds, indicator variant and parameters, warmup behavior, position sizing and rounding, cash handling, order type, fill model, and benchmark.

Example confirmation:

```text I interpreted your strategy as: - Symbol: SPY - Timeframe: 1Day - Data: Alpaca CLI bars, feed=sip, adjustment=split - Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes - Entry: fast SMA crosses above slow SMA - Exit: fast SMA crosses below slow SMA - Signal timing: completed bar close - Fill timing: next trading day's open - Fill model: next_open bar proxy with 5 bps slippage unless quotes are available - Sizing: invest 100% of available cash, fractional shares allowed when supported - Benchmark: SPY buy-and-hold with same assumptions ```

After confirmation, code should match the confirmed interpretation.

## Fill models

Use these model names in confirmations and `notes.md`. Implementation detail is in [Fill model rules](reference.md#fill-model-rules).

- **`next_open`** (default): signal on bar T close; fill on bar T+1 open or quote at T+1 open timestamp. - **`time_based`**: fill at a confirmed time of day; quote bid/ask when available. - **`same_bar`**: only when explicitly requested; document look-ahead risk in `notes.md` and the report. - **Limit and stop orders**: OHLC-bar eligibility rules apply; use conservative intrabar conflict policy when stop and target both touch the same bar.

## Report format

`report.md` should lead with **Performance vs Benchmarks**:

```markdown | | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity | |---|---:|---:|---:|---:|---:| | **Strategy** | ...% | ...% | ...% | ... | $... | | Benchmark | ...% | ...% | ...% | ... | $... | ```

After the table, include strategy configuration, symbols/timeframe/feed/adjustment, fill model and friction, first and last trade, detailed metrics, benchmark explanation, assumptions, data fingerprint, caveats, and the disclosure block.

Metric definitions are in [reference.md](reference.md#metric-formulas).

## In-chat response standard

Lead with the **Teaching Five**:

1. total return versus benchmark; 2. max drawdown; 3. number of trades; 4. win rate; 5. Sharpe ratio versus benchmark.

Then include: annualized return, profit factor, fees paid, first trade, last trade, assumptions made, data fingerprint summary, artifact paths, and most important caveats.

If no trades occurred, say that directly and explain whether this was due to warmup, no signal, insufficient

--- name: alpaca-trading-backtest description: > Execute deterministic, reproducible historical backtests from a start date, end date, and strategy concept using the Alpaca CLI plus agent-written workspace code. Use when the user wants to backtest a strategy, simulate historical trades, or return trades, diagnostics, and reproducibility artifacts. ---

# Trading API Backtesting

Use this skill when you want your AI agent to run a specific historical backtest with the Alpaca CLI and local workspace code. This version is optimized for run-specific execution: your agent writes the minimum readable code needed for the confirmed strategy, stores the exact artifacts, and reports the results back to you.

This skill is written for you, the person invoking it through your AI agent. **You** means the trader, developer, researcher, or operator asking your agent to run the backtest. Your agent should address you directly, restate assumptions clearly, and make every interpretation choice visible.

```text strategy idea -> formalized rules -> confirmed assumptions -> CLI data fetch -> local script -> artifacts -> report ```

It is not a promise that a strategy will work in live markets. It is a reproducible research workflow.

## Required disclosures

Every report, `notes.md`, `report.md`, notebook, dashboard, or exported result should include:

> **Important disclosure** > This backtest is a hypothetical historical simulation and does not represent actual trading performance. Backtested results do not guarantee future results. Results depend on market-data quality, data feed selection, corporate-action handling, fees, slippage, liquidity, taxes, execution assumptions, and implementation details. This material is for research and educational purposes only and is not investment advice, a recommendation, an offer, or a solicitation to buy or sell securities, options, cryptocurrencies, or any other financial product. All investments involve risk and may lose value. Review Alpaca's disclosures and agreements at [alpaca.markets/disclosures](https://alpaca.markets/disclosures).

When paper trading appears in the workflow, add:

> Paper trading is a simulated environment. It does not involve real money or actual securities transactions. Paper results may differ from live trading because of fill assumptions, market impact, liquidity, latency, data differences, order handling, fees, and other market conditions.

When the backtest models Alpaca securities trading-activity fees, `notes.md`, `summary.json`, and `report.md` should link to the Alpaca Brokerage Fee Schedule PDF:

```text https://files.alpaca.markets/disclosures/library/BrokFeeSched.pdf ```

Record the PDF revision date, extraction timestamp, modeled fee categories, and any fee items intentionally excluded.

## CLI prerequisites

### Alpaca CLI

Your agent should use the Alpaca CLI for market-data access.

Check whether it is installed:

```bash alpaca version ```

Install with Go when needed:

```bash go install github.com/alpacahq/cli/cmd/alpaca@latest ```

On macOS or Linux with Homebrew:

```bash brew install alpacahq/tap/cli ```

Make sure the binary directory is on `PATH`, commonly `~/go/bin` for Go installs.

### Local execution permissions

Alpaca CLI commands should run in your local workspace where your Alpaca profile, environment variables, network access, and saved artifacts are available. Some agent runtimes express this as:

```text required_permissions: ["all"] ```

Use the equivalent permission model in your agent environment so the CLI can access local auth/config and write run artifacts.

### Connectivity and authentication check

Before any backtest run, verify the CLI and credentials:

```bash alpaca doctor ```

If authentication fails, your agent should stop the run and show you the available login/help command:

```bash alpaca profile login --help ```

For interactive paper setup:

```bash alpaca profile login ```

For API-key setup:

```bash alpaca profile login --api-key ```

For automation, environment variables are preferred because secrets do not need to be written into generated code:

```bash export ALPACA_API_KEY=PK... export ALPACA_SECRET_KEY=... export ALPACA_QUIET=1 ```

Your agent should never print your secret key, commit it to files, include it in reports, or pass it in a way that exposes it to shell history.

### Machine-readable output

Use `--quiet` for commands whose output will be parsed by code:

```bash alpaca account get --quiet alpaca data bars --symbol SPY --start 2024-01-01 --end 2024-12-31 --timeframe 1Day --quiet ```

Use installed CLI help and schemas as the source of truth for flags and response fields:

```bash alpaca --help-all alpaca data bars --help alpaca data bars --schema alpaca data quotes --schema ```

Because the CLI is generated from API specifications and may evolve, your agent should prefer current `--help`, `--schema`, and `alpaca doctor` output over stale examples.

## Required workflow

Your agent should follow this workflow:

1. Gather required inputs: start date, end date, strategy concept or strategy file. 2. Gather or infer the rest: asset class, symbols or universe, timeframe, initial cash, position sizing, feed, adjustment mode, execution assumptions, benchmark. 3. Work through [run considerations](#run-considerations-checklist): order simulation, indicators, dividends, splits, fees, slippage, spread, market hours, calendar handling, and validation. 4. Translate your freeform idea into precise mathematical rules. 5. Present the formalized interpretation to you before writing code unless your request was already mathematically precise. 6. Check the workspace for reusable data, prior runs, and existing utilities. 7. Create a self-contained run folder. 8. Write `notes.md`, `strategy_spec.json`, `config.json`, and a readable run-specific script. 9. Fetch historical data through the Alpaca CLI, save raw CLI outputs, filter to the chosen market hours, and compute data fingerprints. 10. Run the local simulation. 11. Write artifacts. 12. Return the Teaching Five, first/last trade, assumptions, caveats, data fingerprint, and artifact paths.

## Workspace awareness

Before generating new code or fetching data, your agent should inspect the workspace.

### Data reuse

Look for prior raw data files or cached normalized data that match:

```text symbol asset class feed adjustment mode timeframe start/end range calendar filter regular-hours or extended-hours setting ```

Reuse data only when the data fingerprint matches. If fingerprints differ, your agent should treat the runs as using different input data.

### Run lineage

If this run is a variant of a prior run, `notes.md` should say what changed:

```text changed RSI threshold from 30/70 to 25/75 changed fill model from next_open bar proxy to quote-aware fill changed slippage from 5 bps to 10 bps extended date range from 2020-2024 to 2018-2025 ```

### Existing code

If the workspace already has a backtest engine or shared utility that matches the strategy requirements, your agent may reuse it. Otherwise, the default is a single readable `run.py` in the run folder.

## Run folder and artifact contract

Artifact paths in this skill use `raw/` and `normalized/` as canonical names.

Every run should create a folder like:

```text runs/YYYY-MM-DD_symbol_strategy_timeframe/ notes.md strategy_spec.json config.json run.py requirements.txt or pyproject.toml when needed raw/ bars_SYMBOL.json quotes_SYMBOL.json trades_SYMBOL.json calendar.json corporate_actions.json normalized/ bars_SYMBOL.csv quotes_SYMBOL.csv summary.json report.md trades.csv round_trips.csv equity.csv benchmark_equity.csv data_fingerprint.json warnings.json fee_source.json ```

### `notes.md`

`notes.md` should include your original request, confirmed strategy interpretation, every inferred/defaulted assumption, indicator definitions, fill model, fee model, data feed and adjustment mode, dividend and split treatment, benchmark definitions, calendar and market-hours handling, warnings and caveats, and Alpaca disclosure and fee schedule links.

### Other artifacts

See [reference.md](reference.md) for `summary.json`, `strategy_spec.json`, `data_fingerprint.json`, and `fee_source.json` schemas.

## Code generation rules

For run-specific CLI backtests, your agent should generate a script, not a reusable framework. A single-file `run.py` is the default.

Use readable code:

```python fill_price = bar_open * (1 + friction_pct) ```

instead of compressed expressions that make the artifact hard to audit.

The generated code should:

- read raw or normalized files from the run folder; - implement the confirmed strategy exactly; - implement the chosen indicator definitions exactly (see [Indicator formulas](reference.md#indicator-formulas)); - keep signal timing separate from fill timing; - compute fees, slippage, spread, and settlement according to the confirmed assumptions; - produce all required artifacts; - include deterministic sorting and timezone handling; - avoid hidden network calls after data fetch unless explicitly documented.

Use Python 3 by default. Prefer the standard library plus pandas/numpy when available. Add dependencies only when they materially improve correctness or readability.

## Strategy translation

Your agent should formalize your idea before code generation.

Every rule should specify: data field, trigger, inclusive/exclusive bounds, indicator variant and parameters, warmup behavior, position sizing and rounding, cash handling, order type, fill model, and benchmark.

Example confirmation:

```text I interpreted your strategy as: - Symbol: SPY - Timeframe: 1Day - Data: Alpaca CLI bars, feed=sip, adjustment=split - Indicator: SMA(50) and SMA(200), simple arithmetic mean of completed daily closes - Entry: fast SMA crosses above slow SMA - Exit: fast SMA crosses below slow SMA - Signal timing: completed bar close - Fill timing: next trading day's open - Fill model: next_open bar proxy with 5 bps slippage unless quotes are available - Sizing: invest 100% of available cash, fractional shares allowed when supported - Benchmark: SPY buy-and-hold with same assumptions ```

After confirmation, code should match the confirmed interpretation.

## Fill models

Use these model names in confirmations and `notes.md`. Implementation detail is in [Fill model rules](reference.md#fill-model-rules).

- **`next_open`** (default): signal on bar T close; fill on bar T+1 open or quote at T+1 open timestamp. - **`time_based`**: fill at a confirmed time of day; quote bid/ask when available. - **`same_bar`**: only when explicitly requested; document look-ahead risk in `notes.md` and the report. - **Limit and stop orders**: OHLC-bar eligibility rules apply; use conservative intrabar conflict policy when stop and target both touch the same bar.

## Report format

`report.md` should lead with **Performance vs Benchmarks**:

```markdown | | Total Return | Ann. Return | Max Drawdown | Sharpe | Final Equity | |---|---:|---:|---:|---:|---:| | **Strategy** | ...% | ...% | ...% | ... | $... | | Benchmark | ...% | ...% | ...% | ... | $... | ```

After the table, include strategy configuration, symbols/timeframe/feed/adjustment, fill model and friction, first and last trade, detailed metrics, benchmark explanation, assumptions, data fingerprint, caveats, and the disclosure block.

Metric definitions are in [reference.md](reference.md#metric-formulas).

## In-chat response standard

Lead with the **Teaching Five**:

1. total return versus benchmark; 2. max drawdown; 3. number of trades; 4. win rate; 5. Sharpe ratio versus benchmark.

Then include: annualized return, profit factor, fees paid, first trade, last trade, assumptions made, data fingerprint summary, artifact paths, and most important caveats.

If no trades occurred, say that directly and explain whether this was due to warmup, no signal, insufficient