Agent skill

Return Calculations

by JoelLewis in JoelLewis/finance_skills

Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns.

MITAuto-check passedBusiness, Finance & HR

Install Return Calculations

skills CLI
$ npx skills add JoelLewis/finance_skills --skill return-calculations -a claude-code

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

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

At a glance

Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns.

  • The user asks about portfolio performance calculation
  • SKILL.md covers Core Concepts, Worked Examples, Common Pitfalls and Running the Script, plus 1 more section
  • Runs Python scripts from its folder; calls uv and python3
  • Comparing manager returns

What it does

Return Calculations is an agent skill from JoelLewis/finance_skills. Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns. Use when the user asks about portfolio performance calculation, comparing manager returns, linking sub-period returns, understanding why different return methods give different numbers, converting returns across time periods, or computing the IRR of an investor's own contributions and withdrawals. Also trigger when users mention 'how much did I make', 'annual return'…

Its SKILL.md is about 2.2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including scripts (for example `scripts/return_calculations.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 portfolio performance calculation
  • Comparing manager returns
  • Linking sub-period returns
  • Understanding why different return methods give different numbers

Example prompts

  • “s own contributions and withdrawals. Also trigger when users mention”
  • “annual return”
  • “compound growth”
  • “/return-calculations”

Requirements

  • Python 3

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

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use uv, 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

Return Calculations loads about 2.2k tokens when it runs. Until then it costs about 207 tokens; SKILL.md has 935 words of instructions outside code blocks.

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

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). 935 words, ~2,154 tokens.

Download SKILL.mdSave it as .claude/skills/return-calculations/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
return-calculations
description
Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns. Use when the user asks about portfolio performance calculation, comparing manager returns, linking sub-period returns, understanding why different return methods give different numbers, converting returns across time periods, or computing the IRR of an investor's own contributions and withdrawals. Also trigger when users mention 'how much did I make', 'annual return', 'compound growth', 'dollar-weighted vs time-weighted', 'what was my rate of return', 'geometric vs arithmetic mean', 'log returns', or ask about the effect of cash flows on reported returns. For project or loan IRR, NPV, and generic 'solve for the rate' problems, use time-value-of-money instead.

Return Calculations

Core Concepts

Simple (Holding Period) Return

$$R = \frac{V_{end} - V_{begin} + D}{V_{begin}}$$

where D = distributions (dividends, interest) received during the period. If V_end already reflects reinvested distributions, do not add D again.

Mean and Log Return Conventions
  • Arithmetic mean R_a = (1/n) * sum(R_i) — unbiased estimate of the expected single-period return (use for forward-looking inputs, e.g., mean-variance optimization). Always >= geometric mean; overstates realized compound growth.
  • Geometric mean R_g = [prod(1 + R_i)]^(1/n) - 1 — the correct measure of realized multi-period compound growth. The gap below the arithmetic mean approximates sigma^2 / 2 (volatility drag).
  • Log return r = ln(V_end / V_begin) — time-additive (r_total = r_1 + ... + r_n), so preferred for statistical modeling and multi-period aggregation. Convert with R_simple = e^r - 1 and r = ln(1 + R_simple). Log returns are additive across time but NOT across assets.
CAGR (Compound Annual Growth Rate)

$$CAGR = \left(\frac{V_{end}}{V_{begin}}\right)^{1/n} - 1$$

where n is measured in years. The annualized geometric growth rate between two valuations with no intermediate cash flows.

Time-Weighted Return (TWR)

Chain-links sub-period returns calculated between each external cash flow, removing the effect of cash flow timing. TWR measures the manager's investment skill independent of investor deposit/withdrawal decisions, and is the GIPS standard for manager performance.

$$1 + R_{TWR} = \prod_{i=1}^{n}(1 + R_i), \qquad R_i = \frac{V_{end,i}}{V_{begin,i} + CF_i} - 1$$

Exact TWR requires a portfolio valuation on every cash flow date.

Modified Dietz Return

When valuations on each cash flow date are unavailable, Modified Dietz approximates the period return by day-weighting each external cash flow within the period:

$$R_{MD} = \frac{V_{end} - V_{begin} - CF_{net}}{V_{begin} + \sum_i CF_i \times w_i}, \qquad w_i = \frac{CD - D_i}{CD}$$

where CF_net = sum of external cash flows, CD = calendar days in the period, and D_i = day of flow i (so w_i is the fraction of the period the flow was invested). It is a money-weighted approximation; chain-linking Modified Dietz sub-period returns approximates TWR. Accuracy degrades when flows are large relative to portfolio value or markets are volatile within the period — revalue on large-flow dates instead.

Money-Weighted Return (MWR / IRR)

The internal rate of return that sets the NPV of all investor cash flows (contributions, withdrawals, and terminal value) to zero:

$$0 = \sum_{t=0}^{T} \frac{CF_t}{(1 + r)^t}$$

MWR reflects the actual investor experience because it is sensitive to the timing and magnitude of cash flows. Solved numerically (Newton-Raphson or bisection).

Annualization

$$R_{annual} = (1 + R_{period})^{periods_per_year} - 1$$

For example, a 2% quarterly return annualizes to (1.02)^4 - 1 = 8.24%.

Sub-Period Linking

$$(1 + R_{total}) = \prod_{i=1}^{n}(1 + R_i)$$

The foundational identity behind TWR and CAGR.

Worked Examples

Example 1: Computing CAGR from a 5-Year Investment

Given: An investment of $10,000 grows to $16,105.10 over exactly 5 years with no intermediate cash flows.

Calculate: The compound annual growth rate (CAGR).

Solution:

CAGR = (V_end / V_begin)^(1/n) - 1
CAGR = (16,105.10 / 10,000)^(1/5) - 1
CAGR = (1.610510)^(0.2) - 1
CAGR = 1.10 - 1
CAGR = 0.10 = 10%

The investment grew at a compound annual rate of 10% per year.

Verification: $10,000 * (1.10)^5 = $10,000 * 1.61051 = $16,105.10

Example 2: TWR vs MWR Divergence with Poorly Timed Cash Flow

Given: A fund has the following history:

  • Start of Year 1: Portfolio value = $100,000
  • End of Year 1: Portfolio value = $120,000 (return = +20%)
  • Start of Year 2: Investor deposits $100,000, bringing portfolio to $220,000
  • End of Year 2: Portfolio value = $198,000 (return = -10%)

Calculate: Both TWR and MWR, and explain the divergence.

Solution:

Time-Weighted Return (TWR):

Sub-period 1 return: R_1 = (120,000 - 100,000) / 100,000 = +20%
Sub-period 2 return: R_2 = (198,000 - 220,000) / 220,000 = -10%

TWR (cumulative) = (1 + 0.20) * (1 + (-0.10)) - 1
                  = 1.20 * 0.90 - 1
                  = 1.08 - 1
                  = +8.0%

TWR (annualized) = (1.08)^(1/2) - 1 = 3.92%

Money-Weighted Return (MWR / IRR): Cash flows from the investor's perspective:

  • t=0: -$100,000 (initial investment)
  • t=1: -$100,000 (additional deposit)
  • t=2: +$198,000 (terminal value)

Solve: -100,000 + (-100,000)/(1+r) + 198,000/(1+r)^2 = 0

This is quadratic in x = 1/(1+r); the positive root gives r = -0.66815% (verifiable with the bundled script or any IRR solver).

NPV check at r = -0.0066815:

-100,000 + (-100,000)/0.9933185 + 198,000/0.9933185^2
= -100,000 - 100,672.65 + 200,672.65
= 0.00  (exact)

The MWR is approximately -0.67% annualized.

Interpretation: The TWR of +3.92% annualized reflects the manager's skill: the fund gained 20% then lost 10%, netting +8% over two years. The MWR of approximately -0.67% reflects the investor's experience: more money was at risk during the losing year (Year 2) because of the large deposit, so the investor's dollar-weighted outcome was slightly negative. This divergence highlights why TWR is preferred for evaluating manager performance, while MWR better describes the specific investor's realized result.

Show full SKILL.md (287 more words)Show less

Common Pitfalls

  • Confusing arithmetic and geometric means: the arithmetic mean is always greater than or equal to the geometric mean (AM-GM inequality). Using arithmetic mean to project compounded growth overstates terminal wealth.
  • Using arithmetic mean for multi-period compounding: always use geometric mean or CAGR when describing compound growth over multiple periods.
  • Annualizing returns from very short periods: annualizing a 2% weekly return yields (1.02)^52 - 1 = 180%, which amplifies noise and is misleading. Annualization is most meaningful for periods of at least one year.
  • Ignoring cash flow timing when TWR is appropriate: MWR conflates manager skill with investor timing decisions. Use TWR for manager evaluation.
  • Double-counting dividends: if the ending value V_end already includes reinvested dividends, do not add D separately in the holding period return formula.
  • Trusting Modified Dietz with large intra-period flows: when a single flow exceeds roughly 10% of portfolio value, revalue the portfolio on the flow date rather than day-weighting.

Running the Script

scripts/return_calculations.py provides a Returns class with static methods for every formula above (holding period return, TWR, MWR/IRR via Newton's method, Modified Dietz is straightforward to compose from these, CAGR, annualization, linking, arithmetic/geometric means, log-return conversions).

  • Run: uv run scripts/return_calculations.py (PEP 723 inline metadata resolves numpy automatically), or python3 scripts/return_calculations.py with numpy installed.
  • Bare invocation (or --verify) prints a demo of all functions and asserts the worked-example values above (Example 1 CAGR = 10%, Example 2 TWR = +8.0% cumulative / 3.92% annualized, MWR = -0.6682%), exiting nonzero on any mismatch.
  • --help lists the available functions and import usage.
  • For programmatic use, import rather than run: from return_calculations import Returns.

Cross-References

  • time-value-of-money (core plugin): NPV, IRR, and discounting concepts overlap with MWR calculations; owns project/loan IRR
  • statistics-fundamentals (core plugin): Arithmetic and geometric means, return distribution analysis

© 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/core/skills/return-calculations of JoelLewis/finance_skills.

  • SKILL.md
  • scripts/return_calculations.py

Open the folder on GitHubat commit 5c498ea

Compare with similar skills

Return Calculations 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.

Return Calculations compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Return Calculations this skillJoelLewis/finance_skills205—~2.2kAutomated safety check: PassMIT
Technical Analysttradermonty/claude-trading-skills3k4 repos~4.6kAutomated safety check: PassMIT
Theme Detectortradermonty/claude-trading-skills3k2 repos~4.9kAutomated safety check: PassMIT
Creating Financial ModelsChen-zexi/open-ptc-agent7293 repos~1.3kAutomated safety check: PassMIT
Stock APIzhangxiangliang/stock-api2k—~507Automated 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 4 repos~4.6k tokens
    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
  • 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 3 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
  • Itr Wala

    karanb192/itr-wala

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

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

    zillionare/zillionare

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

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

More from JoelLewis/finance_skills

All 91 skills in this repo
  • 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
  • Diversification

    JoelLewis/finance_skills

    Build diversified portfolios using correlation analysis, efficient frontier construction, and factor-based diversification.

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

Questions about Return Calculations

What does Return Calculations do?

Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns. Return Calculations is an agent skill from JoelLewis/finance_skills. Compute and compare investment return metrics including TWR, MWR (dollar-weighted IRR on portfolio cash flows), CAGR, and annualized returns.

When should I use Return Calculations?

Return Calculations fits situations like: the user asks about portfolio performance calculation; comparing manager returns; linking sub-period returns; understanding why different return methods give different numbers.

How do I install Return Calculations in Claude Code?

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

How do I install Return Calculations in Codex?

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

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

What does Return Calculations need to run?

Going by SKILL.md and its folder, Return Calculations needs Python for the scripts in its folder and the command-line tools its instructions call (uv and python3). Our summary lists: Python 3.

Does Return Calculations access the network?

SKILL.md contains no URLs. Its commands use uv, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Return Calculations 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 Return Calculations use?

Return Calculations 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 Return Calculations use?

About 2.2k tokens (SKILL.md is roughly 8.6k 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 Return Calculations?

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

Who maintains Return Calculations?

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.