{"id":"d4fdcf16-39df-4ffc-b600-ed28586be3e6","slug":"noteheng-finance-skills","kind":"skill","name":"finance-skills","summary":"AI agent financial skill — real fundamentals, deterministic math, fail-closed. Stop agents inventing stock numbers.","owner":"notEhEnG","repoUrl":"https://github.com/notEhEnG/finance-skills","license":"MIT","licenseTier":"permissive","trust":"community","stars":2,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-07-08T06:23:01.000Z","addedAt":"2026-10-21T09:15:07.224Z","logoUrl":"https://avatars.githubusercontent.com/u/111334322?u=9ddb519c359a5859196e6bacd580bc7bc158cabf&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["data-analytics","developer-tools"],"tags":["equity-research","finance","llm","openai","valuation","agents","ai-agents","claude-code"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T22:37:10.281Z","sample":false,"url":"https://conduits.dev/tools/noteheng-finance-skills","language":"Python","transports":["stdio"],"install":{"pypi":"finance-skills"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# finance-skills\n\n[![CI](https://github.com/notEhEnG/finance-skills/actions/workflows/ci.yml/badge.svg)](https://github.com/notEhEnG/finance-skills/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/finance-skills)](https://pypi.org/project/finance-skills/)\n[![Python](https://img.shields.io/pypi/pyversions/finance-skills)](https://pypi.org/project/finance-skills/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\nAuditable public-company research for AI coding agents. One skill, 10 focused\nworkflows, 29 deterministic detector rules, and a fail-closed financial evidence\nengine.\n\n> **Quick start:** install the skill, install its live-data dependency, then run\n> `/finance screen NVDA` (or `$finance screen NVDA` in Codex).\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- claude\npython -m pip install \"yfinance>=0.2\"\n```\n\nThe engine computes and labels the numbers. Your agent interprets the evidence.\nNeither is allowed to silently do the other's job.\n\n## Why finance-skills?\n\nCompany-analysis agents tend to fail in two ways: they invent plausible numbers,\nor they return a data dump without an argument. finance-skills separates those\njobs and tests the boundary.\n\n- **Deterministic fact layer.** Revenue growth, margins, cash conversion, Rule of\n  40, net debt, and valuation multiples come from Python—not model arithmetic.\n- **Fail-closed evidence.** Missing debt is not zero. Period and currency\n  mismatches block affected calculations. Disabled analyses stay visible.\n- **Analyst layer with a point of view.** The agent must weigh conflicting\n  evidence, state the assumption doing the most work, and explain what would\n  change the conclusion.\n- **Auditable provenance.** Material values preserve company, period, currency,\n  source, confidence, data mode, formula, and evidence paths.\n- **Read-only boundary.** No brokerage integrations, trade execution, position\n  sizing, guaranteed returns, or personalized buy/sell instructions.\n\n## See it in action\n\nClaude Code answering “Is NVDA overvalued?” with live data:\n\n![finance-skills agent demo](docs/demo-agent.gif)\n\n[Watch the full-quality video](docs/demo-agent.mp4) or the\n[engine-only terminal demo](docs/demo.gif).\n\n## What's included\n\n### The skill: `finance`\n\nAll research flows use one skill and one evidence contract:\n\n| Command | What it does |\n|---|---|\n| `/finance init` | Create non-sensitive project research context |\n| `/finance screen <ticker>` | Fast, evidence-grounded company assessment |\n| `/finance underwrite <ticker>` | Full conditional thesis with specialist perspectives |\n| `/finance audit <ticker>` | Accounting-quality, provenance, and detector review |\n| `/finance compare <tickers>` | Period- and currency-compatible peer comparison |\n| `/finance challenge <ticker>` | Red-team the current thesis and its core assumption |\n| `/finance stress <ticker>` | Explicit operating and valuation scenarios |\n| `/finance track <ticker>` | Save an immutable research snapshot and watchpoints |\n| `/finance refresh <ticker>` | Compare current evidence with saved research |\n| `/finance explain <topic>` | Explain a financial concept without company advice |\n\nUse `$finance ...` in Codex. A ticker by itself, or a generic “analyze” request,\nroutes to `screen`.\n\n### Usage examples\n\n```text\n/finance screen NVDA\n/finance underwrite CRWV\n/finance audit PLTR\n/finance compare AMD NVDA\n/finance stress NBIS\n/finance explain free cash flow\n```\n\nAsk thesis questions naturally. “Is CRWV a buy?” becomes a conditional screen,\nnot a recommendation: what the evidence supports, what could break the thesis,\nand which metrics decide the next update.\n\n### Deterministic runtime\n\nThe default install contains the focused `SKILL.md`, workflow references,\nspecialist prompts, Codex metadata, and the 14-module runtime needed by the\ncurrent `/finance` workflows. Repository media, development tooling, and legacy\npolicy documents are not copied into the runtime skill.\n\n## Installation\n\n### Agent skill (recommended)\n\nRun the installer from the project where you want the skill:\n\n```bash\n# Choose: claude | codex | cursor | gemini | antigravity | all\ncurl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/v0.14.3/install.sh | bash -s -- codex\n\n# Required only for live market-data retrieval\npython -m pip install \"yfinance>=0.2\"\n```\n\nThe installer is version-pinned, copies an allowlisted payload, and refuses to\noverwrite a non-empty skill directory. Add `--legacy-alias` only if you still\nneed the older `/finance-skills` namespace.\n\n| Runtime | Default project path | Invocation |\n|---|---|---|\n| Claude Code | `.claude/skills/finance/` | `/finance ...` |\n| Codex | `.codex/skills/finance/` or `CODEX_SKILLS_DIR` | `$finance ...` |\n| Cursor | `.cursor/skills/finance/` | `/finance ...` |\n| Gemini CLI | `.gemini/skills/finance/` | `/finance ...` |\n| Antigravity | `.antigravity/skills/finance/` | `/finance ...` |\n\n### Standalone Python CLI\n\n```bash\npython -m pip install finance-skills==0.14.3\nfinance screen --ticker NVDA --format json\nfinance compare --tickers AMD NVDA --format json\nfinance explain --topic \"free cash flow\" --format json\n```\n\nUse `--fixture` for explicit offline samples. Fixture output is always labelled\nas sample data and never substitutes for a failed live request.\n\n## How it works\n\n```text\nUser request\n    │\n    ▼\nfinance skill ── route to exactly one workflow reference\n    │\n    ▼\nworkflow_cli.py ── provider orchestration + normalization\n    │\n    ▼\nevidence report ── observations + formulas + 29 detector results\n    │\n    ▼\nagent synthesis ── conclusion + tension + limitations + what to watch\n```\n\nThe engine owns calculation and provenance. The agent owns interpretation. A\nnumber presented as finance-skills output must exist in the current report;\nexternal filing facts must be separately sourced and never blended into engine\nmetrics.\n\nThe canonical skill router is [`skill/SKILL.src.md`](skill/SKILL.src.md).\nFocused workflows live in [`skill/reference/`](skill/reference/). The evidence\nand state contracts are documented in\n[`docs/redesign-contract.md`](docs/redesign-contract.md).\n\n## Evidence and safety contract\n\n| Allowed | Blocked |\n|---|---|\n| Report observations and engine calculations | Numbers recalled or inferred by the model |\n| Explicit user assumptions, clearly labelled | Silent estimates or repaired missing values |\n| Separately attributed primary-filing facts | External values mixed into engine calculations |\n| Conditional valuation language with a stated basis | Unconditional “cheap”, “expensive”, buy, sell, or hold |\n| Visible fixture, cache, and partial-data limits | Presenting sample or stale data as live |\n\nAutomatic company DCF remains disabled unless every required assumption is\nexplicit. Educational output is not investment advice.\n\n## Data sources and limits\n\n- **Market data:** yfinance, with provider state and retrieval metadata exposed.\n- **Filings:** optional SEC Company Facts reconciliation when\n  `FINANCE_SEC_USER_AGENT` contains a compliant contact string.\n- **Company IR:** explicit project-local observations; never scraped or inferred\n  silently.\n- **Estimates:** opt-in and kept separate from reported historical evidence.\n- **Fixtures:** deterministic CRWV/NBIS samples for demos and offline tests.\n\nMarket-data providers can be delayed, incomplete, or definitionally inconsistent.\nVerify material revenue, cash flow, debt, cash, shares, and capex claims against\nthe latest 10-K or 10-Q.\n\n## Persistent research\n\n`/finance init` creates `RESEARCH.md` and `.finance/config.json` without\noverwriting existing files. `track` creates immutable company snapshots.\n`refresh` produces a deterministic diff and a reviewable thesis-update proposal\ninstead of silently rewriting prior research.\n\nOnly `init`, `track`, and `refresh` write project state. State paths are confined\nto the project and use exclusive or append-only writes.\n\n## Evaluation\n\nThe public checker evaluates three layers:\n\n| Tier | Examples of what it catches |\n|---|---|\n| Safe | Unrecognized numbers, recommendation language, hidden disabled analyses |\n| Useful | Raw JSON dumps, caveat walls, answers with no analytical substance |\n| Synthesized | Draft copying, missing thesis structure, ticker-swappable prose |\n\nSee [`docs/eval.md`](docs/eval.md) for the protocol and limitations. It checks\ncontract adherence, not investment accuracy.\n\n## Development\n\n```bash\npython -m pip install -e \".[dev]\"\npython -m pytest tests -q --cov=scripts\nruff check scripts tests\nmypy scripts\n```\n\n- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- Security: [`SECURITY.md`](SECURITY.md)\n- Releases: [`CHANGELOG.md`](CHANGELOG.md)\n- Engine-report schema: [`docs/engine-report.schema.json`](docs/engine-report.schema.json)\n\n## License\n\n[MIT](LICENSE) · Read-only research · Not investment advice\n"}