finance-skills 0.10.0

AI agent financial skill: real fundamentals, deterministic Rule of 40/DCF/red flags, fail-closed when data is missing — so agents stop inventing stock numbers.

finance-skills

Guardrailed financial-analysis skill for AI coding agents.

When an agent talks about a public company, it can invent plausible EV/EBITDA, fill missing net debt with zero, or say “buy.” This skill forces a deterministic path: route → engine report → bounded answer. Numbers come only from the report; missing data is disabled, not guessed.

Why an agent skill instead of a stock API or a chatbot? A raw LLM hallucinates numbers. A data API can’t reason. finance-skills splits the job: a deterministic engine computes every number and flag (auditable, testable, evaluated in docs/eval.md), and your agent — Claude Code, Codex, Antigravity — does what agents are actually good at: weighing conflicting evidence and building the argument. Same question, two tickers, two genuinely different analyses — with zero invented numbers.

# 1) Install skill (Claude Code)
curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/main/install.sh | bash -s -- claude

# 2) In the agent
/finance-skills is CRWV a buy?

Who this is for: Claude Code / Codex / Cursor-style agent users and people building tool-using agents.
Who this is not for: stock tips, portfolio advice, or r/investing “what should I buy” threads.

---

The failure mode (exact)

Without skill	With skill
Model invents FCF % or intrinsic value	Metrics from one engine report
Missing debt → silent zero	Fail-closed; DCF/EV disabled with reason
“I’d buy the dip”	Policy: analysis only, never a recommendation
Fixture demo treated as live tape	data_state: fixture + mandatory disclosure

Data quality: live pulls use yfinance (delayed, incomplete, label-noisy). Always verify revenue, FCF, debt, cash, shares, and capex in 10-K/10-Q. Fixtures (CRWV, NBIS) are sample data, not live.

---

How this differs from other finance skills

Most agent finance skills on GitHub fall into three classes — each fails a different way:

Class	Where numbers come from	The problem	This skill
Prompt-only ("no runtime, every skill is a prompt")	The model reasons about a DCF or F-Score from memory	Hallucinated numbers with confident formatting	The engine computes every metric; the model may not state a number that isn't in the report
Web-search analysts	Search results pasted into the context	Unverifiable figures + explicit "Buy/Hold/Sell + target price" output	Fail-closed evidence policy; never a recommendation — a conditional valuation screen instead
API wrappers	A paid data vendor behind an API key	Data delivery without an analysis contract; vendor lock-in	Free data layer + an explicit agent contract: the engine keeps the agent honest, the agent builds the argument

The split that makes this work: a deterministic fact layer (auditable numbers, flags, disabled analyses — tested in CI) and a mandated analyst layer (the agent must weigh the bull/bear tension and answer the actual question, scored by a public three-tier eval: safe → useful → synthesized, including a ticker-swap check). Prompt-only skills have the second layer without the first; API wrappers have the first without the second.

---

Agent interaction (contract)

1. User: “Is CRWV a buy?”
2. Agent runs one command:
   python3 scripts/ask.py --json "Is CRWV a buy?" (add --fixture for sample data)
3. Engine returns answer_draft + full report (disabled DCF, fixture flag, evidence)
4. Agent writes its own analyst answer on top — weighing the bull/bear tensions in the report, in the conditional-thesis shape (SKILL.md §4a) — then stops scripting (stop_tool_loop). answer_draft is the evidence floor, not the final reply.
5. No buy/sell recommendation; numbers only from the draft/report

Hard gate: if ask (or legacy route --json + engine --json) did not run this turn for an in-scope company question, do not state financial numbers.

Anti-pattern: chaining five Python scripts and dumping JSON.
Success: one ask → user-visible analysis.

Full policy: SKILL.md · templates: docs/agent-policy.md · eval: docs/eval.md

---

Install

Skill (primary)

curl -fsSL https://raw.githubusercontent.com/notEhEnG/finance-skills/main/install.sh | bash -s -- claude
# codex | antigravity | all

Runtime	Status	Path
Claude Code	tested (skill dir + bash engine)	.claude/skills/finance-skills/
Codex-compatible	best effort	.codex/skills/ (or CODEX_SKILLS_DIR)
Cursor-style	best effort (attach skill + run scripts)	project skill copy
MCP server	not shipped	—

CLI (secondary)

pip install finance-skills
finance-skills brief CRWV --fixture

---

Slash commands

/finance-skills is NVDA overvalued?
/finance-skills is PLTR a value trap?
/finance-skills brief CRWV
/finance-skills valuation AAPL
/finance-skills compare AMD NVDA
/finance-skills learn rule40
/finance-skills help

Intent	Module
default / quick take	brief
cheap / buy / worth / DCF	valuation (analysis, not a rec)
value trap / red flags	redflags
balance sheet / runway	health
compare / vs	compare
walkthrough	company
concept only (no ticker)	learn
personal “what should I buy/sell”	refuse

python3 scripts/router.py route --json "Is CRWV a buy?"
python3 scripts/brief.py CRWV --fixture --json   # includes engine_report

---

Output & fail-closed

Every core verb JSON includes engine_report:

• source.data_state: live | fixture | unavailable | …
• disabled_analyses: reason_code + unlock
• response_guidance.prohibited_claims / mandatory_caveats
• calculations never encode unknown net debt as 0

Schema: docs/engine-report.schema.json

---

Eval (public)

20-prompt bare-model-vs-skill table and hard-fail rules: docs/eval.md

python -m pytest tests/test_agent_transcripts.py tests/test_route_request.py -q

Transcript hard fails: invent number · say buy · hide disabled DCF · fixture-as-live.

---

Optional CLI

Same engine outside an agent UI:

pip install finance-skills
finance-skills route --json "is NBIS a value trap?"
finance-skills brief AAPL
finance-skills compare CRWV NBIS --fixture

---

Development

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

Where to talk about this: agent / Claude Code / tool communities — not as stock advice on investing subs. See docs/SOCIAL.md.

---

License

MIT · Read-only research · Not investment advice