How to use the risk-analysis agent skill: VaR, CVaR, drawdown

What does the risk-analysis skill make the agent do?

Without the skill, an agent may write risk formulas from memory each time, and small differences in sign or sorting can change the answer. With the skill installed, the agent is told to call one shared set of functions in the Vibe-Trading repository (src/quantlib/risk.py) instead of retyping the maths.

• Historical VaR and CVaR (expected shortfall) from a return series
• Parametric (normal) VaR for comparison
• Maximum drawdown, with peak, trough and recovery dates
• Monte Carlo price paths using geometric Brownian motion, and summaries of those paths
• Extreme-value tail-risk fitting and historical scenario stress tests

How do you install the risk-analysis skill?

Download the skill ZIP from this page and unzip it. The skill folder contains a single file, SKILL.md. Choose one of these locations depending on how you use your agent.

For a personal install available in every project, unzip the folder into ~/.claude/skills/. To limit it to one project, unzip it into that project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings, then Capabilities, then Skills.

• Personal: ~/.claude/skills/ (available everywhere)
• Project only: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

What do you need before the skill works?

The skill folder does not include the code it refers to. The functions live in src/quantlib/risk.py, which belongs to the Vibe-Trading repository and must be available to your Python environment. The skill also depends on Python libraries used by that code. The source does not list them, but pandas and scipy are implied by the code.

The skill's own file imports these functions, so this is the set the agent will try to use:

• A Python environment with the Vibe-Trading repository's src/quantlib/risk.py available
• Python libraries used by that module, such as pandas and scipy (inferred, not listed in the file)

How do you trigger the skill with a natural request?

Ask in plain language and say what data you have and what you want measured. The agent should load the skill when your request involves downside risk, VaR, CVaR, drawdown, simulation or stress tests. Giving the confidence level, horizon and data format up front avoids follow-up questions.

The examples below are illustrative phrasings, not required commands.

• Calculate the 1-day 95% historical VaR and CVaR of this daily return series, and tell me the sign convention.
• What is the maximum drawdown of this equity curve, and when did it recover?
• Simulate 10,000 GBM paths for 252 days with annual drift 0.10 and volatility 0.20, using a fixed seed, and report the 95% VaR.
• Compare parametric and historical 99% VaR for this backtest and explain any gap.

How should you read the results?

The skill uses one sign convention across all functions: a loss is a positive number. A VaR of 0.028 means a 2.8% loss. Returns keep their natural sign, so a bad return is negative. Maximum drawdown is also positive, meaning the decline from peak to trough.

VaR is not clipped at zero. If the tail of a sample contains no actual loss, the reported loss is negative, which means a gain. CVaR should never be below VaR when both come from the same sample and confidence level.

• VaR 0.028 = 2.8% loss
• CVaR 0.042 = average loss of 4.2% in the tail
• Max drawdown 0.325 = fell 32.5% below its running peak
• Negative VaR = no loss in the tail, not an error
• Returns such as mean_return are signed and negative when bad

What are the safety notes?

The skill runs Python scripts, so review any code before you run it in a sensitive environment. The source states that the skill does not use the network. Its results are statistical estimates from historical or simulated data, and the source warns they can badly understate real losses in unusual markets.

Do not use the output for personal investment or trading decisions. The skill is a methodology guide, not a certified implementation, so it is not suitable for regulatory or compliance reporting that needs audited models.

• Runs scripts: yes
• Uses network: no
• Not for personal investment or trading decisions
• Not for regulatory or compliance reporting that requires audited models

What tips help you get reliable results?

Always fix the random seed in Monte Carlo runs. Without a seed, each run draws fresh randomness and your numbers cannot be regenerated. The seed is keyword-only in monte_carlo_gbm, so you must pass it by name.

Quote parametric and historical VaR at 99% when the goal is to expose tail risk. At 95%, parametric VaR is usually the higher figure, which is expected for fat-tailed data and not a sign of a bug. For multi-day horizons, the skill scales by the square-root-of-time rule, which holds only if returns are independent and identically distributed.

• Pass seed=... to monte_carlo_gbm every time
• Use steps_per_year if your step is not a 252-day trading year
• Pass a strictly positive equity series to max_drawdown_analysis; rebase a signed PnL series first
• Use the *_periods counts for drawdown duration if your index is not a DatetimeIndex