Image for post Claude Code: Hooks, Skills y MCPs para Entornos Reales

Claude Code: Hooks, Skills y MCPs para Entornos Reales

Escrito por Sergio Márquez

TL;DR: Claude Code sin configurar es un asistente genérico. Con hooks, skills y MCPs bien definidos se convierte en una herramienta que sigue las reglas de tu proyecto, ejecuta acciones deterministas y accede a contexto actualizado. Esta guía cubre las configuraciones que realmente importan en producción, con ejemplos concretos y el coste real de cada decisión.

El problema que nadie menciona en los tutoriales

La mayoría de los tutoriales de Claude Code muestran cómo instalar la herramienta y empezar a chatear con el código. Lo que no muestran es lo que ocurre dos semanas después: el agente reformatea archivos de forma inconsistente, olvida las convenciones del proyecto, o ejecuta comandos que deberían estar bloqueados en ciertos entornos.

Claude Code tiene tres mecanismos de configuración que resuelven exactamente estos problemas: los hooks garantizan ejecución determinista en eventos del ciclo de vida, los skills codifican workflows reutilizables en Markdown, y los MCPs conectan el agente a herramientas externas con contexto real. Entender cuándo usar cada uno marca la diferencia entre un asistente que ayuda y uno que genera deuda técnica.

¿Qué son los hooks en Claude Code?

Los hooks son comandos shell que se ejecutan en puntos específicos del ciclo de vida de Claude Code. No son sugerencias para el modelo: son ejecuciones garantizadas, independientemente de lo que Claude decida hacer.

Los cinco eventos principales son:

  • PreToolUse: antes de que Claude ejecute cualquier herramienta. Ideal para bloquear operaciones peligrosas.
  • PostToolUse: después de que una herramienta termina con éxito. Ideal para formateo automático o validaciones.
  • UserPromptSubmit: cuando el usuario envía un prompt, antes de que Claude lo procese. Permite inyectar contexto adicional.
  • Stop: cuando el agente termina de responder. Útil para notificaciones o commits automáticos.
  • Notification: cuando Claude envía una alerta al usuario.

La clave está en el sistema de códigos de salida: 0 permite la acción, 2 la bloquea y envía el mensaje de stderr a Claude para que ajuste su plan. Cualquier otro código no-cero muestra el error al usuario sin bloquear la operación.

Configuración de hooks: tres patrones que funcionan

Los hooks se definen en ~/.claude/settings.json (global) o en .claude/settings.json (por proyecto). La estructura básica es consistente en todos los tipos de evento.

Patrón 1: bloquear operaciones destructivas

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo '$CLAUDE_TOOL_INPUT' | jq -r '.command' | grep -qE '(rm -rf|git reset --hard|DROP TABLE)' && echo 'Operacion bloqueada: requiere confirmacion manual' >&2 && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

Cuando Claude intenta ejecutar un comando bloqueado, recibe el mensaje de stderr y puede replantear su enfoque. En la practica, esto evita que un agente en modo automatico elimine archivos sin supervision humana.

Patrón 2: formateo automático post-edicion

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo '$CLAUDE_TOOL_INPUT' | jq -r '.file_path'); case $FILE in *.py) ruff format $FILE ;; *.ts|*.tsx) npx prettier --write $FILE ;; esac"
          }
        ]
      }
    ]
  }
}

Este hook detecta la extension del archivo editado y aplica el formateador correspondiente. Sin este patron, Claude puede generar codigo tecnicamente correcto pero que no pasa el linter del equipo.

Patrón 3: inyeccion de contexto en prompts largos

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Rama actual: '$(git branch --show-current)' | Ultimo commit: '$(git log -1 --format='%s')"
          }
        ]
      }
    ]
  }
}

Este patron inyecta el estado actual de git en cada prompt. Es util cuando trabajas en multiples ramas y el agente necesita saber el contexto sin que tengas que recordarselo manualmente.

¿Qué son los skills y cuándo usarlos?

Un skill es un archivo Markdown en ~/.claude/skills/ o .claude/skills/ que define un workflow reutilizable. La diferencia con un slash command es que los skills pueden activarse automaticamente cuando el contexto coincide, no solo cuando se invocan explicitamente.

La estructura tipica de un skill tiene secciones bien definidas: cuando usarlo, contexto que necesita, proceso paso a paso, formato de salida esperado y restricciones. Esta estructura no es arbitraria: permite que el modelo active el skill correctamente y siga el proceso sin desviarse.

Ejemplo: skill de TDD para Python

---
name: python-tdd
description: Implementacion TDD para modulos Python. Activa cuando se pide crear una nueva funcion o clase.
triggers:
  - "crear funcion"
  - "implementar clase"
  - "nuevo modulo"
---

## Cuando usar este skill
Cuando se pide implementar nueva funcionalidad Python en un proyecto con pytest.

## Proceso
1. Escribir el test primero en `tests/test_[modulo].py`
2. Confirmar que el test falla con `pytest tests/test_[modulo].py -v`
3. Implementar la logica minima para pasar el test
4. Refactorizar si es necesario, manteniendo los tests en verde

## Restricciones
- No modificar tests existentes para hacerlos pasar
- Cobertura minima del 80% antes de marcar como completado
- Imports: stdlib > third-party > local

Un skill como este elimina la necesidad de repetir las instrucciones de TDD en cada sesion. Claude las aplica automaticamente cuando el contexto coincide.

MCPs: conectar Claude Code a herramientas externas

El Model Context Protocol es el mecanismo que permite a Claude Code acceder a herramientas externas como repositorios de GitHub, bases de datos, o documentacion actualizada. Los MCPs se configuran en ~/.mcp.json (global) o .mcp.json (por proyecto).

La tabla siguiente recoge los tres MCPs con mejor relacion utilidad/complejidad para un entorno de desarrollo tipico:

MCP Caso de uso principal Coste Instalacion
Context7 Documentacion actualizada de librerias Gratuito (1.000 req/mes) claude mcp add context7 -- npx -y @upstash/context7-mcp@latest
GitHub MCP Issues, PRs, repositorios Gratuito (requiere token) claude mcp add github -- npx -y @modelcontextprotocol/server-github
Filesystem Acceso controlado a directorios locales Gratuito claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Projects

Context7 es el mas valioso para proyectos con dependencias que evolucionan rapido. Resuelve un problema concreto: Claude puede sugerir metodos deprecados o APIs que ya no existen. Con Context7 activo, el modelo consulta la documentacion oficial antes de generar codigo, lo que reduce significativamente los errores de este tipo.

Una limitacion real a febrero 2026: el tier gratuito de Context7 baja a 1.000 peticiones al mes y 60 por hora. Para proyectos con uso intensivo, existe una alternativa local que construye el indice de documentacion a partir de los propios repositorios de las librerias.

Configuracion de proyecto: .mcp.json

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Este archivo puede commitearse al repositorio para que todo el equipo use la misma configuracion. Las variables de entorno como GITHUB_TOKEN se resuelven en tiempo de ejecucion desde el shell, no quedan expuestas en el archivo.

En Produccion

El gap entre el tutorial y el entorno real tiene varias dimensiones que conviene anticipar.

Coste de tokens. Claude Code usa prompt caching por defecto: el contenido cacheado cuesta el 10% del precio original despues de la primera peticion. Mantener el caching activo es la optimizacion mas sencilla disponible. Un CLAUDE.md de 500 lineas que se incluye en cada peticion puede generar un coste significativo si el caching esta desactivado, y casi nada si esta activo.

Hooks en modo no interactivo. Los hooks de tipo PermissionRequest no se activan cuando Claude Code corre con el flag -p (modo no interactivo). Para pipelines CI/CD o ejecucion autonoma, usa PreToolUse en su lugar para las decisiones de permisos.

Skills y contexto de proyecto. Los skills globales en ~/.claude/skills/ aplican a todos los proyectos. Si tienes un skill de TDD para Python que incluye imports especificos de tu empresa, puede interferir con proyectos de terceros. Usar .claude/skills/ a nivel de proyecto es mas seguro cuando las convenciones varian.

MCPs y tiempo de arranque. Cada MCP activo anade latencia al inicio de la sesion. La funcionalidad Tool Search de Claude Code carga los MCPs bajo demanda en lugar de todos al principio, reduciendo el uso de contexto hasta un 85% en sesiones donde no necesitas todos los MCPs disponibles. Merece la pena activarla si tienes mas de tres o cuatro servidores configurados.

Gestion de secretos en hooks. Los hooks tienen acceso al entorno del shell. Un hook que ejecuta echo $AWS_SECRET_ACCESS_KEY expone la clave en el log de Claude. Revisar que los hooks no loggeen variables de entorno sensibles es parte del checklist de seguridad antes de commitear la configuracion.

Errores comunes y su solucion

Error: El hook bloquea operaciones legitimas porque el matcher es demasiado amplio.
Causa: Un matcher como "Bash" sin condiciones internas bloquea cualquier comando.
Solucion: Usar grep -qE dentro del hook para filtrar solo los patrones realmente peligrosos, y salir con 0 para el resto.

Error: El skill no se activa automaticamente aunque el contexto coincide.
Causa: Las palabras clave en el frontmatter del skill no coinciden con los terminos exactos usados en el prompt.
Solucion: Revisar la seccion triggers del skill e incluir variantes del vocabulario que realmente usas.

Error: Context7 devuelve documentacion desactualizada o con rate limit.
Causa: El tier gratuito tiene limite de 1.000 peticiones mensuales desde enero 2026.
Solucion: Para proyectos con uso intensivo, configurar el MCP de Filesystem apuntando al directorio local de node_modules o a un clon del repositorio de la libreria como alternativa sin limite de peticiones.

¿Cuándo justifica el tiempo de setup?

¿Necesito hooks si solo trabajo en proyectos personales?

El tiempo de configuracion de un hook de bloqueo de operaciones destructivas es menos de diez minutos. Si usas Claude Code con algun grado de autonomia (subagentes, modo automatico), un hook de bloqueo para rm -rf y git reset --hard es una inversion que se amortiza la primera vez que el agente decide que borrar un directorio es la solucion mas eficiente.

¿Los skills reemplazan al CLAUDE.md?

No, tienen propositos distintos. CLAUDE.md define el contexto permanente del proyecto: arquitectura, convenciones, reglas globales. Los skills codifican workflows reutilizables que se activan por contexto o comando. La combinacion optima es un CLAUDE.md conciso que apunta a los skills relevantes en lugar de incluir todos los procedimientos directamente.

¿Qué pasa si el MCP de GitHub tiene un outage?

Claude Code continua funcionando con las herramientas nativas. Los MCPs son extensiones opcionales, no dependencias criticas. Si un MCP falla, Claude lo indica en la sesion y puedes continuar usando el CLI de gh directamente desde los hooks o en el contexto de la conversacion.

Conclusion

Hooks, skills y MCPs forman la infraestructura de configuracion de Claude Code que convierte el asistente en una herramienta adaptada a tu forma de trabajar. Los hooks garantizan ejecucion determinista donde los prompts solo pueden hacer sugerencias. Los skills reducen la repeticion de instrucciones en cada sesion. Los MCPs conectan el agente a informacion y herramientas que de otro modo estarian fuera de su alcance.

El punto de entrada practico es simple: un hook que bloquea operaciones destructivas, un skill para el workflow de testing que mas repites, y Context7 si trabajas con librerias que cambian frecuentemente. El resto se puede ir añadiendo segun los friction points que encuentres en el dia a dia.

¿Tienes algun hook o skill que haya cambiado tu flujo de trabajo con Claude Code? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. El siguiente articulo cubre como construir un MCP server propio para conectar Claude Code a herramientas internas de empresa.

Volver al blog