Agent skill

Historical Risk

by JoelLewis in JoelLewis/finance_skills

Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics.

MITAuto-check passedBusiness, Finance & HR

Install Historical Risk

skills CLI
$ npx skills add JoelLewis/finance_skills --skill historical-risk -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install JoelLewis/finance_skills historical-risk --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/JoelLewis/finance_skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugins/wealth-management/skills/historical-risk .claude/skills/historical-risk && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
historical-risk
GitHub stars
206
Token cost
~2.1k tokens
SKILL.md length
947 words
Files
2 (incl. scripts)
Skills in repo
91
Repo updated
First seen
Licence
MIT

At a glance

Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics.

  • The user asks about historical volatility
  • SKILL.md covers Core Concepts, Key Formulas, Worked Examples and Common Pitfalls, plus 2 more sections
  • Runs Python scripts from its folder; calls uv, python3 and pip
  • Maximum drawdown

What it does

Historical Risk is an agent skill from JoelLewis/finance_skills. Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics. Use when the user asks about historical volatility, maximum drawdown, drawdown duration, historical VaR, downside deviation, semi-variance, or tracking error. Also trigger when users mention 'how risky has this been', 'worst decline', 'Parkinson estimator', 'Yang-Zhang', 'peak-to-trough loss', 'recovery time', 'annualized volatility', or ask how to measure past investment risk.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/historical_risk.py`).

It sits in Business, Finance & HR. The repository describes itself as: Claude Code skill plugins for financial services — 81 skills across 7 domain plugins covering investment management, compliance, advisory practice, trading, and operations. The licence is MIT.

When your agent uses it

  • The user asks about historical volatility
  • Maximum drawdown
  • Drawdown duration
  • Downside deviation

Example prompts

  • “how risky has this been”
  • “worst decline”
  • “Parkinson estimator”
  • “/historical-risk”

Requirements

  • Python 3

What it can do on your machine

Read from SKILL.md and the folder at commit 5c498ea. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • uv
    • python3
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv and pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Historical Risk loads about 2.1k tokens when it runs. Until then it costs about 129 tokens; SKILL.md has 947 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~129
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from JoelLewis/finance_skills at commit 5c498ea, republished under its MIT licence (© JoelLewis). 947 words, ~2,084 tokens.

Download SKILL.mdSave it as .claude/skills/historical-risk/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
historical-risk
description
Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics. Use when the user asks about historical volatility, maximum drawdown, drawdown duration, historical VaR, downside deviation, semi-variance, or tracking error. Also trigger when users mention 'how risky has this been', 'worst decline', 'Parkinson estimator', 'Yang-Zhang', 'peak-to-trough loss', 'recovery time', 'annualized volatility', or ask how to measure past investment risk.

Historical Risk Analysis

Core Concepts

Close-to-Close Volatility

The simplest and most common volatility estimator. Compute the standard deviation of log returns and annualize.

sigma_annual = sigma_daily * sqrt(N)

where N = number of trading periods per year (typically 252 for daily, 52 for weekly, 12 for monthly).

Log returns are preferred: r_t = ln(P_t / P_{t-1}).

Parkinson (High-Low) Estimator

Uses intraday high and low prices to capture intraday volatility that close-to-close misses. More efficient than close-to-close when the true process is continuous.

sigma^2_Park = (1 / (4 * n * ln(2))) * sum( ln(H_i / L_i)^2 )

This estimator is roughly 5x more efficient than close-to-close for a diffusion process, but is biased downward when there are jumps or when the range is discretized.

Yang-Zhang Estimator

Combines overnight (close-to-open), open-to-close, and Rogers-Satchell components. It is unbiased for processes with both drift and opening jumps.

sigma^2_YZ = sigma^2_overnight + k * sigma^2_open-to-close + (1 - k) * sigma^2_RS

where k is chosen to minimize estimator variance:

k = 0.34 / (1.34 + (n + 1) / (n - 1))

with n the number of observations, and sigma^2_RS is the Rogers-Satchell estimator that uses all four OHLC prices within each period.

Drawdown Analysis

Drawdown at time t measures the decline from the running peak:

DD_t = (Peak_t - Value_t) / Peak_t

where Peak_t = max(Value_s) for all s <= t.

  • Maximum Drawdown (MDD): MDD = max(DD_t) over the evaluation period.
  • Drawdown Duration: The number of periods from a peak until a new peak is reached.
  • Recovery Time: The number of periods from the trough back to the prior peak level.
Historical VaR

The non-parametric (empirical) Value-at-Risk is simply the alpha-percentile of the historical return distribution. No distributional assumptions are made.

VaR_alpha = -Percentile(R, alpha)

For example, 95% VaR uses the 5th percentile of returns. The negative sign is a convention so that VaR is expressed as a positive loss number.

Downside Deviation

Measures dispersion of returns below a Minimum Acceptable Return (MAR):

sigma_d = sqrt( (1/n) * sum( min(R_i - MAR, 0)^2 ) )

Common choices for MAR: 0%, the risk-free rate, or the mean return.

Tracking Error

Standard deviation of the difference between portfolio and benchmark returns, annualized:

TE = std(R_p - R_b) * sqrt(N)

This measures how consistently the portfolio tracks (or deviates from) its benchmark.

Semi-Variance

Variance computed using only returns below the mean (or below a threshold):

SV = (1/n) * sum( min(R_i - mean(R), 0)^2 )

Semi-variance isolates downside risk and is the foundation for the Sortino ratio (see performance-metrics).

Key Formulas

FormulaExpressionUse Case
Annualized Volatilitysigma_ann = sigma_period * sqrt(N)Convert period vol to annual vol
Log Returnr_t = ln(P_t / P_{t-1})Compute continuously compounded returns
Parkinson Variancesigma^2 = (1 / (4n ln2)) * sum(ln(H/L)^2)Volatility from high-low data
DrawdownDD_t = (Peak_t - Value_t) / Peak_tMeasure peak-to-trough decline
Max DrawdownMDD = max(DD_t)Worst historical decline
Historical VaR (95%)5th percentile of return seriesNon-parametric loss estimate
Downside Deviationsigma_d = sqrt((1/n) * sum(min(R_i - MAR, 0)^2))Asymmetric risk below MAR
Tracking ErrorTE = std(R_p - R_b) * sqrt(N)Portfolio vs benchmark deviation
Semi-Variance(1/n) * sum(min(R_i - mean(R), 0)^2)Below-mean variance

Worked Examples

Example 1: Annualized Volatility from Daily Returns

Given: A stock has daily log returns with a sample standard deviation of 1.2%. Assume 252 trading days per year.

Calculate: Annualized volatility.

Solution:

sigma_annual = 0.012 * sqrt(252)
             = 0.012 * 15.875
             = 0.1905
             ~ 19.05%

The stock's annualized volatility is approximately 19%.

Example 2: Maximum Drawdown from a Price Series

Given: A fund's NAV follows this path over six months: $120, $135, $150, $130, $105, $125.

Calculate: Maximum drawdown and identify the peak and trough.

Solution:

Running peaks: $120, $135, $150, $150, $150, $150.

Drawdowns at each point:

  • $120: (120-120)/120 = 0%
  • $135: (135-135)/135 = 0%
  • $150: (150-150)/150 = 0%
  • $130: (150-130)/150 = 13.3%
  • $105: (150-105)/150 = 30.0%
  • $125: (150-125)/150 = 16.7%

Maximum Drawdown = 30.0%, occurring from the peak of $150 to the trough of $105. As of the last observation ($125), the drawdown has not yet fully recovered.

Show full SKILL.md (394 more words)Show less
Example 3: Historical VaR

Given: 500 daily returns sorted from worst to best. The 25th-worst return is -2.8% and the 26th-worst is -2.6%.

Calculate: 95% 1-day historical VaR.

Solution:

The 5th percentile corresponds to the 25th observation out of 500 (500 * 0.05 = 25).

VaR_95% = -(-2.8%) = 2.8%

Interpretation: On 95% of days, the loss is expected not to exceed 2.8% based on the historical distribution.

Common Pitfalls

  • Not annualizing volatility correctly: Volatility scales with the square root of time (multiply by sqrt(N)), not linearly. Multiplying daily vol by 252 instead of sqrt(252) produces wildly inflated numbers.
  • Using calendar days vs trading days inconsistently: Use 252 trading days (not 365 calendar days) for equity markets when annualizing. Bond markets and some international markets may differ.
  • Survivorship bias in historical data: Data sets that exclude delisted or failed securities understate realized risk.
  • Lookback period sensitivity: A 1-year lookback captures different risk regimes than a 5-year lookback. Always state the lookback window and consider whether it spans relevant market conditions.
  • Confusing VaR confidence level direction: 95% VaR corresponds to the 5th percentile of returns (the loss tail). The "95%" refers to the confidence level, not the percentile of gains.
  • Log returns vs simple returns: For volatility estimation, log returns are preferred because they are additive across time. For reporting cumulative performance, simple returns are more intuitive.

Cross-References

  • performance-metrics (wealth-management plugin): Uses volatility, downside deviation, tracking error, and max drawdown as denominators in risk-adjusted ratios (Sharpe, Sortino, Information Ratio, Calmar).
  • forward-risk (wealth-management plugin): Historical VaR and historical volatility serve as inputs to forward-looking VaR models and stress tests.
  • volatility-modeling (wealth-management plugin): EWMA and GARCH models extend the simple historical volatility estimators covered here into forecasting frameworks.
  • retirement-decumulation (wealth-management plugin): drawdown and volatility history drives sequence-of-returns risk in withdrawal-phase portfolios

Running the script

Run with uv run scripts/historical_risk.py (the PEP 723 header resolves numpy automatically) or with python3 scripts/historical_risk.py after pip install numpy scipy. A bare run prints a full risk analysis (annualized and Parkinson volatility, maximum drawdown with timing, 95%/99% historical VaR, downside deviation, semi-variance, tracking error, rolling volatility) on seeded synthetic data with an injected drawdown event. Use --verify to assert outputs match this skill's worked examples and the demo's expected values (exit code 0 on PASS) and --help for an overview of the class. The file is primarily meant to be imported as a module (e.g., from historical_risk import HistoricalRiskAnalyzer).

© JoelLewis, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (scripts) in plugins/wealth-management/skills/historical-risk of JoelLewis/finance_skills.

  • SKILL.md
  • scripts/historical_risk.py

Open the folder on GitHubat commit 5c498ea

Compare with similar skills

Historical Risk next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Historical Risk compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Historical Risk this skillJoelLewis/finance_skills206—~2.1kAutomated safety check: PassMIT
Technical Analysttradermonty/claude-trading-skills3k4 repos~4.6kAutomated safety check: PassMIT
Theme Detectortradermonty/claude-trading-skills3k2 repos~4.9kAutomated safety check: PassMIT
Creating Financial ModelsChen-zexi/open-ptc-agent7293 repos~1.3kAutomated safety check: PassMIT
Stock APIzhangxiangliang/stock-api2k—~507Automated safety check: PassMIT
Itr Walakaranb192/itr-wala871—~3.6kAutomated safety check: PassMIT

Similar skills

  • Technical Analyst

    tradermonty/claude-trading-skills

    This skill should be used when analyzing weekly price charts for stocks, stock indices, cryptocurrencies, or forex pairs.

    3k GitHub starsUsed in 4 repos~4.6k tokens
    Business, Finance & HRAuto-check passed
  • Theme Detector

    tradermonty/claude-trading-skills

    Detect and analyze trending market themes across sectors. An agent skill from tradermonty/claude-trading-skills.

    3k GitHub starsUsed in 2 repos~4.9k tokens
    Business, Finance & HRAuto-check passed
  • Creating Financial Models

    Chen-zexi/open-ptc-agent

    This skill provides an advanced financial modeling suite with DCF analysis, sensitivity testing, Monte Carlo simulations, and scenario planning for investment decisions

    729 GitHub starsUsed in 3 repos~1.3k tokens
    Business, Finance & HRAuto-check passed
  • Stock API

    zhangxiangliang/stock-api

    Fetch real-time stock quotes, K-line (candlestick) history, and search symbols for China A-shares, Hong Kong, and US markets.

    2k GitHub stars~507 tokensUpdated yesterday
    Business, Finance & HRAuto-check passed
  • Itr Wala

    karanb192/itr-wala

    File Indian income tax returns (ITR) for FY 2025-26 / AY 2026-27.

    871 GitHub stars~3.6k tokensUpdated 7 days ago
    Business, Finance & HRAuto-check passed
  • Tushare Data

    zillionare/zillionare

    面向中文自然语言的 Tushare 数据研究技能。用于把“看看这只股票最近怎么样”“帮我查财报趋势”“最近哪个板块最强”“北向资金在买什么”“给我导出一份行情数据”这类请求,转成可执行的数据获取、清洗、对比、筛选、导出与简要分析流程。适用于 A 股、指数、ETF/基金、财务、估值、资金流、公告新闻、板块概念与宏观数据等研究场景。

    322 GitHub starsUsed in 2 repos~2.3k tokens
    Business, Finance & HRAuto-check passed

More from JoelLewis/finance_skills

All 91 skills in this repo
  • Asset Allocation

    JoelLewis/finance_skills

    Determine how to distribute capital across asset classes using strategic and tactical allocation frameworks.

    206 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Bet Sizing

    JoelLewis/finance_skills

    Determine how much capital to allocate to individual positions within a portfolio.

    206 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Commodities

    JoelLewis/finance_skills

    Analyze commodity markets including futures curve dynamics, roll yield, and supply/demand fundamentals.

    206 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed
  • Currencies And Fx

    JoelLewis/finance_skills

    Analyze currency markets, exchange rate mechanics, and FX risk management for international portfolios.

    206 GitHub stars~1.9k tokensUpdated 2 mo ago
    Auto-check passed
  • Debt Management

    JoelLewis/finance_skills

    Provide frameworks for managing and paying off personal debt effectively.

    206 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed
  • Diversification

    JoelLewis/finance_skills

    Build diversified portfolios using correlation analysis, efficient frontier construction, and factor-based diversification.

    206 GitHub stars~2.3k tokensUpdated 2 mo ago
    Auto-check passed

Questions about Historical Risk

What does Historical Risk do?

Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics. Historical Risk is an agent skill from JoelLewis/finance_skills. Quantify realized risk from historical data using volatility estimators, drawdown analysis, and downside risk metrics.

When should I use Historical Risk?

Historical Risk fits situations like: the user asks about historical volatility; maximum drawdown; drawdown duration; downside deviation.

How do I install Historical Risk in Claude Code?

Run `npx skills add JoelLewis/finance_skills --skill historical-risk -a claude-code`. Or copy the skill folder (plugins/wealth-management/skills/historical-risk in JoelLewis/finance_skills) into .claude/skills/historical-risk in your project. Claude Code loads it when a task matches its description.

How do I install Historical Risk in Codex?

Run `npx skills add JoelLewis/finance_skills --skill historical-risk -a codex`. Or copy the skill folder (plugins/wealth-management/skills/historical-risk in JoelLewis/finance_skills) into .agents/skills/historical-risk in your project. Codex loads it when a task matches its description.

Can I use Historical Risk in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add JoelLewis/finance_skills --skill historical-risk -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/historical-risk, .gemini/skills/historical-risk, .github/skills/historical-risk and .opencode/skills/historical-risk in your project.

What does Historical Risk need to run?

Going by SKILL.md and its folder, Historical Risk needs Python for the scripts in its folder and the command-line tools its instructions call (uv, python3 and pip). Our summary lists: Python 3.

Does Historical Risk access the network?

SKILL.md contains no URLs. Its commands use uv and pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Historical Risk safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Historical Risk use?

Historical Risk is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Historical Risk use?

About 2.1k tokens (SKILL.md is roughly 8.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Historical Risk?

Skills that share tags, products or a category with Historical Risk: Technical Analyst (tradermonty/claude-trading-skills, 3k stars), Theme Detector (tradermonty/claude-trading-skills, 3k stars), Creating Financial Models (Chen-zexi/open-ptc-agent, 729 stars) and Stock API (zhangxiangliang/stock-api, 2k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Historical Risk?

JoelLewis (a GitHub user) maintains it in JoelLewis/finance_skills, which has 206 GitHub stars. The repository holds 91 skills in this directory. The repository was last updated on July 18, 2026.

Source: JoelLewis/finance_skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.