La calidad que exige un plugin de producción
La diferencia de calidad entre un plugin que guardas en tus dotfiles personales y uno que publicas en un marketplace es abismal. El primero puede conformarse con "funciona en mi entorno"; el segundo debe contemplar la convivencia con distintos sistemas operativos, versiones de Node.js, shells y configuraciones existentes, además de la experiencia de onboarding y la estrategia de upgrades.
En abril de 2026, el marketplace oficial de plugins de Anthropic supera los 1.800 plugins publicados, pero apenas los 100 más populares alcanzan más de 1.000 instalaciones activas semanales. Lo que marca esa diferencia no es lo vistoso de las funciones, sino elementos más discretos: la calidad del manifiesto, la documentación, la disciplina en el versionado y el manejo correcto de la configuración del usuario.
Estructura estándar del repositorio
La estructura estándar de un repositorio de plugin es la siguiente.
``` my-claude-plugin/ ├── .claude-plugin/ │ └── plugin.json # Manifiesto (obligatorio) ├── commands/ # Slash commands │ ├── review.md │ └── deploy.md ├── skills/ # Skills │ └── security-audit/ │ └── SKILL.md ├── agents/ # Definiciones de subagentes │ └── researcher.md ├── hooks/ # Configuración de hooks │ └── hooks.json ├── mcp/ # Servidor MCP incluido │ ├── server.ts │ └── package.json ├── scripts/ # Scripts de instalación y migración │ └── postinstall.sh ├── README.md ├── CHANGELOG.md └── LICENSE ```
Repositorios populares como gsd-build/get-shit-done y wshobson/agents convergen casi siempre en esta estructura. En particular, colocar `.claude-plugin/plugin.json` en la raíz es una convención de facto obligatoria, ya que el comando `plugin add` del CLI de Anthropic busca ese path de forma fija.
Cómo escribir el manifiesto plugin.json
El `plugin.json` debe contener como mínimo los siguientes campos.
```json { "name": "gsd-build", "displayName": "Get Shit Done", "version": "2.4.1", "description": "Stop-hook driven task persistence for Claude Code", "author": { "name": "GSD Team", "url": "https://github.com/gsd-build" }, "license": "MIT", "homepage": "https://github.com/gsd-build/get-shit-done", "repository": "https://github.com/gsd-build/get-shit-done.git", "claudeCode": { "minVersion": "2.8.0" }, "commands": ["commands/"], "skills": ["skills/"], "agents": ["agents/"], "hooks": "hooks/hooks.json", "mcpServers": { "gsd-db": { "command": "node", "args": ["mcp/server.js"] } }, "configSchema": "config.schema.json", "telemetry": { "endpoint": "https://telemetry.gsd.dev/v1" } } ```
`claudeCode.minVersion` debe actualizarse cada vez que se introduzca un cambio que rompa la compatibilidad. El peor escenario de UX es que el plugin se instale en un CLI desactualizado y falle silenciosamente. `configSchema` provee validación de la configuración del usuario en formato JSON Schema, de modo que los errores de configuración muestren mensajes claros y útiles.
Versionado semántico en la práctica
El versionado de plugins sigue semver como base, pero determinar "qué cuenta como cambio que rompe compatibilidad" tiene sus propias dificultades. Cambiar el nombre de un slash command, modificar el `matcher` de un hook existente o agregar un campo obligatorio al `inputSchema` de una herramienta MCP son todos cambios que rompen la compatibilidad. En cambio, agregar nuevos comandos, añadir argumentos opcionales a comandos existentes o incorporar nuevas herramientas MCP son cambios de versión menor.
Para el `CHANGELOG.md` se recomienda firmemente el formato Keep a Changelog. La UI del marketplace parsea automáticamente ese archivo para mostrar el historial en la pantalla de actualización, por lo que mantener el formato uniforme tiene un beneficio directo. En KGA IT aplicamos este formato de forma obligatoria en todos los proyectos, incluidos los plugins internos.
Distribución en el marketplace
En abril de 2026 existen tres canales principales de distribución. El primero es el marketplace oficial de Anthropic (claude.ai/plugins): tiene proceso de revisión, pero ofrece la mayor visibilidad. El segundo es la instalación directa desde un repositorio de GitHub (`claude plugin add github.com/user/repo`): sin revisión, con efecto inmediato, por lo que es popular entre autores de proyectos open source. El tercero es el marketplace privado, donde las empresas hospedan un `claude-plugin-registry` propio para distribución interna.
En la revisión del marketplace oficial se evalúa la razonabilidad de la ejecución de comandos de shell, la declaración explícita de los destinos de red, el manejo de datos personales y, en el caso de plugins de pago, la seguridad del flujo de cobro. Desde febrero de 2026 existe el sistema de "audit badge": los plugins que superan el análisis estático reciben un distintivo verde. Los datos publicados muestran que la tasa de adopción es más del doble entre los plugins que cuentan con este badge, por lo que se recomienda obtenerlo.
Telemetría y observabilidad
Operar un plugin requiere entender quién lo usa y cómo. Sin embargo, los usuarios de Claude Code tienen alta conciencia sobre su privacidad, y cualquier telemetría opaca provoca desinstalaciones inmediatas. El enfoque recomendado se rige por tres principios: opt-in, anonimización y envío exclusivo de valores agregados.
En concreto, durante el primer arranque se muestra el prompt "¿Aceptas enviar estadísticas de uso anónimas?"; solo si el usuario responde afirmativamente se envía diariamente un ID de instalación y el número de llamadas por comando. El contenido de los prompts y las rutas de archivos nunca se envían bajo ninguna circunstancia. wshobson/agents usa este esquema para rankear los Subagent más adoptados y publica el resultado mensualmente en el README, lo que también funciona como señal de que el proyecto tiene una gestión transparente y saludable.
Seguimiento a las API que cambian
Desde la segunda mitad de 2025 Claude Code ha acelerado la incorporación de funcionalidades, y en ocasiones incluso versiones menores provocan que plugins existentes dejen de funcionar. Cuando Claude Code 3.0, en enero de 2026, cambió el contrato de los hooks y el paso de JSON por stdin se volvió obligatorio, unos 1.200 plugins tuvieron que actualizarse en un plazo de dos semanas.
La estrategia de mitigación opera en dos niveles. Primero, especificar `claudeCode.minVersion` de forma estricta en `plugin.json` para que el plugin no arranque en versiones de CLI sin soporte. Segundo, ejecutar tests de integración automatizados con `claude-code-nightly` en GitHub Actions para verificar el funcionamiento en nuevas versiones. Desde febrero Anthropic publica el `plugin-compat-matrix`, que muestra el estado de los plugins oficiales en cada versión del CLI. Los proyectos de terceros están adoptando el mismo esquema.
Estrategia de merge de la configuración del usuario
Los plugins escriben en `.claude/settings.json`, pero no deben destruir la configuración existente del usuario. La implementación recomendada es aplicar parches basados en JSON Pointer: al instalar el plugin, se guarda el parche diferencial en `.claude/plugins/<name>/applied-patch.json`, de modo que al desinstalar se pueda revertir con exactitud.
Hay que prestar especial atención al merge del array `permissions`. Para evitar conflictos con las reglas `allow`/`deny` existentes del usuario, la convención emergente es aislar las reglas propias del plugin con un prefijo de namespace (por ejemplo, `"gsd:*"`). get-shit-done adoptó este esquema de manera pionera y se ha convertido en la implementación de referencia para muchos plugins posteriores.
Operación tras la publicación
Publicar no es el punto final. La velocidad de respuesta inicial en GitHub Issues, la corrección inmediata ante una violación de semver, el proceso de publicación de avisos de seguridad y la notificación a usuarios de avisos de deprecación: todo esto determina la tasa de adopción a largo plazo. Cuanto más popular es un plugin, mayor es la carga operativa, y en algunos casos se vuelve necesario sumar mantenedores o incluso constituir una entidad legal.
En KGA IT, cuando entregamos plugins internos a clientes, empaquetamos el runbook operativo, el esquema de guardia y las reuniones trimestrales de revisión como parte del servicio. Un plugin no es un entregable: es un producto, y en el momento en que se publica en producción nace la responsabilidad de operarlo. Esa conciencia es la línea que separa un plugin profesional de uno de aficionado.