md-lint-fix

Detecta, auto-corrige y reporta errores markdownlint en archivos .md modificados — antes de cualquier git commit o git push.

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.

Reescribe ficheros del repo.

IMPORTANTE — Cómo funciona desde cualquier repositorio

El script vive en ~/.claude/skills/md-lint-fix/fix-md-lint.py pero usa Path.cwd() como raíz de trabajo. Esto significa que trabaja siempre en el directorio donde estás parado, no en portfolio-pages.

Desde cualquier repo, el comando es:

# Archivos .md modificados según git (uso normal pre-push)
python ~/.claude/skills/md-lint-fix/fix-md-lint.py

# Todos los .md del repo actual
python ~/.claude/skills/md-lint-fix/fix-md-lint.py --all

# Solo diagnóstico sin modificar nada
python ~/.claude/skills/md-lint-fix/fix-md-lint.py --dry-run

El script detecta el repo actual desde Path.cwd() — no importa desde qué carpeta se llame el script.

Cuándo usar este skill

• El usuario menciona errores MD031, MD034, MD040, MD032, MD024, MD028
• Antes de hacer commit/push con archivos .md modificados
• Después de crear o editar skills, docs o cualquier archivo markdown
• El usuario dice "arregla el lint", "corrige los markdown", "limpia los MD"

Errores que resuelve automáticamente

No resuelve automáticamente (requieren criterio humano):

• MD025 — múltiples headings H1 (implica reestructura)
• MD014 — $ antes de comandos shell (decisión de estilo)
• MD042 — enlaces vacíos (requiere URL real)
• MD051 — fragmentos de enlace rotos (requiere verificar ancla)
• MD013 — line length (desactivado en la mayoría de proyectos)
• MD033 — inline HTML (depende de config del proyecto)

Requisito en el repo destino

El repo donde se ejecute debe tener markdownlint-cli2 disponible. Recomendado: pnpm (postinstall bloqueado por defecto + cuarentena de 24 h sobre versiones nuevas — ver docs/supply-chain-security.md).

La versión va fijada, no flotante: pnpm add -D markdownlint-cli2 sin versión instala lo último publicado, así que una release comprometida entra sola y además el conteo de errores cambia bajo tus pies cuando el linter cambia de criterio.

# Verificar si está instalado
pnpm exec markdownlint-cli2 --version   # o: npx markdownlint-cli2@0.24.0 --version

# Instalar en el repo (recomendado)
pnpm add -D markdownlint-cli2@0.24.0

# Alternativas — válidas pero con menos defensas por defecto contra ataques tipo Shai-Hulud:
#   yarn add -D markdownlint-cli2@0.24.0
#   npm  install --save-dev --ignore-scripts markdownlint-cli2@0.24.0

Si el repo no tiene markdownlint-cli2, pnpm dlx markdownlint-cli2@0.24.0 (o npx markdownlint-cli2@0.24.0) lo descargará automáticamente.

Flujo de ejecución del script

1. Detecta .md en scope (modificados o todos según flag)
2. Escanea con markdownlint-cli2 y cuenta errores iniciales
3. Corrige MD024: añade contexto del heading padre para desambiguar
4. Corrige MD040: infiere lenguaje del bloque (bash/python/json/yaml/hcl/etc.)
5. Auto-fix con markdownlint-cli2 --fix (14 reglas)
6. Verifica y reporta errores restantes agrupados por código de regla

Referencia de reglas

Documentación oficial: https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md