finance-skills

Auditable public-company research for AI coding agents. One skill, 10 focused workflows, 29 deterministic detector rules, and a fail-closed financial evidence engine.

Quick start: install the skill, install its live-data dependency, then run /finance screen NVDA (or $finance screen NVDA in Codex).

curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- claude
python -m pip install "yfinance>=0.2"

The engine computes and labels the numbers. Your agent interprets the evidence. Neither is allowed to silently do the other's job.

Why finance-skills?

Company-analysis agents tend to fail in two ways: they invent plausible numbers, or they return a data dump without an argument. finance-skills separates those jobs and tests the boundary.

• Deterministic fact layer. Revenue growth, margins, cash conversion, Rule of 40, net debt, and valuation multiples come from Python—not model arithmetic.
• Fail-closed evidence. Missing debt is not zero. Period and currency mismatches block affected calculations. Disabled analyses stay visible.
• Analyst layer with a point of view. The agent must weigh conflicting evidence, state the assumption doing the most work, and explain what would change the conclusion.
• Auditable provenance. Material values preserve company, period, currency, source, confidence, data mode, formula, and evidence paths.
• Read-only boundary. No brokerage integrations, trade execution, position sizing, guaranteed returns, or personalized buy/sell instructions.

See it in action

Claude Code answering “Is NVDA overvalued?” with live data:

Watch the full-quality video or the engine-only terminal demo.

What's included

The skill: finance

All research flows use one skill and one evidence contract:

Use $finance ... in Codex. A ticker by itself, or a generic “analyze” request, routes to screen.

Usage examples

/finance screen NVDA
/finance underwrite CRWV
/finance audit PLTR
/finance compare AMD NVDA
/finance stress NBIS
/finance explain free cash flow

Ask thesis questions naturally. “Is CRWV a buy?” becomes a conditional screen, not a recommendation: what the evidence supports, what could break the thesis, and which metrics decide the next update.

Deterministic runtime

The default install contains the focused SKILL.md, workflow references, specialist prompts, Codex metadata, and the 14-module runtime needed by the current /finance workflows. Repository media, development tooling, and legacy policy documents are not copied into the runtime skill.

Installation

Agent skill (recommended)

Run the installer from the project where you want the skill:

# Choose: claude | codex | cursor | gemini | antigravity | all
curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- codex

# Required only for live market-data retrieval
python -m pip install "yfinance>=0.2"

The installer is version-pinned, copies an allowlisted payload, and refuses to overwrite a non-empty skill directory. Add --legacy-alias only if you still need the older /finance-skills namespace.

Standalone Python CLI

python -m pip install finance-skills==0.14.3
finance screen --ticker NVDA --format json
finance compare --tickers AMD NVDA --format json
finance explain --topic "free cash flow" --format json

Use --fixture for explicit offline samples. Fixture output is always labelled as sample data and never substitutes for a failed live request.

How it works

User request
    │
    ▼
finance skill ── route to exactly one workflow reference
    │
    ▼
workflow_cli.py ── provider orchestration + normalization
    │
    ▼
evidence report ── observations + formulas + 29 detector results
    │
    ▼
agent synthesis ── conclusion + tension + limitations + what to watch

The engine owns calculation and provenance. The agent owns interpretation. A number presented as finance-skills output must exist in the current report; external filing facts must be separately sourced and never blended into engine metrics.

The canonical skill router is skill/SKILL.src.md. Focused workflows live in skill/reference/. The evidence and state contracts are documented in docs/redesign-contract.md.

Evidence and safety contract

Automatic company DCF remains disabled unless every required assumption is explicit. Educational output is not investment advice.

Data sources and limits

• Market data: yfinance, with provider state and retrieval metadata exposed.
• Filings: optional SEC Company Facts reconciliation when FINANCE_SEC_USER_AGENT contains a compliant contact string.
• Company IR: explicit project-local observations; never scraped or inferred silently.
• Estimates: opt-in and kept separate from reported historical evidence.
• Fixtures: deterministic CRWV/NBIS samples for demos and offline tests.

Market-data providers can be delayed, incomplete, or definitionally inconsistent. Verify material revenue, cash flow, debt, cash, shares, and capex claims against the latest 10-K or 10-Q.

Persistent research

/finance init creates RESEARCH.md and .finance/config.json without overwriting existing files. track creates immutable company snapshots. refresh produces a deterministic diff and a reviewable thesis-update proposal instead of silently rewriting prior research.

Only init, track, and refresh write project state. State paths are confined to the project and use exclusive or append-only writes.

Evaluation

The public checker evaluates three layers:

See docs/eval.md for the protocol and limitations. It checks contract adherence, not investment accuracy.

Development

python -m pip install -e ".[dev]"
python -m pytest tests -q --cov=scripts
ruff check scripts tests
mypy scripts

• Contributing: CONTRIBUTING.md
• Security: SECURITY.md
• Releases: CHANGELOG.md
• Engine-report schema: docs/engine-report.schema.json

License

MIT · Read-only research · Not investment advice