Extender Claude Code

Skills: enseñando un flujo de trabajo a Claude

Un skill es un archivo markdown (SKILL.md) que enseña a Claude un flujo de trabajo repetible, activado por un comando slash. En lugar de pegar un prompt largo cada vez, lo invocas: /my-skill.

Anatomía: un frontmatter (nombre, descripción, disparadores) + instrucciones + a veces archivos de referencia y scripts. La descripción es crucial: es lo que permite a Claude elegir el skill correcto en el momento adecuado.

Pierre tiene una colección que revela el poder del mecanismo:

• graphify: convertir cualquier carpeta en un grafo de conocimiento consultable.
• dream: consolidación automática de memoria cada noche.
• continuous-learning: analizar el historial de git para extraer patrones recurrentes y proponer reglas.
• model-custom: activar su system prompt compuesto (Frankenstein).
• skill-builder: un skill para crear skills (meta).

Un skill es conocimiento procedimental empaquetado: codificas tu forma de hacer algo una vez, y Claude la repite perfectamente en cada llamada.

MCP: conectar herramientas externas

MCP (Model Context Protocol) es el estándar abierto que conecta a Claude con servidores de herramientas y datos externos: una base de datos, una API, un CMS, un SaaS. Una vez que un servidor MCP está conectado, sus herramientas pueden ser llamadas por Claude como herramientas nativas.

En la práctica, conectas un servidor mediante /mcp o la configuración, y los prompts del servidor aparecen en el formato /mcp__[server]__[prompt]. Es exactamente la misma tecnología que los Conectores del lado de Cowork.

Ejemplos del entorno de Pierre:

• Un MCP de Strapi (CMS headless) para su proyecto MarketDLAGO: Claude lee y edita el contenido del sitio directamente.
• MCPs de terceros conectados a la sesión: Gmail, Calendar, Drive, Canva, Gamma, herramientas SEO (Ahrefs), Adobe...

Un problema que hay que conocer, vivido por Pierre: un MCP puede estar limitado al proyecto. Su MCP de Strapi solo expone sus herramientas si Claude Code se inicia desde la carpeta de proyecto correcta. Iniciar desde otro lugar significa que las herramientas no aparecen. Regla: verificar el alcance cuando una herramienta MCP esperada no aparece.

Sub-agentes: delegar en un contexto aislado

Un sub-agente es un agente Claude que el agente principal lanza para una tarea, con su propio contexto aislado. Realiza su trabajo y solo devuelve su conclusión al agente principal, sin todo el desorden intermedio.

Dos beneficios principales:

• Limpieza del contexto: la búsqueda exploratoria (leer 30 archivos) ocurre en el sub-agente; el agente principal solo recibe el resultado. No se contamina.
• Paralelismo: se pueden lanzar varios sub-agentes a la vez sobre tareas independientes.

Tipos comunes: un agente Explore (búsqueda de solo lectura), un agente Plan (diseño de una estrategia), agentes especializados (revisión de código, auditoría SEO, análisis competitivo). Se gestionan mediante /agents.

Disponibles desde julio de 2025, los sub-agentes son el bloque básico de todo lo que sigue: los workflows y los equipos de agentes son simplemente formas estructuradas de orquestarlos.

Hooks: automatizar el ciclo de vida

Los hooks son acciones que se disparan automáticamente en momentos clave del ciclo de vida de Claude Code: antes o después de una llamada a una herramienta, cuando Claude termina, en cada edición de archivo, al iniciar la sesión.

Punto clave: es el harness quien ejecuta los hooks, no el modelo. Por lo tanto, cualquier comportamiento de la forma "cada vez que ocurra X, hacer Y automáticamente" no puede vivir en la memoria ni en las preferencias: debe ser un hook en settings.json.

Usos típicos:

• Formatear y hacer lint automáticamente después de cada edición de archivo.
• Ejecutar las pruebas cuando Claude anuncia que ha terminado.
• Bloquear un commit si se detecta un secreto.
• Disparar un sistema CI externo vía webhook cuando una tarea finaliza.

Pierre utiliza hooks de git (post-commit) para refrescar automáticamente sus grafos de Graphify en cada commit, y tareas programadas para la consolidación de memoria. Eso es lo que convierte una práctica manual en un pipeline automático.

Plugins y equipos de agentes

Plugins: un plugin es un paquete versionado que agrupa varios skills, sub-agentes, comandos slash, hooks, estilos de salida y definiciones de servidores MCP. Es la forma canónica de compartir extensiones reutilizables de Claude Code a través de un marketplace.

Pierre activa varios plugins en su settings.json: superpowers (flujos de trabajo avanzados), frontend-design, code-review, security-guidance, y un marketplace personal searchfit-seo con sus propios skills de SEO. Un plugin equivale a instalar de una sola vez un conjunto de herramientas completo y coherente.

Equipos de agentes: disponibles desde febrero de 2026, permiten que varios agentes se coordinen en subtareas paralelas. Es el nivel superior al de los sub-agentes aislados: no solo se delega, sino que los agentes colaboran hacia un objetivo común. Profundizamos en la orquestación en el módulo 9.

La progresión a recordar: skill (un flujo de trabajo) -> plugin (un conjunto de herramientas compartido) -> equipo de agentes (varios agentes colaborando). Cada nivel compone el anterior.

Crea tu propio skill

Un skill en Claude Code es un conjunto de instrucciones reutilizables almacenado en un archivo Markdown llamado SKILL.md. Cuando activas el skill, Claude lee ese archivo y lo aplica como conjunto de reglas para la tarea actual. Los skills se ubican en ~/.claude/skills/<skill-name>/SKILL.md (global, disponible en todos los proyectos) o en .claude/skills/<skill-name>/SKILL.md dentro de un repositorio específico (alcance de proyecto).

Todo SKILL.md comienza con un bloque frontmatter (un encabezado YAML breve entre dos líneas ---). Las dos claves obligatorias son name (un identificador corto) y description (una frase que le indica a Claude cuando aplica el skill). La descripción es lo que Claude Code muestra en la lista de skills y usa para decidir si sugerirlo automáticamente.

Un skill se activa de dos formas. La primera es de manera explícita: el usuario escribe /skill-name como comando slash. La segunda es automática: si tu descripción coincide con lo que el usuario solicita, Claude Code puede invocarlo sin que se lo pidan. El cuerpo de SKILL.md (todo lo que sigue al frontmatter) es Markdown simple y puede contener instrucciones paso a paso, restricciones, reglas de formato de salida o incluso plantillas de código.

La estructura de carpetas recomendada para un skill bien organizado es:

• SKILL.md (obligatorio): el frontmatter más las instrucciones
• README.md (opcional): documentación legible para el autor del skill
• examples/ (opcional): entradas de muestra y salidas esperadas de las que Claude puede aprender
• templates/ (opcional): plantillas de archivos que Claude debe copiar o completar durante la ejecución

Descubrir e instalar skills

Claude Code incluye una herramienta Skill integrada, un mecanismo que permite al agente cargar un prompt especializado, un flujo de trabajo o un mini-agente bajo demanda. Un skill es un paquete con nombre almacenado en ~/.claude/skills/<name>/SKILL.md. Cuando usted (o el propio Claude) invoca un skill, la herramienta Skill lee ese archivo y adopta sus instrucciones para el resto de la tarea.

Los skills se descubren a través de varios canales. El más sencillo es escribir un comando slash como /graphify o /code-review en el prompt de Claude Code. Claude verifica la lista de skills disponibles (visible en su recordatorio de sistema) y llama a la herramienta Skill automáticamente. También puede preguntar en lenguaje natural: "find a skill for X" activa el skill find-skills, que busca en el registro y sugiere qué instalar.

El principal punto de distribución es el repositorio comunitario affaan-m/ECC en GitHub, que agrupa cientos de skills preconfigurados. Basta con clonar o copiar los skills deseados en ~/.claude/skills/ para que estén disponibles de inmediato. Algunos autores también publican archivos SKILL.md como gists o subcarpetas de repositorios que puede depositar de la misma manera.

Aspectos clave del sistema de skills:

• Invocación: comando slash (p. ej. /deep-research) o activador en lenguaje natural definido en CLAUDE.md.
• Alcance: los skills en ~/.claude/skills/ son globales; un proyecto puede agregar los suyos en .claude/skills/.
• Composición: un skill puede llamar a la herramienta Skill para encadenar otro skill.
• Inventario: ejecute /skill-stocktake para auditar cada skill instalado y su activador.

El ecosistema MCP

MCP (Model Context Protocol) es un estándar abierto que permite a Claude conectarse con herramientas externas, fuentes de datos e instrucciones reutilizables a través de una única interfaz uniforme. En lugar de codificar cada integración, se conecta un servidor MCP (un pequeño programa que habla el protocolo) y Claude adquiere nuevas capacidades de inmediato.

MCP define exactamente tres primitivas (los bloques de construcción que expone cada servidor):

• Herramientas: funciones invocables que Claude puede llamar, como buscar en una base de datos, ejecutar un comando de shell o llamar a una API. Cada herramienta tiene un nombre, una descripción y un esquema de entrada tipado para que Claude sepa cómo invocarla correctamente.
• Recursos: fuentes de datos de solo lectura (archivos, URLs, filas de base de datos) que Claude puede obtener e incluir en su ventana de contexto (la memoria de trabajo que utiliza por conversación). Los recursos se identifican por una URI y se devuelven como texto o blobs binarios.
• Instrucciones: plantillas de instrucciones con nombre y reutilizables almacenadas en el servidor. Una instrucción puede aceptar argumentos y devolver un mensaje listo para usar, lo que facilita compartir instrucciones coherentes en un equipo sin copiar y pegar.

En Claude Code se configuran los servidores MCP en .claude/settings.json bajo la clave mcpServers. Una vez registrados, todas las herramientas que expone el servidor aparecen automáticamente en el agente, y se puede ver la lista completa con /mcp en el indicador de Claude Code.

Conectar un servidor MCP

MCP (Model Context Protocol) es un estándar abierto que permite a Claude Code comunicarse con herramientas externas y fuentes de datos a través de un pequeño proceso servidor. Cada servidor MCP expone un conjunto de herramientas (acciones que Claude puede invocar) y recursos (datos que Claude puede leer). Basta con instalar uno, indicarle su ubicación a Claude Code, y esas capacidades aparecerán automáticamente en cada conversación.

Claude Code admite dos ámbitos para los servidores MCP. El ámbito de usuario hace que un servidor esté disponible en todos los proyectos de su máquina. El ámbito de proyecto restringe el servidor a un repositorio concreto, lo que mantiene las credenciales y los conjuntos de herramientas aislados. Los servidores con ámbito de proyecto se declaran en .claude/settings.json dentro del repositorio; los de ámbito de usuario residen en su archivo global ~/.claude/settings.json.

Muchos servidores MCP requieren autenticación antes de que Claude Code pueda invocar sus herramientas. Los dos patrones más comunes son el token estático (se pega una clave secreta una sola vez y queda almacenada en la configuración) y OAuth (Open Authorization, un flujo basado en el navegador donde se inicia sesión con la cuenta real y el servidor emite un token de acceso temporal). OAuth es preferible cuando el servicio ya dispone de sus credenciales, ya que no se almacena ningún secreto permanente en un archivo.

• Agregar un servidor con ámbito de usuario: claude mcp add <name> -- <command> [args]
• Agregar un servidor con ámbito de proyecto: claude mcp add --scope project <name> -- <command> [args]
• Listar los servidores conectados y su estado: claude mcp list
• Eliminar un servidor: claude mcp remove <name>
• Iniciar el flujo de autenticación OAuth para un servidor: claude mcp authenticate <name>

Construir tu propio servidor MCP

El Model Context Protocol (MCP) es un estándar abierto que permite a Claude Code llamar a herramientas externas que defines tú mismo. En lugar de estar limitado a los comandos integrados, puedes exponer cualquier función (una consulta a base de datos, una llamada a API, una transformación de archivo) como una herramienta que Claude descubre e invoca automáticamente.

Los servidores MCP se comunican con Claude Code a través de uno de dos transportes (el canal por el que viajan los mensajes). stdio (entrada/salida estándar) es el más sencillo: Claude Code lanza tu servidor como un proceso hijo e intercambia mensajes JSON a través de stdin y stdout. HTTP con Server-Sent Events (SSE) ejecuta tu servidor como un servicio web persistente, útil cuando el servidor debe compartirse entre máquinas o mantenerse activo entre sesiones. Para herramientas locales, stdio es casi siempre la mejor opción.

Cada herramienta que expones tiene tres partes obligatorias: un nombre único, una descripción legible por humanos (Claude la lee para decidir cuándo llamar a la herramienta), y un esquema de entrada (un objeto JSON Schema que describe los parámetros que acepta la herramienta). Claude Code valida cada llamada contra el esquema antes de ejecutarla, de modo que los argumentos incorrectos se detectan con rapidez.

• Instala el SDK: npm install @modelcontextprotocol/sdk
• Elige stdio para herramientas locales, HTTP/SSE para servidores compartidos o remotos.
• Escribe una descripción clara: Claude elige las herramientas leyendo ese texto.
• Valida las entradas con los campos required y type de JSON Schema.

Patrones de sub-agentes

Un sub-agente es un proceso de Claude Code independiente que Claude inicia para gestionar una tarea específica en aislamiento. "Aislamiento" significa que dispone de su propia ventana de contexto en blanco (el búfer de memoria que contiene la conversación hasta ese momento), por lo que no puede ver el historial, las credenciales ni el razonamiento intermedio de la sesión padre. Esto es intencional: un contexto fresco se mantiene enfocado y evita contaminar los resultados con información no relacionada.

¿Cuándo conviene delegar a un sub-agente? La regla general es: delegar cuando una tarea es independiente (no necesita conocimiento que el padre ya posee), costosa (consumiría la mayor parte del presupuesto de contexto del padre leyendo muchos archivos) o paralelizable (varias tareas similares pueden ejecutarse al mismo tiempo). Algunos ejemplos son ejecutar una auditoría de seguridad completa sobre un único módulo, generar una traducción para cada idioma soportado o ejecutar una suite de pruebas sobre una rama.

Claude Code reconoce tres tipos de agentes con nombre que encontrará en los skills y en la documentación:

• Orquestador: el agente padre que planifica el trabajo, lo divide en sub-tareas y ensambla los resultados. Usa la herramienta Task internamente para lanzar los hijos.
• Sub-agente (trabajador): un proceso hijo que recibe un prompt único y bien delimitado y devuelve un resultado. No tiene memoria de los agentes hermanos.
• Agente revisor: un sub-agente especializado cuyo único trabajo es evaluar la salida de otro agente según una lista de criterios o rúbrica, y reportar aprobado o rechazado con justificación.

Dado que cada sub-agente parte de cero, el orquestador debe pasar todo el contexto necesario en el propio prompt: rutas de archivos, fragmentos de código relevantes, restricciones y formato de salida esperado. Trate cada prompt de delegación como un ticket autónomo entregado a un colaborador externo que nunca ha visto su proyecto.

Eventos de hook: el ciclo de vida

Claude Code expone un sistema de hooks que le permite ejecutar sus propios scripts en momentos precisos durante una sesión. Cada momento se denomina evento de hook. Usted registra un hook en settings.json asociando el nombre de un evento a un comando de shell. Claude Code ejecuta ese comando automáticamente cuando el evento se dispara.

Los principales eventos de hook son:

• PreToolUse: se dispara justo antes de que Claude llame a cualquier herramienta (lectura de archivos, comandos bash, peticiones web, etc.). Úselo para registrar, bloquear o modificar la llamada.
• PostToolUse: se dispara inmediatamente después de que una herramienta devuelve su resultado. Úselo para auditar la salida, desencadenar efectos secundarios o actualizar una pantalla de estado.
• Stop: se dispara cuando Claude termina su respuesta final y está a punto de quedar inactivo. Úselo para ejecutar tareas de limpieza, enviar una notificación o actualizar un archivo de memoria.
• SessionStart: se dispara una sola vez cuando se abre una nueva sesión de Claude Code. Úselo para cargar contexto, mostrar un panel de control o definir variables de entorno para la sesión.
• Notification: se dispara cuando Claude Code emite una notificación dirigida al usuario (por ejemplo, una solicitud de permiso o una actualización de tarea en segundo plano).

Los hooks reciben por stdin un JSON estructurado que describe el evento: qué herramienta fue llamada, qué argumentos se pasaron, cuál fue el resultado, etc. Su script lee ese JSON, realiza su trabajo y termina. Un código de salida distinto de cero en un hook PreToolUse cancela por completo la llamada a la herramienta, ofreciéndole un control ligero pero eficaz.

Escribir un script de hook

Un script de hook es un pequeño programa que Claude Code ejecuta automáticamente en un momento específico, por ejemplo antes de que se ejecute una herramienta o después de que se guarde un archivo. Los hooks permiten aplicar políticas, registrar acciones o enviar información adicional a Claude sin modificar los prompts.

Cada hook recibe un payload JSON (un objeto de datos estructurado) en la entrada estándar (stdin) que describe lo que Claude está a punto de hacer. El payload incluye un campo tool_name que puede compararse para decidir si el script debe actuar. Los nombres de herramientas comunes son Bash, Edit, Write y Read.

El script controla lo que sucede a continuación mediante su código de salida (un número que el script devuelve al sistema operativo al terminar) y su salida estándar (stdout):

• Exit 0: permite que la llamada a la herramienta continúe normalmente.
• Exit 2: bloquea la llamada a la herramienta y muestra el mensaje de stdout al usuario como error.
• Cualquier otro código distinto de cero: bloquea en silencio (Claude Code lo trata como un fallo crítico).

Si se escribe un objeto JSON en stdout con un campo continue establecido en true y una cadena stopReason, Claude lee ese texto y puede ajustar su siguiente acción. Así es como se envía contexto al modelo durante una tarea, convirtiendo un guardián pasivo en un asesor activo.

Plugins: agrupar todo en un solo lugar

Un skill de Claude Code es un directorio que se distribuye como una unidad instalable. En su interior puede combinar todos los puntos de extensión que ha aprendido: slash commands, hooks, declaraciones de servidor MCP e incluso definiciones de sub-agentes. Cuando alguien instala su skill, todas esas piezas se activan juntas, sin necesidad de configuración manual.

El punto de entrada es un archivo SKILL.md. Claude lo lee en el momento de la invocación para entender el propósito del skill, sus comandos disponibles y las instrucciones de configuración. Junto a él, el directorio del skill suele contener los scripts de soporte, fragmentos de configuración y manifiestos MCP que respaldan esos comandos.

Un skill bien estructurado cubre cuatro capas:

• Comandos: slash commands que el usuario puede escribir, definidos como secciones en SKILL.md o como archivos .md separados en una subcarpeta commands/.
• Hooks: scripts de ciclo de vida (por ejemplo, PostToolUse o Stop) declarados en una subcarpeta hooks/ y referenciados desde settings.json.
• Servidores MCP: proveedores de herramientas externas listados bajo mcpServers en el fragmento settings.json del skill.
• Agentes: prompts de sub-agentes reutilizables que los comandos del skill pueden lanzar mediante la herramienta Task.

Los skills residen en ~/.claude/skills/<skill-name>/ para uso global, o en .claude/skills/<skill-name>/ dentro de un repositorio para uso limitado al proyecto. Invocar un skill es tan sencillo como escribir /skill-name en el indicador de Claude Code.

settings.json en profundidad

settings.json es el archivo de configuración que controla el comportamiento de Claude Code en un proyecto o de forma global. Cubre cuatro áreas principales: los permisos (las herramientas que Claude puede usar sin preguntar), las variables de entorno (valores inyectados en cada sesión), los hooks (comandos de shell que se ejecutan automáticamente en ciertos momentos) y las reglas de ubicación de archivos y precedencia.

Existen dos niveles de alcance. El archivo de usuario en ~/.claude/settings.json se aplica a todos los proyectos que abres. El archivo de proyecto en .claude/settings.json dentro de un repositorio se aplica solo a ese repositorio. Cuando ambos existen, los ajustes del proyecto sobreescriben los del usuario para cualquier clave compartida, y el resto se hereda.

El bloque permissions utiliza una lista allow y una lista deny. Cada entrada es un identificador de herramienta como Bash, Edit o un nombre de herramienta MCP. Las entradas en allow permiten que Claude llame a esa herramienta sin confirmación; las entradas en deny la bloquean por completo. El bloque env es un objeto clave-valor simple: cada clave se convierte en una variable de entorno disponible para los hooks y para cualquier subproceso que Claude lance.

El bloque hooks asocia eventos del ciclo de vida con comandos de shell:

• PreToolUse: se ejecuta antes de que Claude llame a una herramienta (útil para registro o bloqueo).
• PostToolUse: se ejecuta después de que una llamada a herramienta finaliza.
• Stop: se ejecuta cuando la sesión termina (útil para resúmenes o sincronización de memoria).
• Notification: se dispara cuando Claude envía un evento de notificación.

Cada entrada de hook es un objeto con un matcher (nombre de herramienta o "*" para todas) y una cadena command ejecutada en el shell. Los hooks se ejecutan como el usuario actual, por lo que tienen acceso completo al sistema: mantenlos cortos y revisados.

Estilos de salida

Claude Code usa por defecto un estilo conversacional y detallado: explica su razonamiento, lista los pasos y confirma las acciones. Ese comportamiento predeterminado es útil cuando se está aprendiendo, pero genera ruido cuando se trabaja en un ciclo de iteración rápida o se redirige la salida hacia otra herramienta.

El estilo de salida se controla mediante dos mecanismos principales: las opciones de la línea de comandos y las instrucciones dentro del propio prompt. Las opciones son fiables y legibles por máquinas; las instrucciones de prompt son flexibles y portables.

Las opciones más importantes son:

• --output-format json: emite un objeto JSON estructurado en lugar de prosa, útil cuando un script necesita analizar el resultado.
• --output-format text: texto plano, sin markdown, adecuado para redirigir hacia grep o sed.
• --verbose: muestra las llamadas a herramientas y los pasos de razonamiento internos, útil para entender por qué Claude hizo algo inesperado.
• --no-stream: espera la respuesta completa antes de mostrarla, en lugar de transmitir los tokens a medida que llegan.

Dentro del prompt se pueden agregar directivas de estilo como "responde solo con el contenido del archivo, sin comentarios" o "devuelve únicamente un comando de shell, nada más." Claude Code las respeta de forma consistente en claude-opus-4-8, claude-sonnet-4-6 y claude-haiku-4-5.

Tareas en segundo plano y herramientas web

Claude Code puede lanzar procesos de larga duración en segundo plano para que no tenga que esperar a que terminen antes de dar la siguiente instrucción. La opción run_in_background le indica a la herramienta Bash que inicie un comando sin bloquearse: Claude lo lanza, continúa trabajando y le notifica cuando finaliza. Esto es útil para compilaciones, suites de pruebas o servidores de desarrollo que de otro modo congelarían la conversación.

Dos herramientas web extienden Claude Code más allá de sus archivos locales. WebSearch consulta la web y devuelve una lista clasificada de resultados con títulos, URLs y fragmentos breves. WebFetch recupera el contenido completo de una URL específica, elimina el HTML y le entrega el texto legible a Claude. Juntas, permiten a Claude responder preguntas que requieren información actualizada o documentación externa sin que usted tenga que copiar y pegar nada.

Saber cuándo usar cada herramienta es importante. Use WebSearch cuando necesite descubrir fuentes (aún no conoce la URL correcta). Use WebFetch cuando ya tiene una URL y quiere que Claude lea la página completa (por ejemplo, una referencia de API o un registro de cambios). Use run_in_background cuando un comando de shell tarde más de unos pocos segundos y quiera seguir trabajando en paralelo.

• run_in_background: ejecución de shell no bloqueante, resultado entregado como notificación.
• WebSearch: búsqueda web en tiempo real, devuelve fragmentos y enlaces.
• WebFetch: recupera y lee una página completa en una URL dada.
• Las tres funcionan dentro de una conversación normal de Claude Code, sin necesidad de ningún complemento.