Skip to content
Skills Library
Finance & accounting · Analysis

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.

Licence
MIT
Last repository change
07.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Inputs
  2. Procedure
  3. Checks
  4. Output
  5. Explaining the result
Original SKILL.md headings · 49 lines, 418 words
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

RepositoryScoreLicence
This page · ruujOnChain/HedgeFund-Skills100MIT
mlophez/polix-ai100Apache-2.0
andriiklymiuk/corgi100MIT
cavallinilorenzo/agentic-engineering100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.