Skill, hook, subagente y CI: probamos a revisar un módulo con Claude Code

Por David Moya · · 9 min lectura · Artículo técnico

Prueba del 16 de noviembre de 2026 con Claude Code 2.1.325: configuración, resultados y un hallazgo sobre los hooks PostToolUse.

Skill, hook, subagente y CI en Claude Code

Una skill define el procedimiento, un subagente hace la lectura editorial, un hook comprueba cada edición y el CI cierra la puerta en el push. El 16 de noviembre de 2026 montamos las cuatro piezas para revisar un módulo de un temario ficticio con Claude Code. Esto es lo que hicimos, con la configuración real y lo que midió cada prueba. El hallazgo principal: un hook PostToolUse avisa, pero no impide el cambio.

En este artículo

  1. Condiciones de la prueba
  2. Las cinco piezas
  3. La configuración, fragmento a fragmento
  4. Resultados
  5. El hallazgo: el hook avisa, no bloquea
  6. Cómo repetir la prueba
  7. Límites de la prueba
  8. Preguntas frecuentes

Condiciones de la prueba

Es una sola muestra, en un repositorio pequeño y con un único modelo. Sirve para ver el mecanismo, no para sacar tasas de acierto.

Las cinco piezas

El reparto sigue la lógica de la comparativa de extensiones de Anthropic: lo que debe ser siempre verdad va en CLAUDE.md, un procedimiento reutilizable en una skill, una comprobación ante un evento en un hook, y una revisión con su propio contexto en un subagente.

PiezaFicheroQué hace
CLAUDE.mdCLAUDE.mdConvenciones del temario y comando del validador.
Skill.claude/skills/revisar-modulo/SKILL.mdProcedimiento y formato del informe. Solo se activa con /revisar-modulo.
Subagente.claude/agents/revisor-editorial.mdRevisión editorial con herramientas de solo lectura.
Hook.claude/settings.json y scripts/hook_validar.pyPostToolUse sobre ediciones: valida los enlaces del Markdown de temario/.
CI.github/workflows/enlaces.ymlEjecuta el validador de enlaces en cada push.

Si quieres la base de cada una, tenemos guías sobre skills, hooks y subagentes. Aquí nos interesa cómo se combinan.

La configuración, fragmento a fragmento

Skill: el procedimiento

La skill (documentación) fija el orden de trabajo y el formato del informe. disable-model-invocation: true reserva su uso a la persona: solo corre cuando alguien escribe /revisar-modulo.

---
name: revisar-modulo
description: Revisa un módulo del temario antes de publicarlo (objetivos, rúbrica, fuentes, entregable y enlaces) y entrega un informe con hallazgos localizables. Se invoca con /revisar-modulo <ruta>.
disable-model-invocation: true
---

1. Ejecuta `python3 scripts/validar_enlaces.py $ARGUMENTS` y anota cada enlace roto con fichero:línea.
2. Delega la lectura editorial en el subagente `revisor-editorial` pasándole la ruta. No edites ningún fichero.
3. Comprueba que el módulo tiene, en este orden: identificador `M-NN`, «Objetivos», «Contenido», «Entregable» y «Fuentes».
4. Devuelve un informe con este formato exacto: ... Veredicto: PUBLICABLE | NO PUBLICABLE

Subagente: la revisión de solo lectura

El subagente (documentación) tiene su propio contexto y solo Read, Grep y Glob. No puede escribir aunque quiera.

---
name: revisor-editorial
description: Revisor editorial de solo lectura para módulos del temario. Devuelve hallazgos con fichero:línea. Nunca edita.
tools: Read, Grep, Glob
---

Lee el módulo indicado y devuelve como máximo 5 hallazgos con el formato `fichero:línea: problema. propuesta.`

Practica con módulos gratuitos

Si quieres aprender a trabajar con agentes de IA paso a paso, empieza por los módulos gratuitos de IAcademy.

Empieza gratis

Hook: la comprobación en cada edición

El hook (documentación) se registra en .claude/settings.json y se dispara tras Edit, Write o MultiEdit.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hook_validar.py\""
          }
        ]
      }
    ]
  }
}

El script solo actúa sobre Markdown de temario/. Si el validador falla, escribe en stderr y sale con 2:

# scripts/hook_validar.py (extracto)
evento = json.load(sys.stdin)
ruta = evento.get("tool_input", {}).get("file_path", "")
if not (ruta.endswith(".md") and "/temario/" in ruta):
    sys.exit(0)
r = subprocess.run([sys.executable, "scripts/validar_enlaces.py", ruta],
                   capture_output=True, text=True)
# ... registra la ejecución en .claude/hook.log ...
if r.returncode:
    print("Validador de enlaces:\n" + r.stdout, file=sys.stderr)
    sys.exit(2)   # Claude ve el aviso. El cambio ya está escrito.

CI: la puerta del repositorio

name: enlaces
on: [push, pull_request]
jobs:
  validar:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python3 scripts/validar_enlaces.py temario/

Resultados

PruebaQué se hizoResultado
T1/revisar-modulo sobre la rama con dos enlaces rotos.Pasa. Informe con :14 y :21, veredicto NO PUBLICABLE, subagente invocado y git status vacío.
T2Pedir a Claude que añada con Edit un enlace a un fichero inexistente.Pasa. El hook se ejecuta, queda en el log y Claude recibe el aviso. El cambio no se revierte.
T3Push de la rama limpia y de la rama con enlaces rotos.Pasa. Limpia: success, 0 enlaces rotos. Con defecto: failure, código de salida 1.
T4Comprobar que el subagente no modifica nada.Pasa. Sin herramientas de escritura y diff intacto (cubierto en T1).

T1: el informe de la skill

La ejecución duró 64 segundos y 5 turnos. El informe, resumido, fue este:

INFORME /revisar-modulo
Módulo: temario/modulo-02-evaluacion.md · M-02
Enlaces rotos: 2
- temario/modulo-02-evaluacion.md:14: ancla inexistente './modulo-01-introduccion.md#objetivo'
- temario/modulo-02-evaluacion.md:21: fichero inexistente './guia-rubricas.md'
Estructura: OK
Editorial: (5 hallazgos del subagente, con fichero:línea)
Veredicto: NO PUBLICABLE

El subagente aportó hallazgos que el validador no puede ver: un objetivo que no es observable y un entregable que pide cinco criterios cuando la rúbrica solo tiene dos. Es un buen reparto: el script comprueba lo determinista y el modelo, el juicio.

Una rareza: Claude invocó al subagente dos veces y repitió también la validación. Es inocuo, pero en un procedimiento real conviene pedir en la skill que se delegue una sola vez.

T3: el CI en verde y en rojo

En main, el workflow terminó en success con 0 enlaces rotos. En defecto terminó en failure con código de salida 1 y listó los dos enlaces del informe. Las ejecuciones fueron las 43958254778 y 43958256348 de GitHub Actions. El repositorio es privado, así que no podemos enlazarlas.

El hallazgo: el hook avisa, no bloquea

En T2 pedimos a Claude un enlace a un fichero inexistente. El hook se ejecutó y dejó esta línea en su log (extracto):

{"herramienta": "Edit", "fichero": "temario/modulo-01-introduccion.md", "codigo": 1,
 "salida": "temario/modulo-01-introduccion.md:15: fichero inexistente './plantilla-entregable.md'"}

El codigo: 1 es el del validador. El hook, a su vez, salió con 2 para que Claude Code mostrara el error al modelo, y Claude citó el aviso y propuso opciones. Pero el enlace roto ya estaba escrito. El hook no lo revirtió.

Regla práctica

Un hook PostToolUse informa después de escribir. Para impedir el cambio hace falta validar antes de escribir con un hook PreToolUse, o confiar en la puerta de CI. No probamos PreToolUse en este ensayo, así que lo planteamos como siguiente paso y no como resultado.

Lo razonable es combinar las tres capas: el hook da feedback inmediato al agente, la skill ordena el trabajo y el CI garantiza que nada roto llegue a la rama principal. Si quieres llevar esa tercera capa más lejos, mira cómo usar Claude Code en CI/CD. Y para el caso complementario, en el que el fallo pasa los tests, lee verificar en cuatro niveles los cambios de un agente.

Cómo repetir la prueba

El repositorio de prueba es privado, pero la idea se reproduce con cualquier carpeta de Markdown y un validador de enlaces de pocas líneas. La invocación de T1 fue esta:

claude -p "/revisar-modulo temario/modulo-02-evaluacion.md" --output-format json \
  --allowedTools "Bash(python3 scripts/validar_enlaces.py:*)" Read Grep Glob Agent

Con --allowedTools damos permiso solo al validador y a las herramientas de lectura y delegación. Así la skill no puede ejecutar nada más, y eso refuerza el criterio de «no cambia el repositorio».

Qué nos llevamos de la prueba:

Límites de la prueba

Preguntas frecuentes

¿Un hook PostToolUse puede impedir que Claude Code escriba un cambio?

No. En nuestra prueba el hook avisó con éxito, pero el cambio ya estaba escrito. Para impedirlo hace falta un hook PreToolUse o una puerta de CI.

¿Cuál es la diferencia entre una skill y un subagente?

La skill es un procedimiento que se carga en la conversación. El subagente trabaja con su propio contexto y sus propias herramientas, y devuelve un informe.

¿Cómo evito que una skill se active sin que yo lo pida?

Con disable-model-invocation: true en el frontmatter de SKILL.md. Así solo se activa cuando la invocas con su comando.

Llévate el checklist para evaluar agentes

17 comprobaciones sacadas de estas pruebas: qué puede tocar el agente, cómo se verifica lo que cambia, cómo se evalúa cuando no basta un test y qué hay que dejar anotado. Gratis, en PDF.

Descargar el checklist

«Claude», «Claude Code» y «Anthropic» son marcas de Anthropic, PBC. IAcademy es un proyecto educativo independiente, sin afiliación con Anthropic ni con las empresas citadas.