Agent skill

Performance Attribution

by JoelLewis in JoelLewis/finance_skills

Decompose portfolio returns into explainable components to identify where value was added or lost.

MITAuto-check passedBusiness, Finance & HR

Install Performance Attribution

skills CLI
$ npx skills add JoelLewis/finance_skills --skill performance-attribution -a claude-code

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

GitHub CLI
$ gh skill install JoelLewis/finance_skills performance-attribution --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/performance-attribution .claude/skills/performance-attribution && 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
performance-attribution
GitHub stars
205
Token cost
~2.5k tokens
SKILL.md length
1,162 words
Files
2 (incl. scripts)
Skills in repo
91
Repo updated
First seen
Licence
MIT

At a glance

Decompose portfolio returns into explainable components to identify where value was added or lost.

  • Works in 9 steps: Total portfolio return: 0.35×15% +… → Total active return: 10.45% - 7.50% =… → Tech allocation effect: (0.35 - 0.25) ×… → …
  • The user asks about Brinson attribution
  • 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

What it does

Performance Attribution is an agent skill from JoelLewis/finance_skills. Decompose portfolio returns into explainable components to identify where value was added or lost. Use when the user asks about Brinson attribution, allocation vs selection effects, factor-based attribution, fixed-income attribution, or currency attribution. Also trigger when users mention 'what drove my returns', 'was it stock picking or sector bets', 'alpha decomposition', 'multi-period linking', 'interaction effect', 'active return breakdown', or ask why their portfolio outperformed or underperformed the…

Its SKILL.md is about 2.5k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/performance_attribution.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 Brinson attribution
  • Allocation vs selection effects
  • Factor-based attribution
  • Fixed-income attribution

Example prompts

  • “what drove my returns”
  • “was it stock picking or sector bets”
  • “alpha decomposition”
  • “/performance-attribution”

Requirements

  • Python 3

Workflow steps

9 steps, taken from the first numbered list in SKILL.md.

  1. Total portfolio return: 0.35×15% + 0.65×8% = 5.25% + 5.20% = 10.45%.
  2. Total active return: 10.45% - 7.50% = 2.95%.
  3. Tech allocation effect: (0.35 - 0.25) × (12% - 7.5%) = 0.10 × 4.5% = +0.45% (overweight a sector that beat the benchmark).
  4. Tech selection effect: 0.25 × (15% - 12%) = 0.25 × 3% = +0.75% (stock picks in Tech beat Tech benchmark).
  5. Tech interaction effect: (0.35 - 0.25) × (15% - 12%) = 0.10 × 3% = +0.30% (overweight AND outperformed).
  6. Healthcare allocation effect: (0.65 - 0.75) × (6% - 7.5%) = -0.10 × -1.5% = +0.15% (underweight a sector that lagged the benchmark).
  7. Healthcare selection effect: 0.75 × (8% - 6%) = 0.75 × 2% = +1.50% (stock picks in Healthcare beat Healthcare benchmark).
  8. Healthcare interaction effect: (0.65 - 0.75) × (8% - 6%) = -0.10 × 2% = -0.20% (underweight but outperformed — interaction is negative).
  9. Totals: Allocation = 0.45 + 0.15 = 0.60%. Selection = 0.75 + 1.50 = 2.25%. Interaction = 0.30 + (-0.20) = 0.10%. Sum = 0.60 + 2.25 + 0.10…

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

Performance Attribution loads about 2.5k tokens when it runs. Until then it costs about 137 tokens; SKILL.md has 1,162 words of instructions outside code blocks.

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

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). 1,162 words, ~2,488 tokens.

Download SKILL.mdSave it as .claude/skills/performance-attribution/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
performance-attribution
description
Decompose portfolio returns into explainable components to identify where value was added or lost. Use when the user asks about Brinson attribution, allocation vs selection effects, factor-based attribution, fixed-income attribution, or currency attribution. Also trigger when users mention 'what drove my returns', 'was it stock picking or sector bets', 'alpha decomposition', 'multi-period linking', 'interaction effect', 'active return breakdown', or ask why their portfolio outperformed or underperformed the benchmark.

Performance Attribution

Core Concepts

Brinson-Fachler Attribution (Single Period)

The classic equity attribution model decomposes active return (portfolio return minus benchmark return) into three effects:

  • Allocation effect: Value added by over/underweighting sectors relative to the benchmark
    • A_i = (w_p,i - w_b,i) × (R_b,i - R_b)
    • Rewards overweighting sectors that outperform the total benchmark
  • Selection effect: Value added by picking better securities within each sector
    • S_i = w_b,i × (R_p,i - R_b,i)
    • Rewards outperforming the sector benchmark regardless of weight
  • Interaction effect: Combined effect of both overweighting and outperforming (or vice versa)
    • I_i = (w_p,i - w_b,i) × (R_p,i - R_b,i)
    • Captures the joint benefit of overweighting a sector AND selecting better securities in it
  • Total active return: R_p - R_b = Σ A_i + Σ S_i + Σ I_i

Where: w_p,i = portfolio weight in sector i, w_b,i = benchmark weight in sector i, R_p,i = portfolio return in sector i, R_b,i = benchmark return in sector i, R_b = total benchmark return.

Multi-Period Attribution

Single-period attribution does not compound across periods. Geometric linking methods are required:

  • Carino method: Applies a smoothing factor to make arithmetic effects compound to the correct geometric total
  • Menchero method: Uses a logarithmic approach for smoother decomposition
  • GRAP (Geometric Return Attribution Program): Converts arithmetic effects to geometric equivalents
  • Key principle: the sum of linked attribution effects must equal the total geometric active return over the full period
Factor-Based Attribution

Decomposes returns into exposures to systematic risk factors:

  • Model: R_p = Σ β_k × F_k + α
    • β_k = portfolio's exposure (loading) to factor k
    • F_k = return of factor k during the period
    • α = residual return unexplained by factors (true alpha)
  • Common factors: Market (MKT), Size (SMB), Value (HML), Momentum (UMD), Quality (QMJ), Low Volatility (BAB)
  • Factor contribution: β_k × F_k for each factor
  • Active factor contribution: (β_p,k - β_b,k) × F_k
  • The model chosen (Fama-French 3, Carhart 4, Fama-French 5, Barra, Axioma) affects results
Fixed-Income Attribution

Decomposes bond portfolio returns into component sources:

  • Yield return (income): Coupon income accrued during the period (yield × time)
  • Roll return: Price appreciation as bonds "roll down" the yield curve toward maturity
  • Curve change return: Impact of parallel and non-parallel yield curve shifts
    • Duration effect: -D × Δy (parallel shift)
    • Curve reshaping: key rate duration contributions
  • Spread change return: Impact of credit spread changes: -spread_duration × Δspread
  • Credit/default return: Losses from defaults or credit events
  • Residual: Unexplained return (convexity effects, model error)
Currency Attribution

For international portfolios, returns decompose into:

  • Local return: Return of the asset in its local currency
  • Currency return: Gain/loss from exchange rate movements
  • Cross-product: Interaction between local return and currency return
  • Total return (base currency): R_base ≈ R_local + R_currency + R_local × R_currency
  • Hedged return: Local return + hedge cost (forward premium/discount)
  • Attribution of active currency decisions: actual currency exposure vs benchmark currency exposure
Holdings-Based vs Returns-Based Attribution
  • Holdings-based: Uses actual portfolio positions; more accurate but requires detailed holdings data at each evaluation point
  • Returns-based (style analysis): Regresses portfolio returns against a set of style indices (e.g., Sharpe style analysis); less precise but requires only return series
  • Transaction-based: Most accurate; accounts for intra-period trading by using actual transaction records

Key Formulas

FormulaExpressionUse Case
Allocation effect (sector i)A_i = (w_p,i - w_b,i) × (R_b,i - R_b)Sector weighting decisions
Selection effect (sector i)S_i = w_b,i × (R_p,i - R_b,i)Security selection within sector
Interaction effect (sector i)I_i = (w_p,i - w_b,i) × (R_p,i - R_b,i)Joint allocation-selection effect
Total active returnR_p - R_b = Σ(A_i + S_i + I_i)Sum of all effects equals active return
Factor return contributionC_k = β_k × F_kReturn from factor k exposure
Duration effectΔP/P ≈ -D × ΔyBond price change from yield shift
Currency returnR_fx = (S_end - S_start) / S_startExchange rate impact

Worked Examples

Example 1: Brinson-Fachler equity attribution

Given: Two-sector portfolio (Tech and Healthcare). Portfolio: 35% Tech (returned 15%), 65% Healthcare (returned 8%). Benchmark: 25% Tech (returned 12%), 75% Healthcare (returned 6%). Total benchmark return: 0.25×12% + 0.75×6% = 7.5%. Calculate: Allocation, selection, and interaction effects for each sector, and total active return. Solution:

  1. Total portfolio return: 0.35×15% + 0.65×8% = 5.25% + 5.20% = 10.45%.
  2. Total active return: 10.45% - 7.50% = 2.95%.
  3. Tech allocation effect: (0.35 - 0.25) × (12% - 7.5%) = 0.10 × 4.5% = +0.45% (overweight a sector that beat the benchmark).
  4. Tech selection effect: 0.25 × (15% - 12%) = 0.25 × 3% = +0.75% (stock picks in Tech beat Tech benchmark).
  5. Tech interaction effect: (0.35 - 0.25) × (15% - 12%) = 0.10 × 3% = +0.30% (overweight AND outperformed).
  6. Healthcare allocation effect: (0.65 - 0.75) × (6% - 7.5%) = -0.10 × -1.5% = +0.15% (underweight a sector that lagged the benchmark).
  7. Healthcare selection effect: 0.75 × (8% - 6%) = 0.75 × 2% = +1.50% (stock picks in Healthcare beat Healthcare benchmark).
  8. Healthcare interaction effect: (0.65 - 0.75) × (8% - 6%) = -0.10 × 2% = -0.20% (underweight but outperformed — interaction is negative).
  9. Totals: Allocation = 0.45 + 0.15 = 0.60%. Selection = 0.75 + 1.50 = 2.25%. Interaction = 0.30 + (-0.20) = 0.10%. Sum = 0.60 + 2.25 + 0.10 = 2.95% ✓.
Show full SKILL.md (398 more words)Show less
Example 2: Factor-based attribution

Given: A fund has factor loadings: β_mkt = 1.1, β_smb = 0.3, β_hml = -0.2. During the period: MKT = 5%, SMB = 2%, HML = -1%. Risk-free rate = 1%. Fund excess return = 7%. Calculate: Factor contributions and alpha. Solution:

  1. Market contribution: 1.1 × 5% = 5.50%.
  2. Size (SMB) contribution: 0.3 × 2% = 0.60%.
  3. Value (HML) contribution: -0.2 × (-1%) = +0.20%.
  4. Total factor-explained return: 5.50 + 0.60 + 0.20 = 6.30%.
  5. Alpha (residual): 7.00% - 6.30% = +0.70%.
  6. Interpretation: The fund's excess return of 7% is mostly explained by above-market beta (5.5%) and a small-cap tilt (0.6%). The negative value loading helped (+0.2%) as value underperformed. After accounting for all factors, the manager generated 0.70% of true alpha.

Common Pitfalls

  • Interaction effect is hard to interpret — some attribution models fold it into allocation or selection, which changes reported results significantly
  • Multi-period attribution requires geometric linking — simple arithmetic attribution does not compound correctly and residuals grow over time
  • Returns-based attribution (style analysis) may not reflect actual holdings, especially for managers who trade actively or change style
  • Factor attribution results depend heavily on the chosen factor model — different models yield different alpha estimates
  • Currency attribution is often overlooked in international portfolios, hiding or inflating apparent skill
  • Survivorship bias in manager evaluation: only surviving funds are analyzed, overstating average skill
  • Confusing gross-of-fee and net-of-fee returns when comparing to benchmarks
  • Using inappropriate benchmarks that do not match the portfolio's investment universe

Cross-References

  • investment-policy (wealth-management plugin): Benchmark selection in IPS directly feeds performance attribution analysis
  • tax-efficiency (wealth-management plugin): After-tax attribution requires adjusting returns for tax impact
  • savings-goals (wealth-management plugin): Attribution helps assess whether investment strategy is on track to meet goals
  • liquidity-management (wealth-management plugin): Cash drag from liquidity reserves affects portfolio-level attribution
  • client-review-prep (advisory-practice plugin): attribution analysis highlights are key talking points in client review meetings
  • tax-loss-harvesting (wealth-management plugin): tax alpha from TLH should be tracked and attributed separately

Running the script

Run with uv run scripts/performance_attribution.py (the PEP 723 header resolves numpy automatically) or with python3 scripts/performance_attribution.py after pip install numpy scipy. A bare run prints three demos: the Brinson-Fachler attribution from Worked Example 1, an OLS factor attribution on seeded synthetic data, and Carino multi-period linking. Use --verify to assert outputs match this skill's worked example numbers (exit code 0 on PASS) and --help for an overview of the classes. The file is primarily meant to be imported as a module (e.g., from performance_attribution import BrinsonFachler).

© 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/performance-attribution of JoelLewis/finance_skills.

  • SKILL.md
  • scripts/performance_attribution.py

Open the folder on GitHubat commit 5c498ea

Compare with similar skills

Performance Attribution 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.

Performance Attribution compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Performance Attribution this skillJoelLewis/finance_skills205—~2.5kAutomated safety check: PassMIT
Technical Analysttradermonty/claude-trading-skills3k5 repos~4.6kAutomated safety check: PassMIT
Creating Financial ModelsChen-zexi/open-ptc-agent7294 repos~1.3kAutomated safety check: PassMIT
Stock APIzhangxiangliang/stock-api2k—~507Automated safety check: PassMIT
Theme Detectortradermonty/claude-trading-skills3k2 repos~4.9kAutomated 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 5 repos~4.6k 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 4 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 today
    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
  • Itr Wala

    karanb192/itr-wala

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

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

    zillionare/zillionare

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

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

More from JoelLewis/finance_skills

All 91 skills in this repo
  • Equities

    JoelLewis/finance_skills

    Analyze equity securities, factor models, and equity portfolio construction.

    205 GitHub starsUsed in 1 repo~2.2k tokens
    Auto-check passed
  • Asset Allocation

    JoelLewis/finance_skills

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

    205 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.

    205 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.

    205 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.

    205 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.

    205 GitHub stars~2.5k tokensUpdated 2 mo ago
    Auto-check passed

Questions about Performance Attribution

What does Performance Attribution do?

Decompose portfolio returns into explainable components to identify where value was added or lost. Performance Attribution is an agent skill from JoelLewis/finance_skills. Decompose portfolio returns into explainable components to identify where value was added or lost.

When should I use Performance Attribution?

Performance Attribution fits situations like: the user asks about Brinson attribution; allocation vs selection effects; factor-based attribution; fixed-income attribution.

How do I install Performance Attribution in Claude Code?

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

How do I install Performance Attribution in Codex?

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

Can I use Performance Attribution 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 performance-attribution -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/performance-attribution, .gemini/skills/performance-attribution, .github/skills/performance-attribution and .opencode/skills/performance-attribution in your project.

What does Performance Attribution need to run?

Going by SKILL.md and its folder, Performance Attribution 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 Performance Attribution 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 Performance Attribution 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 Performance Attribution use?

Performance Attribution 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 Performance Attribution use?

About 2.5k tokens (SKILL.md is roughly 10k 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 Performance Attribution?

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

Who maintains Performance Attribution?

JoelLewis (a GitHub user) maintains it in JoelLewis/finance_skills, which has 205 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.