How to use the performance-attribution agent skill

What the skill makes the agent do

The skill covers Brinson sector and stock-selection attribution, factor alpha and beta decomposition, market-timing evaluation, and a benchmark comparison framework. Brinson attribution splits excess return into allocation, selection and interaction effects by sector. Factor analysis splits return into exposures such as market beta, size, value and momentum, plus an alpha term.

The skill tells the agent to use the project's tested Python functions in src/quantlib/attribution.py instead of writing the formulas from scratch. It also tells the agent to explain how multi-period results are linked, and to report any gap between calculated and reported returns rather than hiding it.

Install the skill (ZIP download or Claude apps upload)

The skill is a single file, SKILL.md. Download the ZIP from the skill's page on this directory, then choose one of these routes.

For Claude Code, unzip the download into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill limited to one project. For the Claude apps, upload the ZIP under Settings → Capabilities → Skills.

• Personal use across projects: ~/.claude/skills/
• Single project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Set up the Vibe-Trading repository

The skill calls functions that live in the Vibe-Trading repository, so the repository must be available to the agent. The skill expects src/quantlib/attribution.py to exist at that path, and the agent imports from it as src.quantlib.attribution. Run the agent from the repository root so that import path resolves.

The skill does not contain the calculations themselves. Without the repository, the agent has nothing to call.

Trigger the skill with natural requests

You do not need a special command. Describe what you want in plain language and include your data. The agent should recognise a request about return drivers, attribution, alpha, beta or market timing and load the skill.

Good requests name the analysis and supply the inputs, for example: break down this month's excess return versus the benchmark into allocation, selection and interaction by sector, using the weights and returns below. Or: run a Fama-French style factor regression on these 36 monthly returns against the market and tell me whether the alpha is significant. Or: check whether this fund showed market-timing ability using the Treynor-Mazuy model.

• Name the method: Brinson, factor regression, Treynor-Mazuy, Henriksson-Merton, or capture ratios
• Provide the data: portfolio and benchmark weights and sector returns, or periodic return series
• Ask for the reconciliation: state the reported fund return so any gap is quantified

Read a worked Brinson example

The skill's example is a single-period, four-sector Brinson-Fachler calculation. Portfolio and benchmark weights must carry the same total. The function raises an error rather than returning a decomposition that does not tie out.

The three effects sum exactly to the active return: 0.0045 + 0.0015 + 0.0045 = 0.0105. A residual inside the decomposition should not happen. A gap between this decomposition and the reported fund return is normal, because trading, cash drag, corporate actions and FX can move the real return away from what the snapshot implies. The skill asks the agent to attribute that gap to its source.

• A benchmark sector you did not hold shows zero selection and zero interaction, so the whole effect falls into allocation.
• You cannot show stock-picking skill in a sector you never owned.

Link multi-period results correctly

Single-period effects add up, but returns compound, so summing each period's effects does not reproduce the compounded active return. The skill's example shows summed active returns of 2.85% against a compounded 3.0318% over three periods. The error grows with horizon and return level.

The skill recommends Carino logarithmic linking through carino_link. It is residual-free, and each period's scaling factor depends only on that period's total returns, so sector bucketing cannot steer the result. Arithmetic linking is acceptable only if you explicitly report the residual.

• linked.scaling_factors gives one scaling factor per period so a report can be audited
• Allocation, selection and interaction of the linked result sum to the linked active return

Run factor and market-timing analysis

For factor work, the skill describes an alpha-beta regression using OLS with at least 60 data points, and a multi-factor extension with market, size, value and momentum factors. For China A-shares, the skill proposes proxies such as CSI 300 for the market and CSI 500 minus CSI 300 for size.

For timing, the skill covers the Treynor-Mazuy model, where a positive and significant squared-excess-return term suggests timing ability, and the Henriksson-Merton model, where a positive term suggests higher beta in bull markets. It also describes bull and bear capture ratios.

• Alpha-beta: R_p = α + β × R_m + ε, with at least 60 data points
• Treynor-Mazuy: adds a squared market excess return term γ
• Henriksson-Merton: adds a max(R_m − R_f, 0) term γ
• Capture ratios: above 100% in bull markets and below 100% in bear markets indicate good performance

Safety notes: scripts and network

The skill runs scripts, since its calculations are Python code in the repository. It does not use the network, so it works only with the weight and return data you give it. Review the code in src/quantlib/attribution.py before you rely on it in production, as you would with any code the agent runs.

Results are only as good as the inputs. The skill analyses what you supply and does not check the data's source or accuracy.

• Runs scripts: yes
• Uses network: no
• Keep the repository and skill files under version control if results feed reports

Tips for reliable results

Give the agent the reported fund return along with the weights, so it can quantify the reconciliation gap. Check that portfolio and benchmark weights each sum to the same total before you run the analysis. For factor regressions, use at least 60 observations, and read the t-statistics and R² alongside the alpha.

• Use the same sector classification for portfolio and benchmark
• Prefer carino_link over summing periods
• Treat a significant alpha as a hypothesis to test, not a conclusion