El 24 de febrero de 2026, Anthropic anunció marketplaces privados de plugins para Claude Code, dándoles a los administradores una forma de construir, alojar y controlar plugins sin tocar los registros públicos de Anthropic. Lo que obtendrás de este artículo: los pasos exactos para agrupar una habilidad e integrarla en un plugin distribuible, alojarlo en un repositorio privado de GitHub, fijar versiones y diagnosticar los problemas más comunes cuando una segunda máquina se niega a instalar de forma limpia.
Cuando un equipo necesita un plugin
El marketplace público está bien para experimentar individualmente. Una vez que tienes más de una persona dependiendo del mismo comando de barra o del mismo script de hook, la distribución ad-hoc colapsa rápidamente. Alguien copia un archivo manualmente, usa una ruta ligeramente diferente, y Claude Code silenciosamente ignora el hook porque el nombre no coincide con lo que el registro espera.
Ese es el disparador real de un marketplace privado: consistencia entre máquinas, no cantidad de usuarios. Si tienes dos desarrolladores y ambos necesitan el mismo hook de despliegue, un marketplace privado vale la hora de configuración. Si tienes veinte, no es opcional.
El otro disparador es la confidencialidad. La documentación de creación de plugins de Anthropic es explícita: para mantener un plugin interno en tu equipo, alojas el marketplace en un repositorio privado. Enviar a claude-community publica tu plugin para que cualquiera lo vea e instale. Un repositorio privado evita eso completamente. Si tu plugin contiene patrones de API internos, comandos de barra propietarios, o cualquier cosa que prefieras no indexar, la ruta privada es la correcta.
Cabe destacar: si tu equipo ya está ejecutando servidores MCP en producción, verifica cómo la distribución privada de plugins se ajusta junto a esa pila antes de comprometerte con una estructura, ya que los dos enfoques tienen casos de uso que se superponen pero son distintos.
Agrupa una habilidad existente y un hook
Un plugin es una carpeta. Esa es la resumen honesto. Según la documentación oficial de plugins, la estructura mínima viable se ve así:
my-plugin/
plugin.json
README.md
skills/
my-skill.md
hooks/
hooks.json
guard.sh
El plugin.json es el manifiesto. Nombra el plugin, declara una versión y apunta a los subdirectorios de habilidades y hooks. Un ejemplo ilustrativo abreviado:
{
"name": "deployment-tools",
"version": "1.2.0",
"description": "Deployment workflow helpers for the platform team",
"skills": ["skills/"],
"hooks": "hooks/hooks.json"
}
Las habilidades son archivos markdown que definen lo que Claude sabe cómo hacer, y los comandos de barra viven dentro de ellos. Los hooks son declaraciones JSON que conectan scripts de shell a puntos de disparo (antes de una llamada de herramienta, después de una sesión, y así sucesivamente). Puedes agrupar cualquier combinación de los dos en una única carpeta de plugin. La documentación de habilidades señala que los comandos personalizados ahora son parte del modelo de habilidades, así que no intentes mantenerlos como un sistema paralelo separado.
Una cosa que atrapa a la gente: los scripts de hook deben ser ejecutables. Ejecuta chmod +x hooks/guard.sh antes de hacer commit. Claude Code verifica el bit de permiso e ignorará silenciosamente un hook si no está establecido.
Crea y distribuye un marketplace privado
Un marketplace es un repositorio de GitHub con una estructura de carpeta específica. Cada plugin vive en su propio subdirectorio. En la raíz del repositorio necesitas un registry.json que catalogue lo que está disponible. La documentación del plugin marketplace describe esta estructura en detalle, y la demostración comunitaria en mrlm-xyz/demo-claude-marketplace muestra dos plugins de ejemplo funcionando con agentes, comandos y habilidades si quieres una referencia concreta antes de construir desde cero.
Una vez que el repositorio exista, cuéntale a Claude Code sobre él en .claude/settings.json en la raíz del repositorio:
{
"extraKnownMarketplaces": {
"company-tools": {
"source": {
"source": "github",
"repo": "your-org/claude-plugins"
}
}
},
"enabledPlugins": {
"deployment-tools@company-tools": true,
"code-formatter@company-tools": true
}
}
Confirma ese archivo. Ahora cada miembro del equipo que confía en la carpeta del proyecto obtiene el marketplace agregado automáticamente, sin indicación separada ni paso manual por CLI. El bloque enabledPlugins significa que esos dos plugins están activos por defecto. Cualquiera que no los quiera puede deshabilitarlos localmente; los valores por defecto solo eliminan fricción para todos los demás.
Si estás en un plan Team o Enterprise y distribuyendo a través de configuración de Organización, el repositorio del marketplace debe ser privado o interno. La Claude GitHub App lo lee, así que necesitarás concederle acceso explícitamente. Un repositorio público falla silenciosamente en ese camino, que es uno de los modos de error más confusos.
Para equipos que manejan trabajo de Claude Code orientado al cliente a escala, los servicios de agencia Claude Code de Seahawk manejan la configuración del marketplace y la gobernanza de plugins en curso si prefieres no tener esa infraestructura por tu cuenta.
Controla versiones y revisa actualizaciones
Aquí es donde la mayoría de los marketplaces privados fracasan. Las personas fijan una versión en plugin.json, insertan un cambio que rompe compatibilidad bajo la misma etiqueta, y se preguntan por qué la reversión no funcionó. Las etiquetas de Git son la unidad correcta de verdad de versión aquí, no solo la cadena de versión en el manifiesto.
El flujo de trabajo que realmente funciona:
- Aumenta el campo
versionenplugin.json(sigue semver:1.2.0a1.3.0para adiciones compatibles hacia atrás,2.0.0para cambios que rompen compatibilidad). - Confirma e inserta.
- Crea una etiqueta de git:
git tag v1.3.0 && git push origin v1.3.0. - Actualiza
registry.jsonpara que la entrada del plugin apunte a la nueva etiqueta.
Para instalar una versión específica en una máquina:
/plugin install deployment-tools@company-tools --version 1.3.0
Para revertir a la etiqueta anterior:
/plugin install deployment-tools@company-tools --version 1.2.0
La bandera --version se resuelve contra etiquetas de git en el repositorio de origen. Si no has etiquetado, Claude Code cae de nuevo a HEAD de la rama por defecto, lo que significa que "reversión" es sin sentido. Etiqueta cada lanzamiento. Toma diez segundos y evita dolor real.
Para revisión de actualizaciones, trata el repositorio del marketplace como cualquier otro código base de producción: requiere una solicitud de extracción, como mínimo una aprobación, y una entrada de registro de cambios en README.md antes de fusionar a main. La documentación propia de Anthropic señala que los plugins son componentes altamente confiables que pueden ejecutar código arbitrario, así que una política de una-persona-puede-fusionar en un repositorio de plugins es mala idea independientemente del tamaño del equipo.
Prueba la instalación en una segunda máquina
Antes de que le digas al equipo más amplio que extraiga el nuevo plugin, instálalo en un perfil completamente nuevo. No una ventana de terminal diferente. Un perfil nuevo sin secretos integrados, sin estado de plugin existente, y sin entradas de marketplace preconfiguradas más allá de lo que está en settings.json del repositorio.
Lista de verificación numerada para una prueba limpia en segunda máquina:
- Clona el repositorio del proyecto.
- Abre Claude Code y confía en la carpeta cuando se te solicite.
- Confirma que el marketplace aparece con
/plugin marketplace list. - Instala el plugin explícitamente:
/plugin install deployment-tools@company-tools. - Ejecuta el comando slash que expone el plugin y verifica que devuelva el resultado esperado.
- Comprueba que el hook se ejecuta al activar la llamada de herramienta relevante e inspecciona el resultado.
- Verifica que no aparezcan credenciales ni rutas locales de tu máquina de desarrollo en la respuesta.
Esta última verificación es importante. Los scripts de hooks que hacen referencia a rutas absolutas (/Users/yourname/scripts/...) se rompen en cualquier otra máquina. Usa rutas relativas al directorio del plugin o variables de entorno que los equipos puedan establecer de manera consistente.
Soluciona problemas de nombres, rutas y dependencias
La mayoría de los errores de instalación son una de tres cosas.
Discrepancias de nombres. El nombre del plugin en plugin.json debe coincidir exactamente con el nombre del directorio en el repositorio del marketplace y el nombre usado en registry.json. Distingue mayúsculas de minúsculas. Si plugin.json dice deployment-tools y la entrada del registro dice Deployment-Tools, el comando install devuelve un error de no encontrado que parece no estar relacionado con la capitalización.
Problemas de rutas en hooks. Como se mencionó antes, las rutas absolutas son la fuente más común de errores tipo "funciona en mi máquina". Audita cada script de hook para detectar rutas codificadas antes de etiquetar un lanzamiento. Un grep -r "/Users" hooks/ rápido detecta la más común.
Vacíos de dependencias. Si tu script de hook llama a un binario externo (jq, gh, docker, una CLI interna personalizada), documenta esa dependencia en README.md con la versión mínima. Claude Code no resuelve dependencias de binarios externos por ti. Un hook que sale silenciosamente porque jq no está instalado es difícil de diagnosticar, especialmente para un compañero de equipo que no sabe que el hook existe.
Hay otros detalles que vale la pena verificar si la instalación se atasca:
- La GitHub App necesita acceso de lectura al repositorio privado del marketplace. Comprueba la configuración de la Organización si la búsqueda se cuelga.
- Si
extraKnownMarketplacesestá ensettings.jsonpero el marketplace no aparece después de confiar en la carpeta, confirma que el archivo está comprometido y que la ventana de confianza fue aceptada, no descartada. - Los nombres de plugins en
enabledPluginsdeben usar el formatoname@marketplaceexactamente.deployment-toolssolo no se resolverá sin el calificador de marketplace.
La serie de dev.to de Nagell cubre versionado automático y CI de lanzamiento con más profundidad si deseas conectar GitHub Actions al flujo de etiquetado. Vale la pena leer antes de construir el paso de CI manualmente.
Para un contexto más amplio sobre cómo Claude Code se ajusta a un flujo de trabajo de desarrollo real más allá de solo plugins, esta descripción general de superpoderes de Claude Code es una compañera útil.
FAQ
¿Puedo alojar el marketplace en otro lugar que no sea GitHub?
El campo source en settings.json soporta github y local como tipos de source según los documentos actuales del marketplace de plugins. Una ruta local funciona para una sola máquina o un recurso compartido de red montado, pero no se actualiza automáticamente como lo hace una fuente respaldada por git. Para distribución en equipo con seguimiento de versiones, un repositorio GitHub privado es la opción práctica en este momento.
¿Los miembros del equipo necesitan su propio acceso a GitHub al repositorio privado del marketplace?
No directamente. Si distribuyes a través de la configuración de Organización en un plan Team o Enterprise, la GitHub App de Claude lee el repositorio en su nombre. Si usas extraKnownMarketplaces en settings.json sin la ruta de sincronización de org, cada usuario necesita acceso de lectura al repositorio a través de sus propias credenciales de GitHub o una deploy key.
¿Cuál es la diferencia entre `enabledPlugins` e instalar realmente un plugin?
enabledPlugins en settings.json activa plugins automáticamente cuando la carpeta del proyecto es confiable. Es un valor por defecto, no una instalación forzada. Un usuario aún puede desactivar un plugin localmente. Instalar manualmente a través de /plugin install añade el plugin sin importar lo que settings.json diga. Los dos mecanismos funcionan juntos: valores por defecto para conveniencia, instalación manual para cualquier cosa fuera del contexto del proyecto.
¿Puedo tener múltiples marketplaces privados en una organización?
Sí. El objeto extraKnownMarketplaces acepta múltiples claves. Cada clave es un alias de marketplace local, y cada una apunta a un repositorio source separado. Podrías tener company-tools, data-team-plugins y security-tools todos registrados en el mismo settings.json. Solo asegúrate de que los alias sean únicos y no colisionen con claude-plugins-official o claude-community.
¿Cómo interactúa esto con el mercado oficial de Anthropic?
Coexisten. Claude Code registra claude-plugins-official automáticamente en el primer lanzamiento interactivo. Tu mercado privado se suma a este. Los plugins de tu mercado privado se referencian como plugin-name@your-alias; los plugins oficiales como plugin-name@claude-plugins-official. Sin conflictos, siempre que tus nombres de plugin no dupliquen los oficiales y causen ambigüedad en la resolución.
La advertencia más importante de todo esto: los tags de git son el único mecanismo confiable para revertir cambios. Una cadena de versión en plugin.json sin un tag correspondiente es solo decoración, no una opción de recuperación.