market-regime
Skill0 starsChanged 23 days agoMITView on GitHub
Markov-chain market regime analysis for any stock, ETF, index, FX pair or crypto. Labels price history Bull, Sideways or Bear, builds an honest transition matrix from non-overlapping windows, reads the signal P(Bull) - P(Bear) for the next window, shows how fast the forecast fades, and runs a walk-forward backtest with costs against buy and hold. Writes a text report, JSON and a single-file HTML report. Pure Python standard library: nothing to install. Use when someone asks what regime a market is in, whether a trend is likely to persist, for a Markov or regime-switching read, a transition matrix, bull/bear/sideways probabilities, a regime filter for a strategy, or an honest backtest of a regime rule. Works on tickers like SPY, AAPL, ^GSPC, BTC-USD, EURUSD=X, crypto pairs like BTCUSDT on 1h/4h/daily bars, or any price CSV.
3 other projects use a version of this.
Adopted by
Most recently taken up by
- rgourley/quant-garagetheir own version, first seen Nov 1, 2026
- Shubhamkumartrichy/claude-trading-skills-indiatheir own version, first seen Nov 1, 2026
- nimadorostkar/Claude-Skills-collectiontheir own version, first seen Oct 13, 2026
Other versions3 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 3
- Shubhamkumartrichy/claude-trading-skills-india★ 64same name
- nimadorostkar/Claude-Skills-collection★ 37same name
- rgourley/quant-garage★ 7same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
The file
We split this skill into the rules it gives an agent
7 rules. 0 are common, 5 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 3 edited versions we read keep these.
5
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 67
Pin down the market and bar size: If the user named a ticker, use it.
- Very specific: line 68
Default to daily bars. For crypto intraday ("4h", "hourly") use the Binance pair (BTCUSDT, not BTC-USD).
- Distinctive: line 95
Keep it short and plain. Lead with what is true now, then how much to trust it.
- Distinctive: line 117
Always close with: "Backtests flatter.
- Distinctive: line 129
Don't tune to the backtest: If the user wants the best window or threshold, explain that every extra run on the same history is another …
- Distinctive: line 136
It reads public price data and nothing else: Never ask for exchange API keys, wallets or account access.
- Distinctive: line 156
Label mix: if one state covers more than ~75% of bars or another under ~5%, the threshold doesn't suit that market's volatility.
“Common” is measured: kept by at least 6 in 10 of the 3 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Market regime
A statistical read of where a market sits in its Bull / Sideways / Bear cycle, built so the numbers can't flatter themselves. Made by Bentley Markets.
Everything runs from one script, scripts/regime.py, on Python 3.8+ with no
packages to install. Use python instead of python3 on Windows.
Run it
SKILL_DIR is not set for you. Set it to the absolute path of the folder this
SKILL.md is in (for example ~/.claude/skills/market-regime or
~/.codex/skills/market-regime) in the same command:
SKILL_DIR="$HOME/.claude/skills/market-regime"
python3 "$SKILL_DIR/scripts/regime.py" SPY --threshold 0.03 \
--json /tmp/regime-SPY.json --html "$PWD/regime-SPY.html"The text report prints to stdout. Read it, and read the JSON if you need exact figures. The JSON can live in a temp folder. Write the HTML report to the user's current working folder (or wherever they asked) as an absolute path, and tell them that path.
| Flag | Default | What it does |
SYMBOL | Yahoo ticker (SPY, AAPL, ^GSPC, BTC-USD, EURUSD=X, GC=F, SHOP.TO) or Binance pair (BTCUSDT, ETHUSDT) | |
--interval | 1d | 1h, 4h, 1d, 1wk. 4h needs a Binance pair. |
--years | 10 (1d), 7 (4h), 3 (1h), 20 (1wk) | history to fetch |
--csv PATH | read prices from a file instead (--date-col, --close-col if not guessed) | |
--window | 20 bars daily, ~7 days intraday, 4 weekly | the trailing return that defines a regime |
--threshold | 0.05 | Bull at or above +5% over the window, Bear at or below -5% |
--mode | filter | filter: long above the gate, short below, flat between. standalone: size with the signal |
--entry | 0.10 | the signal gate for filter mode |
--long-only | off | never short, sit flat instead |
--cost-bps | 5 | cost per unit of position change, in basis points |
--min-train | one year of bars | history the matrix learns from before the first backtest trade |
--json, --html | write the full result / the visual report | |
--force | off | show results even when the label checks fail |
Exit codes: 0 fine, 2 data problem (message on stderr), 3 label checks failed.
Source is picked automatically: crypto pairs like BTCUSDT go to Binance's
public market-data API, everything else to Yahoo Finance. Force one with
--source yahoo or --source binance.
Workflow
- Pin down the market and bar size. If the user named a ticker, use it.
Default to daily bars. For crypto intraday ("4h", "hourly") use the Binance
pair (
BTCUSDT, notBTC-USD). If they gave a file, use--csv. Pick the threshold from the asset class, before you run, unless the user set one. A threshold that suits the market's volatility gives the chain all three regimes to learn from. Choosing it up front, rather than after seeing a backtest, keeps the test honest.
Market Daily bars, 20-bar window Broad stock index or ETF (SPY, QQQ, ^GSPC) --threshold 0.03Single stock 0.05to0.08Gold, oil, other commodities 0.04Major FX pairs 0.02Crypto 0.10to0.15(or0.05on 4h bars, 7-day window)- Run it with
--jsonand--html. If the sandbox has no internet (the fetch fails with "could not reach"), ask the user for a CSV export: Yahoo Finance's download, a TradingView chart export, or any file with a date column and a close column all work. - If it exits 3 (label checks failed), one regime barely exists at that
threshold. Re-run with a smaller
--threshold(try half) and say you did. - Check the warnings at the end of the text report before writing anything. They decide how confident your summary can sound.
- Present the result in the order below, then offer the HTML report.
How to present it
Keep it short and plain. Lead with what is true now, then how much to trust it.
- Regime now: state, how long it has held, the window return, and the date of the last bar (the read is as of that close, not live).
- Next window: the honest matrix row for today's state as Bull / Sideways / Bear odds, with how many past transitions that row rests on.
- Signal and lean:
P(Bull) - P(Bear), and what the rule would do (long, short or flat). Call it a lean, never a call or a prediction. - Persistence: the honest diagonal (stickiness), and in one line how much the overlapping matrix inflates it on average. This is the point of the method.
- Fade: the forecast converges to the long-run mix within a few windows, so anything past that horizon carries no information. Show the first one or two windows and the long-run mix; skip rows that repeat it.
- Backtest: honest vs buy and hold on Sharpe, CAGR, max drawdown and time in market. If honest loses to buy and hold, say so first and plainly. Say how the rule actually behaved (the report's "long X% of bars, short Y%, flat Z%" line): a filter that was long 98% of the time is buy and hold with extra costs. Mention the inflated version only as the cautionary comparison.
- Caveats: any warnings from the report, then the closing line below.
Always close with: "Backtests flatter. The honest matrix shows uglier, truer numbers, and those are the only ones worth acting on. This is a statistical read of past prices, not financial advice."
Rules
- Never present the overlapping matrix or its backtest as the result. Neighbouring windows share all but one bar, so counting every bar fakes persistence. It exists only to show the gap.
- Never imply the output predicts returns or tells anyone to trade. No "buy", "sell", "you should". Say "the rule would be long", "the regime leans bullish". Don't promise or project profits.
- Don't tune to the backtest. If the user wants the best window or threshold, explain that every extra run on the same history is another test and the winner is partly luck. If they still want a sweep, keep it small, report every run you tried (not just the best), and suggest checking the chosen settings on a different market or a later period.
- Respect small samples. A row resting on fewer than 20 transitions is rough. Say so when today's signal comes from such a row.
- It reads public price data and nothing else. Never ask for exchange API keys, wallets or account access. This skill places no orders.
- Suggest paper trading before anyone acts on a regime rule.
Reading the numbers
- Signal runs from -1 to +1. The sign is direction, the size is conviction. Between -0.10 and +0.10 (the default gate) the chain has nothing useful to say.
- Stickiness is the matrix diagonal: the chance the next window is in the same regime. Honest stickiness is usually far below the overlapping one.
- One step is one window, not one bar. With a 20-day window, the first forecast row is about a month out.
- A Bear regime with a bullish lean is normal, and so is the reverse. The signal is about the next window, so it says Bear windows have more often been followed by recoveries than by more Bear (mean reversion). Explain it in those words rather than as a contradiction, and mention how many bars the regime has held: a regime two bars old is barely established.
- Labels describe the past window, so a regime is only confirmed after a move has happened. The method is a filter on context, not a timing tool.
- Label mix: if one state covers more than ~75% of bars or another under ~5%, the threshold doesn't suit that market's volatility. Use the table in the workflow, and say so if you change it after a run.
Troubleshooting
could not reach ...: no internet in this environment. Use--csv.Python could not verify HTTPS certificates: on macOS python.org installs, run "Install Certificates.command" in the Python folder, or use--csv.Yahoo has no data for X: wrong ticker format. Index tickers start with^, FX ends in=X, non-US listings carry an exchange suffix (.TO,.L,.NS).Binance does not list X: use the exchange pair, quote currency included.not enoughbars: fetch more--yearsor lower--min-train.
Using it from Python
import sys; sys.path.insert(0, f"{SKILL_DIR}/scripts")
import regime
times, closes = regime.fetch_yahoo("SPY", "1d", 10) # or fetch_binance / load_csv
result = regime.analyze(times, closes, window=20, threshold=0.05, cost=0.0005)references/method.md has the full method, the defaults behind each bar
size, and what was deliberately left out.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

