Cómo crear complementos para Claude Code: Una guía paso a paso

Claude Code se encarga de la mayoría de las tareas de desarrollo de forma inmediata, pero cada equipo tiene flujos de trabajo específicos que los valores predeterminados no cubren. Es posible que desees un comando personalizado que estructure los componentes según la estructura preferida de tu empresa, o una comprobación automática antes de cada confirmación, o un acceso rápido a la documentación de un marco de trabajo que utilizas constantemente.

Los complementos de Claude Code te permiten añadir estas funciones tú mismo. Puedes instalar complementos creados por la comunidad o crear los tuyos propios.

Si eres nuevo en la herramienta de codificación de agentes de Anthropic, te recomiendo que empieces por la  Guía de Claude Code o el curso Introducción a Modelos Claude. Este tutorial da por sentado que tienes Claude Code instalado y que lo has utilizado para tareas básicas.

Al final, sabrás cómo:

• Busca e instala complementos del directorio de Anthropic y de fuentes de la comunidad.
• Comprender los tres tipos de componentes que pueden contener los complementos.
• Elige el tipo adecuado para cada caso de uso.
• Crea y comparte tus propios complementos

¿Qué son los complementos Claude Code?

Un complemento es un paquete que agrupa una o varias extensiones de Claude Code para facilitar su intercambio e instalación. En lugar de copiar manualmente los archivos de configuración entre equipos o compañeros de trabajo, puedes incluir todo en un complemento y distribuirlo como una sola unidad.

Los complementos pueden contener tres tipos de componentes:

• Habilidades: Comandos personalizados que invocas con /skill-name o indicaciones contextuales que Claude utiliza automáticamente cuando es relevante.
• Servidores MCP: Conexiones a servicios externos y API que te dan acceso a datos que de otro modo no tendrías.
• Ganchos: Scripts de terminal que se ejecutan automáticamente en eventos específicos, como antes de editar un archivo o después de una confirmación.

Un complemento puede contener solo uno de estos elementos o combinar varios que funcionan juntos. Un complemento de «implementación» podría incluir una habilidad de /deploy para implementaciones manuales, un servidor MCP que compruebe el estado de tu entorno de prueba y un gancho que ejecute pruebas antes de que se ejecute cualquier comando de implementación.

El archivo de manifiestoplugin.json define lo que contiene un complemento. Especifica qué habilidades, servidores MCP y ganchos instalar, junto con metadatos como el nombre del complemento, la versión y el autor. Cuando instalas un complemento, Claude Code lee este manifiesto y configura cada componente en la ubicación correcta.

Este formato de empaquetado significa que no necesitas comprender la estructura interna de archivos de las extensiones de Claude Code. Instala el complemento y todo quedará donde debe estar.

Búsqueda e instalación de complementos Claude Code

La mayoría de los complementos se encuentran en uno de estos dos lugares. Directorio oficial de Anthropic en plugins.claude.ai incluye complementos creados por Anthropic, contribuciones verificadas de la comunidad y extensiones populares de terceros. Cada ficha muestra los componentes que contiene el complemento, información sobre compatibilidad e instrucciones de instalación.

La segunda fuente es GitHub. El repositorio awesome-claude-code mantiene una lista seleccionada y organizada por categorías, y los programadores individuales publican plugins en vuestros propios repositorios.

Una vez que hayas encontrado el complemento que deseas, el comando de instalación depende de dónde se encuentre:

# From the official directory
claude plugin add @anthropic/deploy-helper
 
# From a GitHub repository
claude plugin add github:username/repo-name
 
# From a local directory (useful during development)
claude plugin add ./my-plugin

Después de instalar algunos complementos, querrás llevar un registro de ellos. El comando ` plugin ` se encarga de listar, actualizar y eliminar:

# List all installed plugins
claude plugin list
 
# Update a specific plugin to the latest version
claude plugin update @anthropic/deploy-helper
 
# Update all plugins
claude plugin update --all
 
# Remove a plugin
claude plugin remove @anthropic/deploy-helper

Una decisión que tomarás durante la instalación es el alcance. Los complementos pueden residir en dos lugares: los complementos de ámbito de usuario se instalan en ~/.claude/plugins/ y funcionan en todos tus proyectos, mientras que los complementos de ámbito de proyecto se instalan en .claude/plugins/ dentro de un repositorio específico.

El valor predeterminado es el ámbito de usuario. Para instalar un complemento solo para el proyecto actual, añade el indicador --project:

claude plugin add @anthropic/deploy-helper --project

Los complementos con alcance de proyecto tienen sentido cuando la extensión se vincula a un código base específico. 

Un complemento que conoce el proceso de implementación de tu empresa pertenece a ese proyecto. Un complemento que formatea el código según tus preferencias personales pertenece al nivel de usuario. Cuando un complemento existe en ambos ámbitos, la versión del proyecto tiene prioridad, lo que permite a los equipos aplicar configuraciones específicas del proyecto, mientras que los programadores mantienen activos sus complementos personales en otros lugares.

Elegir el tipo de complemento Claude Code adecuado

Los tres tipos de componentes tienen diferentes propósitos y consumen recursos de manera diferente. Comprender estas ventajas e inconvenientes te permite mantener tu ventana de contexto en buen estado y te ayuda a elegir la herramienta adecuada para cada tarea.

Habilidades frente a servidores MCP: La compensación simbólica

Los servidores MCP precargan todas las definiciones de herramientas en tu ventana de contexto al inicio de la sesión. Cada herramienta necesita su nombre, descripción y esquema completo de parámetros, que suele tener entre 100 y 300 tokens por herramienta. Una configuración de cinco servidores consume aproximadamente 55 000 tokens antes de que escribas un solo carácter:

• GitHub: 35 herramientas
•  Slack: 11 herramientas
• Centinela: 5 herramientas
• Grafana: 5 herramientas
• Splunk: 2 herramientas

Un análisis reveló que las configuraciones con más de 7 servidores consumían más de 67 000 tokens, lo que supone un tercio de la ventana de contexto de 200 000 antes de que comience la conversación.

Las habilidades adoptan un enfoque diferente a través de la divulgación progresiva. Al inicio de la sesión, Claude solo ve el nombre de cada habilidad y una descripción de una línea del frontmatter YAML, alrededor de 100 tokens por habilidad. 

Las instrucciones completas solo se cargan cuando Claude determina que la habilidad es relevante para la tarea actual. Los archivos de referencia solo se cargan cuando son específicamente necesarios. Y los scripts nunca entran en la ventana de contexto; Claude los ejecuta externamente y solo se obtiene el resultado.

Anthropic abordó este desequilibrio a finales de 2025 con Tool Search, una función que incorpora la carga diferida a los servidores MCP. 

En lugar de precargar todas las definiciones de herramientas, Claude Code ahora detecta cuándo las descripciones de herramientas consumirían más del 10 % del contexto disponible y cambia a la carga bajo demanda. 

Las pruebas internas mostraron que el uso del contexto se redujo de ~134 000 tokens a ~5000 tokens para bibliotecas de herramientas grandes. La precisión en la selección de herramientas también mejoró, pasando Opus 4 del 49 % al 74 % y Opus 4.5 del 79,5 % al 88,1 % en las evaluaciones MCP.

Entonces, ¿cuándo debes recurrir a cada uno?

Las habilidades encajan mejor cuando quieres que Claude tenga acceso a conocimientos o flujos de trabajo que pueda aplicar con criterio. Cuando Claude revisa el código, se carga una habilidad que describe la lista de verificación de revisión de código de tu equipo, pero Claude sigue decidiendo cómo aplicar cada elemento en función del contexto. 

Las habilidades también tienen sentido para operaciones que requieren scripts para cálculos complejos, ya que el código del script permanece fuera de la ventana de contexto.

Los servidores MCP son la mejor opción cuando Claude necesita datos en tiempo real de servicios externos como mensajes de Slack, PR de GitHub o consultas de bases de datos. También son la opción adecuada cuando varios agentes de IA necesitan las mismas herramientas, o cuando necesitas funciones empresariales como registros de auditoría y permisos explícitos.

Muchas configuraciones combinan ambas cosas: las habilidades proporcionan el «cómo» y el «cuándo» a través de instrucciones en lenguaje natural, mientras que los servidores MCP se encargan de las llamadas API reales.

Habilidades populares de Claude Code que vale la pena instalar

• Superpoderes: Más de 20 flujos de trabajo probados en producción para TDD, depuración y planificación estructurada.
• diseño de interfaz: Le indica a Claude que evites la estética genérica y tomes decisiones de diseño audaces.
• mcp-builder: Guía para crear servidores MCP para integrar API externas
•  pruebas de aplicaciones web: Prueba aplicaciones web locales utilizando Playwright para la verificación de la interfaz de usuario.
•  creador de habilidades: Herramienta interactiva que te guía en el desarrollo de nuevas habilidades.

Servidores MCP populares a los que vale la pena conectarse

• Context7: Búsqueda de documentación específica de cada versión en tiempo real
• GitHub: Búsqueda en repositorios, gestión de relaciones públicas, seguimiento de incidencias.
• Dramaturgo: Automatización del navegador utilizando árboles de accesibilidad en lugar de capturas de pantalla.
• Supabase: Consultas de bases de datos con reconocimiento de seguridad a nivel de fila
• Centinela: Seguimiento de errores y supervisión del rendimiento directamente en tu editor.

También puedes leer nuestra guía sobre los mejores servidores MCP remotos.

Ganchos: La capa determinista

Los ganchos quedan totalmente al margen del debate entre habilidades y MCP. Mientras que tanto las habilidades como los servidores MCP están orientados a Claude (Claude decide cuándo utilizarlos), los hooks están orientados al sistema. Se activan en eventos como PreToolUse o PostToolUse, ejecutando scripts de terminal antes o después de que Claude realice acciones específicas. Claude no tiene voz ni voto en si un gancho funciona o no.

Esto hace que Hooks sea la elección adecuada cuando algo debe suceder sin excepción: linting antes de cada commit, bloquear escrituras en directorios protegidos, registrar cada comando bash o ejecutar pruebas antes de cualquier implementación.

Este programador recomienda los ganchos «block-at-submit» en lugar de los ganchos «block-at-write». Interrumpir a Claude en mitad de una tarea confunde al agente y produce peores resultados. Tu equipo utiliza un gancho PreToolUse que envuelve Bash(git commit) y comprueba si existe un archivo temporal que solo aparece si las pruebas se superan. Sin archivo, no hay confirmación. El agente finaliza su trabajo y, a continuación, se lleva a cabo la validación al final.

Los ganchos no añaden ninguna sobrecarga de tokens, ya que se ejecutan como scripts de terminal fuera de la ventana de contexto.

Enlaces útiles de Claude para configurar

• ESLint/Prettier en la edición: Formatear automáticamente los archivos después de que Claude los escriba.
• Prueba de puerta en commit: Bloquea las confirmaciones a menos que se superen las pruebas.
• Rutas protegidas: Evita escribir en migraciones, configuraciones o directorios de proveedores.
• Notificación de finalización: Enviar alertas de Slack o del escritorio cuando finalicen tareas largas.
• Copia de seguridad de la transcripción: Guarda el historial de conversaciones antes de ejecutar la compactación.

Cómo crear tus propios complementos Claude Code

Cuando una habilidad se encuentra en tu directorio personal .claude/, solo tú puedes utilizarla. Empaquetarlo como un complemento te permite compartirlo con tus compañeros de equipo o reutilizarlo en diferentes proyectos.

Crearemos un complemento llamado session-logger que añade un comando/session-logger:summarize. Cuando se invoca, Claude revisa la conversación y añade un resumen estructurado a SESSION_LOG.md.

Crea la estructura del complemento.

Los complementos pueden residir en cualquier lugar de tu sistema de archivos. Para este tutorial, crearemos uno en tu directorio de inicio:

cd ~
mkdir -p session-logger/.claude-plugin
mkdir -p session-logger/skills/summarize

Esto crea:

~/session-logger/
├── .claude-plugin/
│   └── plugin.json  	# manifest goes here, nowhere else
└── skills/
	└── summarize/   	# folder name becomes the command name
    	└── SKILL.md 	# must be named exactly this

Escribe el manifiesto.

Crear un ~/session-logger/.claude-plugin/plugin.json:

{
  "name": "session-logger",
  "description": "Log session summaries to a markdown file",
  "version": "1.0.0"
}

El campo « name » se convierte en el prefijo del espacio de nombres. Todos los comandos de este complemento comenzarán por /session-logger:.

Escribe la habilidad

Crear ~/session-logger/skills/summarize/SKILL.md:

---
description: Log a summary of the current session to SESSION_LOG.md
disable-model-invocation: true
---
 
When invoked, review the conversation and create a summary with these sections:
 
- **Date/time**: Current timestamp
- **Tasks completed**: What was accomplished
- **Files modified**: List of files created or changed
- **Decisions made**: Architectural or implementation choices
- **Open questions**: Unresolved items for future sessions
 
Append the summary to SESSION_LOG.md in the project root. Create the file if it doesn't exist.

La línea « disable-model-invocation: true » le dice a Claude que solo tú,, puedes activar esta habilidad. Sin esta bandera, Claude podría decidir ejecutar el comando de forma autónoma si cree que eso ayuda a la conversación. Para una herramienta de registro o implementación, normalmente se prefiere el control manual.

Prueba localmente

Ve a cualquier proyecto en el que quieras utilizar el complemento y, a continuación, inicia Claude Code con la --plugin-dir indicando tu complemento:

cd ~/your-project
claude --plugin-dir ~/session-logger

Escribe « /session-logger:summarize » para ejecutar el comando. Ten en cuenta que los comandos de los complementos no aparecen en las sugerencias de autocompletado hasta que escribes el nombre completo. El texto se vuelve azul una vez que Claude Code lo reconoce como un comando válido.

Después de realizar algunas tareas en la sesión, ejecuta el comando. Claude revisa la conversación y añade una entrada a SESSION_LOG.md en el directorio actual de tu proyecto.

Compartir con otros

Envía tu complemento a GitHub. Para distribuirlo más allá de la clonación manual, añádelo a un mercado de complementos. La guía del mercado cubre la creación de tu propio mercado o la presentación a los ya existentes.

Conclusión

Los complementos convierten a Claude Code de un asistente de uso general en algo diseñado para tu flujo de trabajo específico. El registrador de sesiones que creamos tardó unos cinco minutos y ocupó tres archivos. La mayoría de los complementos útiles no son mucho más complicados que eso.

Si has seguido los pasos, ahora tendrás un complemento operativo en tu equipo. Intenta ajustarlo. Cambia el formato del resumen, añade nuevas secciones o sustitúyelo por algo que tu equipo realmente necesite. La estructura es la misma tanto si estás creando una herramienta personal rápida como si se trata de algo que vas a distribuir a cientos de programadores.

Explora los repositorios de la comunidad cuando tengas oportunidad. Ver cómo otros estructuran sus complementos te enseña patrones que la documentación no puede enseñarte. Y cuando crees algo útil, publícalo. El ecosistema crece con un complemento compartido cada vez.