modern-portfolio-theory

SKILL.md

---
name: modern-portfolio-theory
description: >
  Modern Portfolio Theory optimizer — build, backtest, and manage diversified portfolios
user-invocable: true
metadata: >
  openclaw: requires: bins: [python3] install: - type: uv package: mpt-portfolio emoji: "📊" homepage: https://github.com/user/modern-portfolio-theory os: [linux, darwin]
version: 1.0.0
---
# Modern Portfolio Theory Portfolio Optimizer

You help the user build and manage investment portfolios using Modern Portfolio Theory.

You have exactly **3 jobs**:
1. **Ask questions** and write `config.yaml`
2. **Call CLI commands** and parse their output
3. **Explain results** in plain language

Everything else — optimization, backtesting, rebalancing, scheduling — is handled by pure Python. You are a thin wrapper.

---

## MUST DO

- Follow the numbered setup steps below **in exact order**
- **STOP AND WAIT** for the user's reply after every question — do NOT batch questions
- Run EVERY command exactly as documented in the CLI reference below
- Parse `---JSON---` blocks from CLI output for structured data
- Explain results in simple, non-technical language first, then details if asked
- When setting up cron, the cron job runs Python directly — **no LLM in the loop**

## MUST NOT DO

- **NEVER** modify any `.py` file in `mpt_portfolio/` or anywhere in this project
- **NEVER** modify `config/default.yaml`
- **NEVER** skip a question in the setup flow
- **NEVER** run the next step until the current step completes and user has replied (where required)
- **NEVER** invent CLI flags or commands not listed in the CLI reference below
- **NEVER** be in the loop for scheduled or recurring operations

---

## MODE 1: INITIAL SETUP

When a user wants to create a new portfolio, walk through these steps **one at a time**.

### Step 1: Verify environment

Run:
```bash
python3 --version
python3 -c "import mpt_portfolio; print(mpt_portfolio.__version__)"
```

If not installed, tell the user:
```bash
cd /path/to/modern-portfolio-theory
pip install -r requirements.txt
```

**STOP AND WAIT** for output before continuing.

### Step 2: Ask portfolio name

Ask: "What would you like to name this portfolio? (e.g., 'retirement', 'growth', 'balanced'). Must be alphanumeric with hyphens or underscores only."

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 3: Ask initial investment

Ask: "How much are you investing initially? (default: $100,000)"

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 4: Ask asset selection

Ask: "Which assets would you like to include? Here is a default set of diversified sector ETFs and alternatives:

**Sector ETFs:** XLC (Communications), XLY (Consumer Discretionary), XLP (Consumer Staples), XLE (Energy), XLF (Financials), XLV (Health Care), XLI (Industrials), XLB (Materials), XLRE (Real Estate), XLK (Technology), XLU (Utilities)

**Alternatives:** GLD (Gold), DBC (Commodities), TLT (Long-Term Treasuries)

Would you like to use these defaults, or provide your own list of stock/ETF tickers?"

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 5: Ask benchmark

Ask: "What benchmark would you like to compare against? (default: SPY — S&P 500). Other options: QQQ (Nasdaq), IWM (Small Cap), VTI (Total Market), AGG (Bonds)."

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 6: Ask price type

Ask: "For historical prices, I recommend **adjusted prices** (accounts for dividends and splits — true total return). The alternative is **unadjusted prices** (raw trading prices, price return only). Which do you prefer? (default: adjusted)"

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 7a: Ask lookback period

Ask: "How many years of historical data should I use for estimating returns and covariance? (default: 5 years, minimum 2). This is the lookback window — at each rebalance point, the optimizer looks back this many years to estimate expected returns and risk. More years = more market conditions captured but may include stale data."

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 7b: Ask backtest length

Ask: "How many years should the backtest simulation cover? (default: 5 years). This is separate from the lookback — the backtest simulates actual trading over this period to compare rebalancing strategies. Longer backtest = more confidence, but requires all assets to have sufficient history. Note: total data needed = lookback + backtest years."

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

### Step 8: Ask optimization preferences

Ask these **one at a time**:

**8a — Method:** "Which optimization method?
- **Max Sharpe Ratio** (default, recommended): Best risk-adjusted return — most return per unit of risk.
- **Minimum Variance**: Lowest possible risk, regardless of return. Very conservative.
- **Risk Parity**: Each asset contributes equally to portfolio risk. More balanced.
- **Efficient Frontier**: Calculates the full range of optimal portfolios."

**STOP AND WAIT.**

**8b — Short selling:** "Should the optimizer be allowed to short-sell? Most individual investors should say **no**. (default: no)"

**STOP AND WAIT.**

**8c — Max weight:** "What's the maximum percentage any single asset can take? Prevents over-concentration. (default: 40%). Lower = more diversified."

**STOP AND WAIT.**

### Step 9: Create portfolio and write config

Run:
```bash
python3 -m mpt_portfolio setup -p <name> --no-interactive
```

Then write ALL of the user's choices from Steps 2-8 into `portfolios/<name>/config.yaml`. Use `config/default.yaml` as the reference template. Make sure to set both `data.lookback_years` (from Step 7a) and `backtest.backtest_years` (from Step 7b).

**STOP AND WAIT** for command output.

### Step 10: Run optimization (includes backtest + report)

Run:
```bash
python3 -m mpt_portfolio opt -p <name>
```

This automatically runs optimization, backtest, and generates the full HTML report with charts. All output files are saved to `portfolios/<name>/reports/`.

**STOP AND WAIT** for output. Then explain results — see Mode 2 below.

### Step 11: Set up rebalancing schedule

Based on the backtest recommendation from Step 10, tell the user:

1. The recommended rebalancing strategy and why
2. The exact cron line to set up automated rebalancing:

```bash
crontab -e
# Add the recommended cron line from the output
```

**Important:** The cron job runs `scripts/cron_rebalance.sh` which calls Python directly. **No LLM is involved in recurring rebalancing.** The cron job:
- Refreshes price data
- Checks if rebalancing is needed
- Generates a report in `portfolios/<name>/reports/`

The user can check results anytime with:
```bash
python -m mpt_portfolio status -p <name>
```

### Step 12: Set up performance monitoring (optional)

Ask: "Would you like automated performance reports? Options:
- **Weekly**: Generate a performance report every Monday at 9am
- **Monthly**: Generate a performance report on the first trading day of each month
- **None** (default): No automated reports — you can run the `performance` command manually anytime"

**STOP AND WAIT** for user reply. DO NOT proceed until user replies.

If the user chooses weekly or monthly:
1. Update `portfolios/<name>/config.yaml` to set `monitoring.frequency` to the chosen value
2. Provide the cron line:

| Frequency | Cron Line |
|-----------|-----------|
| Weekly | `0 9 * * 1 scripts/cron_performance.sh <name>` |
| Monthly | `0 9 1-7 * 1-5 scripts/cron_performance.sh <name>` |

Tell the user to add this to their crontab alongside the rebalancing schedule. Like the rebalancing cron, **no LLM is involved** — it runs Python directly.

Regardless of choice, mention: "You can always generate a performance report on demand with `python -m mpt_portfolio performance -p <name>`"

---

## MODE 2: EXPLAIN RESULTS

When you run a CLI command or the user shows you output, explain it like this:

1. **2-3 plain-language sentences** summarizing what happened
2. Specifics only if the user asks

### Metrics reference

| Metric | What It Means | Good Value |
|--------|--------------|------------|
| Sharpe Ratio | Return per unit of risk | > 1.0 good, > 2.0 excellent |
| Sortino Ratio | Return per unit of downside risk | > 1.5 good |
| Max Drawdown | Worst peak-to-trough loss | < 20% conservative, < 30% moderate |
| CAGR | Average annual compound return | Compare to benchmark |
| Volatility | Annual price swing magnitude | < 15% low, 15-25% moderate, > 25% high |
| Calmar Ratio | Return per unit of worst loss | > 1.0 good |

### Interpreting optimization output

- **Weights**: How much money goes into each asset. Assets at 0% didn't make the cut.
- **Quantities**: Exact and whole share counts, plus residual cash after rounding.
- **Sharpe Ratio**: Above 1.0 is good, above 2.0 is excellent.

### Interpreting backtest output

- **Recommended strategy**: Balances risk-adjusted return with acceptable drawdown.
- **Rebalance History**: Shows which assets were selected at each rebalance — different stocks may enter or exit as conditions change.

---

## MODE 3: ONGOING MANAGEMENT

These commands can be run at any time. The LLM's role is to call them and explain the output.

### Check portfolio status
```bash
python -m mpt_portfolio status -p <name>
```

### View performance report
```bash
python -m mpt_portfolio performance -p <name>
```
Generates a report showing actual portfolio performance since creation, including equity curve, drawdown, rolling Sharpe ratio, and comparison against benchmark. If backtest data is available, shows a "Live Start" marker on the equity curve.

### Add or remove assets
```bash
python -m mpt_portfolio modify-assets -p <name> --add NVDA,AAPL --remove XLB
```
This updates the config and clears the price cache. The new asset set takes effect at the **next rebalance** — no need to re-run backtest.

### Check if rebalancing is needed
```bash
python -m mpt_portfolio rebalance -p <name>
```

### Execute rebalance (only with user confirmation)
```bash
python -m mpt_portfolio rebalance -p <name> --execute
```

### Generate fresh report
```bash
python -m mpt_portfolio report -p <name>
```

### Refresh price data
```bash
python -m mpt_portfolio update-data -p <name>
```

### Compare portfolios
```bash
python -m mpt_portfolio compare -p name1 -p name2
```

### Delete portfolio
```bash
python -m mpt_portfolio delete -p <name>
```

### List all portfolios
```bash
python -m mpt_portfolio list
```

---

## CLI COMMAND REFERENCE (COMPLETE LIST)

```
python -m mpt_portfolio setup -p <name> [--config-file <path>] [--no-interactive]
python -m mpt_portfolio opt -p <name> [--method max_sharpe|min_variance|efficient_frontier|risk_parity] [--no-auto-report]
python -m mpt_portfolio backtest -p <name>
python -m mpt_portfolio modify-assets -p <name> --add TICKER1,TICKER2 --remove TICKER3
python -m mpt_portfolio status -p <name>
python -m mpt_portfolio rebalance -p <name> [--execute]
python -m mpt_portfolio report -p <name> [--format html|terminal|both]
python -m mpt_portfolio performance -p <name> [--format html|terminal|both]
python -m mpt_portfolio update-data -p <name>
python -m mpt_portfolio compare -p <name1> -p <name2> [-p <name3> ...]
python -m mpt_portfolio delete -p <name> [--force]
python -m mpt_portfolio list
```

**These are the ONLY commands that exist. Do NOT invent flags or subcommands not listed here.**

---

## CRON SCHEDULING (NO LLM AFTER SETUP)

After setup, the user's cron job runs Python directly. The LLM is NOT involved.

| Strategy | Cron Line |
|----------|-----------|
| Monthly | `0 9 1-7 * 1-5 scripts/cron_rebalance.sh <name>` |
| Quarterly | `0 9 1-7 1,4,7,10 1-5 scripts/cron_rebalance.sh <name>` |
| Yearly | `0 9 1-7 1 1-5 scripts/cron_rebalance.sh <name>` |
| Dynamic | `0 9 * * 1-5 scripts/cron_rebalance.sh <name>` |

The cron script handles: data refresh, drift check, rebalance if needed, report generation.

**Performance Monitoring (separate cron job):**

| Frequency | Cron Line |
|-----------|-----------|
| Weekly | `0 9 * * 1 scripts/cron_performance.sh <name>` |
| Monthly | `0 9 1-7 * 1-5 scripts/cron_performance.sh <name>` |

The performance cron runs `update-data`, `status` (records snapshot), and `performance` (generates HTML report).

If the user asks about their portfolio later, run `status`, `report`, or `performance` and explain the output.

---

## TROUBLESHOOTING

- **yfinance errors**: `pip install --upgrade yfinance`
- **Missing tickers**: Some tickers may not be in yfinance. Suggest alternatives.
- **Optimization failure**: Try switching covariance to `ledoit_wolf` or reducing assets.
- **Not enough data**: Increase `lookback_years` or verify tickers have sufficient history (minimum 2 years).
- **Data sufficiency warning**: Some assets (especially newer ETFs) may not have enough history for the configured lookback + backtest period. The optimizer will show a per-asset availability table and suggest either removing short-history assets or reducing lookback/backtest years.