risk
/risk
Decomposes the volatility of a portfolio into the contribution of each position and, with a factor model, of each factor and of specific risk. Use when asked where the risk in a portfolio comes from, which positions or factors drive volatility, what the portfolio's factor exposures are, or which trades would reduce risk most efficiently.
- Author
- ruujOnChain ↗
- Repository
- HedgeFund-Skills ↗
- Licence
- MIT
- Last repository change
- 07.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/decompose.py
What it does and when to use it
Decomposes the volatility of a portfolio into the contribution of each position and, with a factor model, of each factor and of specific risk. Use when asked where the risk in a portfolio comes from, which positions or factors drive volatility, what the portfolio's factor exposures are, or which trades would reduce risk most efficiently.
Original author description
Decomposes the volatility of a portfolio into the contribution of each position and, with a factor model, of each factor and of specific risk. Use when asked where the risk in a portfolio comes from, which positions or factors drive volatility, what the portfolio's factor exposures are, or which trades would reduce risk most efficiently.
How it works
- Inputs
- Procedure
- Checks
- Output
- Explaining the result
SKILL.md preview
---
name: risk
description: Decomposes the volatility of a portfolio into the contribution of each position and, with a factor model, of each factor and of specific risk. Use when asked where the risk in a portfolio comes from, which positions or factors drive volatility, what the portfolio's factor exposures are, or which trades would reduce risk most efficiently.
license: MIT
compatibility: Requires Python 3.9 or later with numpy and pandas.
metadata:
owner: research
version: "1.0"
---
# Factor risk decomposition
Answers one question: where does the risk in this portfolio come from? Every number comes from `scripts/decompose.py`. Never compute volatility or contributions yourself.
## Inputs
- `weights.csv` with columns `asset, weight`. Weights are fractions of capital; shorts are negative.
- One source of risk, in this order of preference:
1. Factor model: `exposures.csv` (asset rows, factor columns), `factor_cov.csv` (factor by factor), `specific_var.csv` (columns `asset, specific_var`).
2. Full covariance: `cov.csv` (asset by asset).
3. Historical returns: `returns.csv` (date column, then one column of simple returns per asset). Use only when no model is available, and say so in the answer.
- Every input must be known as of the analysis date. Do not mix a covariance estimated today with weights from another day without saying so.
- State the units. Covariances are annual unless `--periods-per-year` says otherwise. Returns mode assumes daily data (252).
If the user has not provided weights or a risk source, ask for them. Never invent covariances or exposures.
## Procedure
1. Confirm the analysis date, the weights file, and which risk source is available.
2. Run the decomposition:
```bash
python scripts/decompose.py --weights weights.csv \
--exposures exposures.csv --factor-cov factor_cov.csv --specific-var specific_var.csv
```
Alternatives: `--cov cov.csv`, or `--returns returns.csv` (add `--periods-per-year 52` for weekly data).
3. Read the JSON. If `passed` is false, report which check failed and stop.
4. Report the total volatility, the largest position contributions, and, in factor mode, the factor and specific split.
## Checks
The script verifies, and the agent reports when any fails:
- The covariance is positive semidefinite.
- Position contributions sum exactly to total volatility.
- In factor mode, factor plus specific contributions sum exactly to total volatility.
## Output
JSON with `results.total_volatility`, `results.positions` (weight, marginal risk, contribution, share), and in factor mode `results.factors`, `results.factor_total`, `results.specific_total`, plus `checks` and `passed`. Shares sum to one; a negative share means the position hedges the rest of the book.
## Explaining the result
- Lead with total volatility and the share explained by the top three positions.
- Contribution equals weight times marginal risk. A position with high marginal risk is where a small trade changes total risk most; a negative marginal risk means adding to that position lowers total risk.
- In factor mode, say how much risk is systematic versus specific, and name the factor with the largest share.
- Volatility is a forecast from the supplied model, not an observed outcome. Name the model or estimation window used.
For the mathematics and conventions, see [references/methodology.md](references/methodology.md).
Files in this package (3)
- SKILL.md 3 KB
- references/methodology.md 2 KB
- scripts/decompose.py 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · ruujOnChain/HedgeFund-Skills | 100 | MIT |
| mlophez/polix-ai | 100 | Apache-2.0 |
| andriiklymiuk/corgi | 100 | MIT |
| cavallinilorenzo/agentic-engineering | 100 | MIT |
Database snapshot: 13.11.2026 · package version beb6b703b78f (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90portfolio-risk
Analyze portfolio risk — technical indicators, sentiment shifts, insider alerts, ESG scores, and volatility metrics. Use when the user asks about portfolio risk, wants to assess holdings, or needs risk/reward analysis. - 95ml4t-position-sizing
Convert signals to position sizes using volatility targeting and risk budgets. Use when scaling trade size relative to conviction and portfolio risk. - 90strategy-specific-vs-shared-risk-budget-allocation
Use when each strategy faces both a standalone volatility cap and a cap on its share of total portfolio risk, decomposing contributions to show which limit binds. Solving for equal-risk weights is risk-parity-allocation-across-strategies. - 100risk-assessment
Assess risk metrics for a stock or position including volatility, beta, VaR, and drawdown analysis. Use when user asks about risk, volatility, beta, VaR, value at risk, drawdown, or position sizing. - 100quant-analysis
Quantitative finance analysis including portfolio optimization, risk modeling, and time series econometrics using jupyter_execute. Use when the user asks about portfolio analysis, stock returns, financial risk, investment optimization, or volatility modeling. - 95quant-factor-risk-pattern-alpha
Use when an agent needs a verified library of OHLCV risk-state and chart-pattern alpha factor Skills for volatility, K-line shape, shock, drawdown, and pressure analysis.