time-value-of-money
Calculate present value, future value, NPV, IRR for projects and loans, loan payments, and amortization schedules across all compounding conventions. Use when the user asks about discounting cash flows, valuing an annuity or perpetuity, comparing investments with different timing, building a mortgage amortization table, evaluating whether a project is worth pursuing, or solving for the rate that equates cash flows (project IRR, loan IRR, yield on an investment). Also trigger when users mention 'what is it worth today', 'how much will I have in 20 years', 'monthly payment on a loan', 'discount rate', 'Gordon growth model', 'effective annual rate', 'continuous compounding', or ask how to compare a lump sum versus a stream of payments. For portfolio money-weighted return (dollar-weighted IRR on an investor's contributions and withdrawals), use return-calculations instead.
- Installs
- 717
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/joellewis/finance_skills --skill time-value-of-money- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads time-value-of-money automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Time Value of Money
Core Concepts
Future Value (FV)
The value of a present sum after earning interest for n periods at rate r per period.
$$FV = PV \times (1 + r)^n$$
Future value grows exponentially with time, which is the mathematical basis of compound interest.
Present Value (PV)
The current worth of a future sum, discounted back at rate r for n periods. This is the inverse of future value.
$$PV = \frac{FV}{(1 + r)^n}$$
Present value is the cornerstone of all valuation: a dollar today is worth more than a dollar tomorrow because of the opportunity cost of capital.
Compounding Conventions
Interest can compound at different frequencies. The nominal annual rate r_nom compounded m times per year produces different effective yields.
Discrete compounding (m times per year):
$$FV = PV \times \left(1 + \frac{r_{nom}}{m}\right)^{m \times t}$$
Continuous compounding:
$$FV = PV \times e^{r \times t}$$
Effective Annual Rate (EAR):
$$EAR = \left(1 + \frac{r_{nom}}{m}\right)^m - 1$$
For continuous compounding: EAR = e^(r_nom) - 1
Common frequencies:
| Frequency | m |
|---|---|
| Annual | 1 |
| Semi-annual | 2 |
| Quarterly | 4 |
| Monthly | 12 |
| Daily | 365 |
| Continuous | infinity |
Ordinary Annuity
A series of equal payments made at the end of each period for n periods.
Present Value:
$$PV = PMT \times \frac{1 - (1 + r)^{-n}}{r}$$
Future Value:
$$FV = PMT \times \frac{(1 + r)^n - 1}{r}$$
Annuity Due
A series of equal payments made at the beginning of each period. Each cash flow is one period closer than in an ordinary annuity, so values are scaled by (1 + r).
Present Value:
$$PV = PMT \times \frac{1 - (1 + r)^{-n}}{r} \times (1 + r)$$
Future Value:
$$FV = PMT \times \frac{(1 + r)^n - 1}{r} \times (1 + r)$$
Growing Annuity
A finite series of payments that grow at a constant rate g per period, where g != r.
Present Value:
$$PV = \frac{PMT}{r - g} \times \left[1 - \left(\frac{1 + g}{1 + r}\right)^n\right]$$
This is widely used in equity valuation (e.g., multi-stage dividend discount models) and salary/pension projections.
Perpetuity
An infinite stream of equal payments.
$$PV = \frac{PMT}{r}$$
Growing Perpetuity
An infinite stream of payments growing at constant rate g, where g < r for convergence.
$$PV = \frac{PMT}{r - g}$$
This is the Gordon Growth Model when applied to dividends.
Net Present Value (NPV)
The sum of all discounted cash flows, including the initial investment. A positive NPV indicates value creation.
$$NPV = \sum_{t=0}^{T} \frac{CF_t}{(1 + r)^t}$$
Typically, CF_0 is a negative outflow (initial investment), and subsequent CF_t are inflows.
Internal Rate of Return (IRR)
The discount rate r that makes the NPV of all cash flows exactly zero.
$$0 = \sum_{t=0}^{T} \frac{CF_t}{(1 + r)^t}$$
IRR is solved numerically (Newton-Raphson or bisection) since there is no closed-form solution for general cash flow streams. For conventional cash flows (one sign change), a unique IRR exists.
Amortization
Each payment on an amortizing loan is split into an interest component and a principal component:
- Interest portion:
Interest_t = Balance_{t-1} * r - Principal portion:
Principal_t = PMT - Interest_t - Remaining balance:
Balance_t = Balance_{t-1} - Principal_t
Over time, the interest portion decreases and the principal portion increases.
Key Formulas
| Formula | Expression | Use Case |
|---|---|---|
| Future Value | FV = PV * (1 + r)^n | Compound a lump sum forward |
| Present Value | PV = FV / (1 + r)^n | Discount a future lump sum |
| EAR | (1 + r_nom/m)^m - 1 | Compare rates across compounding frequencies |
| Continuous FV | FV = PV * e^(r*t) | Continuous compounding |
| Ordinary Annuity PV | PMT * [1 - (1+r)^(-n)] / r | Loan payments, lease valuation |
| Annuity Due PV | PMT * [1 - (1+r)^(-n)] / r * (1+r) | Rent, insurance (paid in advance) |
| Growing Annuity PV | PMT/(r-g) * [1 - ((1+g)/(1+r))^n] | Salary streams, growing dividends |
| Perpetuity PV | PMT / r | Preferred stock, consol bonds |
| Growing Perpetuity PV | PMT / (r - g) | Gordon Growth Model |
| NPV | sum(CF_t / (1+r)^t) | Project/investment evaluation |
| IRR | solve: sum(CF_t / (1+r)^t) = 0 | Return metric for uneven cash flows |
Worked Examples
Example 1: Monthly Mortgage Payment
Given: A $300,000 mortgage at a 6.5% annual interest rate, fixed for 30 years, with monthly payments (ordinary annuity).
Calculate: The monthly payment amount.
Solution:
First, convert the annual rate to a monthly rate and years to months:
r_monthly = 0.065 / 12 = 0.00541667
n = 30 * 12 = 360 months
Using the ordinary annuity present value formula, solve for PMT:
PV = PMT * [1 - (1 + r)^(-n)] / r
300,000 = PMT * [1 - (1.00541667)^(-360)] / 0.00541667
Compute the annuity factor:
(1.00541667)^360 = 6.99179
(1.00541667)^(-360) = 0.143010
1 - 0.143010 = 0.856990
0.856990 / 0.00541667 = 158.2108
Solve for PMT:
PMT = 300,000 / 158.2108 = $1,896.20
The monthly mortgage payment is $1,896.20.
Over 30 years, total payments = 360 * $1,896.20 = $682,632, meaning total interest paid is $682,632 - $300,000 = $382,632.
Example 2: NPV of a Project with Uneven Cash Flows
Given: A project requires an initial investment of $50,000 and produces the following cash flows:
- Year 1: $12,000
- Year 2: $15,000
- Year 3: $18,000
- Year 4: $22,000
- Year 5: $25,000
The required rate of return (discount rate) is 10%.
Calculate: The NPV and whether the project should be accepted.
Solution:
Discount each cash flow to present value:
PV(CF_0) = -50,000 / (1.10)^0 = -50,000.00
PV(CF_1) = 12,000 / (1.10)^1 = 10,909.09
PV(CF_2) = 15,000 / (1.10)^2 = 12,396.69
PV(CF_3) = 18,000 / (1.10)^3 = 13,523.67
PV(CF_4) = 22,000 / (1.10)^4 = 15,026.30
PV(CF_5) = 25,000 / (1.10)^5 = 15,523.03
Sum all present values:
NPV = -50,000.00 + 10,909.09 + 12,396.69 + 13,523.67 + 15,026.30 + 15,523.03
NPV = +$17,378.78
Since NPV is positive ($17,378.78), the project creates value and should be accepted. It earns more than the 10% required rate of return.
To find the IRR, we would solve for the rate where NPV = 0. Numerically, the IRR for this cash flow stream is approximately 21.2% (21.18%), well above the 10% hurdle rate.
Common Pitfalls
- Mismatching rate and period frequency: if payments are monthly, the discount rate must be a monthly rate. Divide the annual nominal rate by 12, do not take the 12th root of
(1 + annual rate)unless converting from EAR. - Forgetting the sign convention for cash flows in IRR: outflows (investments) must be negative and inflows (returns) positive, or vice versa, but the convention must be consistent. Incorrect signs produce meaningless IRR results.
- Confusing nominal vs effective rates: a 12% nominal rate compounded monthly produces an EAR of 12.68%, not 12%. Always clarify the compounding basis.
- Off-by-one errors in annuity due vs ordinary annuity: an annuity due shifts all payments one period earlier. Forgetting the
(1 + r)adjustment factor will undervalue annuity-due streams. - Multiple IRR solutions with non-conventional cash flows: when cash flows change sign more than once (e.g., initial outflow, inflows, then a large terminal outflow), Descartes' rule allows up to as many positive real IRR solutions as there are sign changes. In such cases, use NPV profiling or the Modified IRR (MIRR) instead.
Running the Script
scripts/time_value_of_money.py implements every formula above as static methods on a TimeValueOfMoney class (present_value, future_value, npv, irr, annuity_pv, annuity_fv, growing_annuity_pv, perpetuity_pv, fisher_rate, continuous_compounding) plus an AmortizationSchedule class.
- Run:
uv run scripts/time_value_of_money.py(PEP 723 inline metadata; stdlib-only, no third-party dependencies), or simplypython3 scripts/time_value_of_money.py. - Bare invocation (or
--verify) prints a demo of all methods and asserts the worked-example values above (Example 1 mortgage payment = $1,896.20; Example 2 NPV = $17,378.78 and IRR = 21.18%), exiting nonzero on any mismatch. --helplists the available methods and import usage.- For programmatic use, import rather than run:
from time_value_of_money import TimeValueOfMoney, AmortizationSchedule, then call e.g.TimeValueOfMoney.npv(...).
Cross-References
- return-calculations (core plugin): CAGR is a special case of compound growth; portfolio MWR uses the same NPV=0 framework and lives there
- statistics-fundamentals (core plugin): Discount rate estimation often relies on regression (CAPM beta) and distributional assumptions
FAQ
What does the time-value-of-money skill do?
Calculate present value, future value, NPV, IRR for projects and loans, loan payments, and amortization schedules across all compounding conventions. Use when the user asks about discounting cash flows, valuing an annuity or perpetuity, comparing investments with different timing, building a mortgage amortization table, evaluating whether a project is worth pursuing, or solving for the rate that equates cash flows (project IRR, loan IRR, yield on an investment). Also trigger when users mention 'what is it worth today', 'how much will I have in 20 years', 'monthly payment on a loan', 'discount rate', 'Gordon growth model', 'effective annual rate', 'continuous compounding', or ask how to compare a lump sum versus a stream of payments. For portfolio money-weighted return (dollar-weighted IRR on an investor's contributions and withdrawals), use return-calculations instead.
How do I install time-value-of-money?
Run npx skills add https://github.com/joellewis/finance_skills --skill time-value-of-money in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/time-value-of-money/ (personal) or .claude/skills/time-value-of-money/ (project).
Which AI agents can use time-value-of-money?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is time-value-of-money safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains time-value-of-money?
It is published by joellewis in joellewis/finance_skills. It has 717 recorded installs.
More from joellewis/finance_skills
asset-allocation
joellewis/finance_skills
Determine how to distribute capital across asset classes using strategic and tactical allocation frameworks. Use when the user asks about portfolio allocation, mean-variance optimization, Black-Litterman, risk parity, glide paths, or target-date strategies. Also trigger when users mention 'how much in stocks vs bonds', '60/40 portfolio', 'policy portfolio', 'core-satellite', 'liability-driven investing', 'asset-liability matching', or ask how to split their money across investments.
statistics-fundamentals
joellewis/finance_skills
Apply statistical methods to financial data including descriptive statistics, covariance estimation, regression, hypothesis testing, and resampling. Use when the user asks about return distributions, correlation between assets, building a covariance matrix, running a CAPM regression, testing whether alpha is significant, checking if returns are normal, or estimating confidence intervals. Also trigger when users mention 'volatility', 'how correlated are these', 'fat tails', 'skewness', 'R-squared', 'beta of a fund', 'bootstrap a Sharpe ratio', 'shrinkage estimator', 'Ledoit-Wolf', or ask why their optimizer produces unstable weights.
quantitative-valuation
joellewis/finance_skills
Estimate intrinsic value of stocks and companies using DCF, dividend discount models, comparable multiples, and residual income. Use when the user asks about discounted cash flow, DCF models, WACC, terminal value, dividend discount models, comparable multiples, or sum-of-the-parts valuation. Also trigger when users mention 'what is this stock worth', 'fair value estimate', 'Gordon growth model', 'free cash flow valuation', 'cost of equity', 'sensitivity analysis', 'exit multiple', or ask whether a stock is overvalued or undervalued.
finance-psychology
joellewis/finance_skills
Recognize and mitigate cognitive biases that impair financial decisions, and coach clients toward values-driven financial lives. Use when the user asks about behavioral finance, money psychology, loss aversion, overconfidence, herd behavior, or emotional investing. Also trigger when users mention 'why do I panic sell', 'money fights with my spouse', 'I can never save enough', 'fear of investing', 'lifestyle creep', 'keeping up with the Joneses', 'Rich Life', 'money scripts', or ask how emotions affect financial decisions.
commodities
joellewis/finance_skills
Analyze commodity markets including futures curve dynamics, roll yield, and supply/demand fundamentals. Use when the user asks about commodity investing, commodity ETFs, contango, backwardation, roll yield, commodity indices (GSCI, BCOM), or commodities as an inflation hedge. Also trigger when users mention 'oil prices', 'gold as a safe haven', 'agricultural futures', 'convenience yield', 'storage costs', 'natural gas', 'copper demand', or ask why commodity ETF returns differ from spot price changes.
investment-policy
joellewis/finance_skills
Construct comprehensive Investment Policy Statements governing return objectives, risk tolerance, and portfolio constraints. Use when the user asks about building an IPS, setting return objectives, assessing risk tolerance, defining investment constraints, or establishing rebalancing and benchmark policies. Also trigger when users mention 'investment plan', 'policy portfolio', 'risk capacity vs willingness', 'spending rate for an endowment', 'foundation payout', 'manager selection criteria', or ask how to document their investment strategy.
Popular business & finance skills
sales-enablement
coreyhaines31/marketingskills
When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'leave-behind,' 'objection handling,' 'deal-specific ROI analysis,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' 'buyer persona card,' 'battle card,' 'battlecard,' 'competitive one-pager,' 'win-loss analysis,' 'why are we losing deals,' 'loss reasons,' 'how do I respond to this objection,' 'prospect just said,' 'help my sales team,' 'sales materials,' or 'what should I give my sales reps,' 'cold call script,' or 'voicemail script.' Use this for any document or asset that helps a sales team close deals. For public competitor comparison pages, see competitors. For running buyer interviews or churn research, see customer-research. For marketing website copy, see copywriting. For cold outreach emails, see cold-email. For the offer being sold (bonuses, guarantees, pricing structure),
revops
coreyhaines31/marketingskills
When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'outbound pipeline stages,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see emails. For pricing decisions, see pricing.
sales-funnel-blueprint
autonnel/autonnel-skills
Turn an offer into a concrete multi-step sales funnel spec - page-by-page structure, price ladder, copy outline and the metrics each step must hit. Use when asked to build a sales funnel, marketing funnel, landing page flow, lead magnet funnel, webinar funnel, tripwire or VSL funnel, when planning a product launch page flow, or when someone asks "what pages do I need" for selling something online.
pricing
coreyhaines31/marketingskills
When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' 'should I offer a free plan,' 'pricing page teardown,' 'pricing page audit,' 'is my pricing page AI-readable,' or 'can AI read my pricing.' Use this whenever someone is figuring out what to charge, how to structure their plans, or wants to audit a pricing page (for humans and for the AI agents that shortlist tools). For in-app upgrade screens, see paywalls. For offer construction (bonuses, guarantees, value framing, naming) on services/courses/coaching/high-ticket B2B, see offers.
cross-border-ecommerce
nexscope-ai/ecommerce-skills
Cross-border e-commerce expansion advisor. Scores target markets on 8 weighted dimensions (market size, ecommerce penetration, competition, regulatory complexity, logistics infrastructure, payment ecosystem, cultural distance, IP protection), compares 5 fulfillment models with cost and transit data, provides country-by-country tax/duty compliance guides (EU VAT/IOSS, UK VAT, US sales tax, CA GST, AU GST, JP consumption tax), maps local payment preferences by market, and builds a phased expansion roadmap. No API key required.
pricing-strategy
coreyhaines31/marketingskills
When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywall-upgrade-cro.