Python Lint Guard

python-lint-guard

El gemelo Python de [md-lint-fix](../md-lint-fix/SKILL.md): el gate que faltaba en la cadena de guardias del toolkit.

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:

| Código | Qué detecta | Por qué importa | |---|---|---| | PARITY-NO-CI | Herramienta declarada que ningún workflow ejecuta | El gate no existe donde importa: nada impide que el código roto entre a main | | PARITY-NO-CONFIG | El CI ejecuta una herramienta que el repo no declara | Config implícita: el dev no puede reproducir en local lo que el CI exige | | PARITY-CONFLICT | Dos herramientas con el mismo rol (dos formateadores, dos linters) | Se pisan: cada una reescribe lo que la otra dejó, generando commits de ida y vuelta | | PARITY-HOOK-ABSENT | Existe .pre-commit-config.yaml pero el hook local no está instalado | El caso más caro: el gate existe en el papel, no en la máquina. Cada violación se descubre en CI y cuesta un commit extra | | PARITY-NO-GATE | Hay .py y ningún linter declarado ni en CI | Superficie sin cubrir |

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:

| Regla | Por qué no se auto-corrige | |---|---| | F841 | Variable asignada y nunca usada — puede ser un bug real, no basura | | E741 | Nombre ambiguo (l, I, O) — renombrar es decisión de diseño | | E402 | Import fuera del top — a veces es intencional (side-effects, sys.path) | | E501 | Línea demasiado larga — la arregla el formateador, no el linter | | S110 / S112 | try-except-pass / continue — silenciar excepciones puede ocultar fallos | | C901 | Complejidad excesiva — exige refactor, no un fix | | B008 | Llamada en el default de un argumento — semántica, no estilo |

--fix invoca ruff check --select --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](../yaml-control/SKILL.md); para

Markdown → [md-lint-fix](../md-lint-fix/SKILL.md).

---

Dependencias

| Dependencia | Cómo instalar | Requerida u opcional | |---|---|---| | python>=3.11 | viene con el SO | requerida (usa tomllib) | | git | — | opcional (sin git analiza todo el árbol) | | ruff | pip install ruff | opcional — capa 2; degrada con aviso | | pre-commit | pip install pre-commit | opcional — solo para aplicar la recomendación |

---

Integración con los guards

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

• [pre-commit-guard](../pre-commit-guard/SKILL.md) → --parity-only sobre lo staged (rápido, `

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vladimiracunadev-create
• Source: vladimiracunadev-create/claude-skills-toolkit
• License: MIT
• Homepage: https://github.com/vladimiracunadev-create/claude-skills-toolkit#-catálogo

Install and usage instructions live in the source repository linked above.