python-ml

Python/ML Stack

Production-ready Claude Code configuration for Python machine learning projects.

What's Included

Component	Description
CLAUDE.md	Project instructions: ML conventions, anti-patterns, testing practices
skills/ml-debug	Systematic ML debugging: shapes, NaN, gradients, devices, dtypes
skills/data-explore	Dataset profiling: schema, distributions, missing values, outliers
skills/notebook-refactor	Jupyter notebook to tested Python module extraction
hooks/python-lint.sh	Auto-format with ruff + black on every file edit
hooks/type-check.sh	pyright/mypy type checking after edits
hooks/test-guard.sh	Run relevant pytest tests when source files change
settings.json	Hook configuration wiring everything together
templates/pyproject.toml	Recommended project config with dev/ml/torch dependency groups
templates/.env.example	Common environment variables for ML projects

Installation

# From your project root:
cp -r path/to/claude-awesome-stack/stacks/python-ml/CLAUDE.md ./CLAUDE.md
mkdir -p .claude/skills .claude/hooks
cp -r path/to/claude-awesome-stack/stacks/python-ml/skills/* .claude/skills/
cp -r path/to/claude-awesome-stack/stacks/python-ml/hooks/* .claude/hooks/
cp path/to/claude-awesome-stack/stacks/python-ml/settings.json .claude/settings.json

Prerequisites

The hooks expect these tools to be installed (they degrade gracefully if missing):

• ruff -- fast Python linter (pip install ruff)
• black -- code formatter (pip install black)
• pyright or mypy -- type checker (pip install pyright)
• pytest -- test runner (pip install pytest)
• jq -- JSON processor (system package)

Customization

Disable a hook

Remove or comment out the corresponding entry in .claude/settings.json.

Adjust tool preferences

Edit CLAUDE.md to match your project's conventions (e.g., different formatter, testing framework).

Add your own skills

Create new directories under .claude/skills/ with a SKILL.md file. See the existing skills for the format.