python-lint-guard

El gemelo Python de md-lint-fix: el gate que faltaba en la cadena de guardias del toolkit.

Alcance y permisos

No declara allowed-tools, y es deliberado: ese campo preaprueba herramientas —se salta la confirmación durante el turno que invoca el skill— en vez de limitarlas. Declararlo aquí no acotaría nada: quitaría la confirmación del usuario. disallowed-tools sí retira herramientas del pool mientras el skill está activo, y ahí es donde se acota de verdad.

--fix reescribe código.

Por qué existe

Un .py modificado atravesaba pre-commit-guard y pre-push-guard sin lint. Los dos guards encadenaban yaml-control + md-lint-fix + pytest, y ninguno miraba el estilo del Python. El resultado observable son los commits que solo existen para apagar un CI en rojo: fix(lint): ruff F401/I001, style: aplicar black para pasar CI, fix: wrap strings for ruff.

Pero este skill no es un wrapper de ruff. Correr el linter es la parte fácil y ya la hace el CI. Su aporte propio es la capa que ninguna herramienta cubre: la paridad entre lo declarado y lo ejecutado.

Cuándo invocar este skill

Triggers explícitos:

• "arregla el lint de Python"
• "corrige los errores de ruff"
• "por qué falla el lint en CI"
• "black rompió el CI"
• "valida los .py antes de pushear"
• "fix python lint"

Triggers proactivos:

• Después de editar cualquier .py
• Antes de git commit / git push con Python en el diff
• Cuando el CI falla en un job de lint y no está claro por qué en local pasaba

Cómo se invoca

python ~/.claude/skills/python-lint-guard/python_lint_guard.py                # diff vs git
python ~/.claude/skills/python-lint-guard/python_lint_guard.py --all          # todos los .py
python ~/.claude/skills/python-lint-guard/python_lint_guard.py --fix          # auto-fix del set mecánico
python ~/.claude/skills/python-lint-guard/python_lint_guard.py --parity-only  # solo paridad, sin ruff
python ~/.claude/skills/python-lint-guard/python_lint_guard.py --json         # salida JSON

Exit code 0 si no hay errores, 1 si hay algo que bloquea commit/push.

Capa 1 — Paridad de toolchain (núcleo, stdlib)

Cruza dos inventarios y reporta cuatro desalineaciones:

Fuentes de declaración que lee: pyproject.toml ([tool.*] y dependencias), ruff.toml, .ruff.toml, setup.cfg, .flake8, tox.ini, .pre-commit-config.yaml. Fuente de ejecución: .github/workflows/*.y*ml, mirando solo líneas run: / uses: para no confundir un comentario o el nombre de un job con una ejecución real.

Herramientas reconocidas y su rol: ruff (linter+formatter), black, autopep8, yapf (formatter), flake8, pylint (linter), isort (import-sorter), mypy (type-checker).

Capa 2 — Violaciones (opt-in, requiere ruff)

Si ruff no está instalado, esta capa se salta con un aviso RUFF-ABSENT y la capa de paridad ya se ejecutó igual. Nunca falla por ausencia.

La aportación aquí es la separación en dos grupos:

Mecánicas — se corrigen sin criterio humano, y son las únicas que toca --fix:

I001 · F401 · UP006 · UP035 · W291 · W293 · W391 · RUF100 · COM812 · Q000

Requieren criterio — se reportan, nunca se auto-corrigen:

--fix invoca ruff check --select <set-mecánico> --fix. Nunca un --fix global: eso es exactamente lo que borra la evidencia de un bug al eliminar la variable que lo delataba.

Qué NO hace / limitaciones

• No formatea. No invoca black ni ruff format. Reporta el conflicto si hay dos formateadores, pero la decisión de cuál usar es del proyecto.
• No instala nada. Si falta ruff o el hook de pre-commit, lo dice y da el comando; no lo ejecuta por su cuenta.
• La detección en workflows es textual, no semántica: un run: que invoque el linter a través de un Makefile o un script propio puede no detectarse. Falso negativo posible en PARITY-NO-CI — nunca falso positivo silencioso.
• No juzga la configuración del linter (qué reglas activar es del proyecto).
• Solo Python. Para YAML → yaml-control; para Markdown → md-lint-fix.

Dependencias

Integración con los guards

Ambos guards del toolkit lo invocan automáticamente cuando hay .py en el diff:

• pre-commit-guard → --parity-only sobre lo staged (rápido, < 2 s)
• pre-push-guard → análisis completo sobre el diff vs origin/<branch>

Si el skill no está instalado, ambos guards lo saltan con ⊘ y siguen.

Ejemplo de salida

python-lint-guard — repo: C:\dev\social-bot-scheduler
  ficheros .py en scope: 47

Toolchain declarado vs. ejecutado en CI
  ---------------------------------------------------------------------
  herramienta   rol               declarado en             CI
  black         formatter         .pre-commit-config.yaml  ci-cd.yml
  flake8        linter            .pre-commit-config.yaml  ci-cd.yml
  mypy          type-checker      pyproject.toml           ci-cd.yml

ERRORES
  ✗ [PARITY-HOOK-ABSENT] .pre-commit-config.yaml existe pero el hook local NO está instalado
      → instálalo con `pre-commit install` — sin él el linter solo corre en CI
        y cada violación cuesta un commit extra de arreglo

❌ Hay errores que bloquean commit/push.