A Claude Code skill that turns the code ↔ math gap into grounded, real-time explanations: read the math behind your code, pick the right math before you write it, and explain it to others.
math-hint is a math copilot, not a code linter. It rides along while you code and translates both directions between code and math, always grounded in your actual code rather than textbook abstractions. It keeps no memory and stores nothing: every session is live.
┌──────────────────┐ ┌─────────────┐ ┌────────────────────┐
│ your code + │ ──▶ │ routing │ ──▶ │ 1. understand │
│ a math keyword │ │ logic │ │ 2. prepare │
│ or a question │ │ │ │ 3. communicate │
└──────────────────┘ └─────────────┘ └─────────┬──────────┘
│
▼
┌────────────────────┐
│ in-chat answer or │
│ code comments │
└────────────────────┘
Three directions, auto-selected from what you say and whether code is in context.
| Direction | Triggers on | What it does | Output |
|---|---|---|---|
| Understand | a math keyword (PCA / SVD / Adam / softmax ...) with code present · "explain / I don't get it / what is this computing" · nan / wrong accuracy / negative variance |
explains the math scaffolding behind the code brick by brick, and traces weird numbers back along the math flow | answer grounded to file:line plus the actual formulas |
| Prepare | "which algorithm should I use / which one / can I use X / does the data meet the assumptions", usually before you write code | picks the right math and checks data assumptions before you commit to an approach | decision tables plus assumption checks |
| Communicate | "write math comments / docstring / interview practice / blog draft" | turns the math you just understood into something you can hand off | docstrings · mock-interview Q&A · blog draft |
It does not fire on generic code generation, non-math review, pure algorithm questions with no math angle (BFS vs DFS), or syntax / type errors.
# clone into your Claude Code skills directory
git clone https://github.com/catinblue/math-hint.git ~/.claude/skills/math-hintOnce it is present, the skill auto-triggers when you ask about the math behind code. No configuration, nothing to run.
you: "what is this PCA computing?" (with the code in context)
-> math-hint walks the math scaffolding, grounded to your file:line
math-hint/
SKILL.md # routing + when-to-fire + skill principles
references/
understand.md # 1. explain / trace the math behind code
prepare.md # 2. pick the right math + check assumptions
communicate.md # 3. comments / interview / blog
scan-rules.md # shared: 5 classes of math checks
decision-matrix-library.md # shared: library API decisions (sklearn / torch ...)
routing-logic.md # read only when routing is ambiguous
The loader reads SKILL.md first and pulls in references/ on demand, never all six at once.
rm -rf ~/.claude/skills/math-hint