python-code-style

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: python-code-style
description: >
  Owns Python code style for this stack: ruff for lint + format, numpydoc
  for docstrings. Three responsibilities — (1) place the project's
  `ruff.toml` from the bundled template once the stack and workspace
  are in place, (2) run ruff against any Python files Claude has
  just generated or edited, and (3) contextualize each touched file's
  comments to the data-science problem — rewriting any leftover
  template / workflow prose (skill names, gates, runner, digest,
  guard-rails) into concise, problem-specific docs so the user's
  committed files read like a colleague wrote them, not like a
  generated scaffold. Stops at "the touched files pass `ruff check`
  and document the problem, not the process."

  TRIGGER when (any of these):
  (1) a Python file was just created or edited via Write / Edit /
      MultiEdit — invoke this skill before declaring the task done so
      ruff is run AND the file's comments are contextualized to the
      problem;
  (2) a fresh ML workspace was just scaffolded by
      `organize-ml-workspace` and the project has no `ruff.toml` at
      its root yet — drop the bundled template;
  (3) the user asks about lint, format, docstring style, or reaches
      for `black` / `isort` / `flake8` / `pydocstyle` (redirect to
      ruff — the stack's canonical linter, owned by
      `data-science-python-stack` Tier 1).

  SKIP when: the project is non-Python; the only edits in this turn
  are to Markdown / TOML / JSON / YAML; the file lives in a
  third-party vendored directory the user doesn't own.

  HOW TO USE: run ruff manually on the files you just touched — do
  not configure a PostToolUse hook for this. **Read the "Stop
  conditions" block and emit the Pre-flight checklist as visible
  text in your response — both are mandatory before running ruff.**
---

# Python Code Style

Single owner of "what does well-styled Python look like in this
stack": ruff (lint + format) and numpydoc docstrings. This skill is
explicitly **manual** — Claude runs ruff on the files it has just
touched, no hook involved.

## Stop conditions — read before anything else

- **Do not configure a PostToolUse / PreToolUse hook for ruff.** This
  skill is intentionally manual. A hook tightens the loop in ways
  that bite (every micro-edit triggers a fix cycle, partial files
  fail D-rule checks mid-write, retries can stall the turn). If the
  user explicitly asks for an automated hook later, redirect to
  `update-config` — but the default is "Claude runs ruff itself."
- **Do not substitute ruff with `black` / `isort` / `flake8` /
  `pydocstyle` / `pylint`.** Ruff is the canonical linter in this
  stack (`data-science-python-stack` Tier 1). If `import ruff` /
  `pixi run ruff --version` fails, route through `python-env-manager`
  to install — don't silently fall back.
- **One fix attempt per file, then surface.** If `ruff check`
  reports issues after Claude's first fix, address them once. If the
  *same* issue persists after the second pass, stop editing that
  file and surface the remaining diagnostics + diff to the user.
  This is the anti-infinite-loop guardrail — do not enter a third
  cycle on the same warning.
- **Don't lint files outside the user's code.** The hook scope is
  `src/<pkg>/`, `experiments/`, `audit/`, `data/eda.py` (the
  explore-ml-data EDA script), top-level `*.py` scripts, and any
  package directory the user owns. Skip vendored paths, generated
  files, the rest of user-owned `data/`, and anything under `.pixi/`,
  `.venv/`, `node_modules/`, etc.
- **Never write `ruff.toml` from memory.** The bundled
  `templates/ruff.toml` is the single source of truth — it encodes
  the per-file ignores (`experiments/**`), the numpydoc convention,
  and the rule selection this stack expects. Initial setup requires
  **`Read .agents/skills/python-code-style/templates/ruff.toml`**
  *this turn*, then `Write <project-root>/ruff.toml` verbatim from
  that file's content. Authoring