Guía: tu primer plugin de Claude

1. Antes de empezar: ¿realmente necesitas un plugin?

Responde estas dos preguntas antes de seguir.

¿Tienes al menos tres skills funcionando que usas cada semana?

Si la respuesta es no, cierra esta guía y construye los skills primero. Un plugin sin skills probados es un recetario que nadie va a abrir. Empieza con un solo SKILL.md en ~/.claude/skills/ o dentro de tu proyecto en .claude/skills/, pruébalo durante dos semanas, y cuando tengas tres o cuatro de la misma función, vuelves acá.

¿Vas a compartirlo con alguien que no eres tú?

Si no, tampoco lo necesitas. Para uso personal, los skills sueltos funcionan igual y son más rápidos de iterar. El plugin existe para que tu equipo, tu cliente, o la comunidad puedan instalar tu stack con un comando, no como vitrina personal.

Si pasaste las dos preguntas, sigue.

2. La estructura mínima

Un plugin es una carpeta. Adentro tiene un manifiesto, y el resto son las piezas que empaquetas. Esta es la estructura completa, con todo lo opcional incluido:

mi-plugin/
├── .claude-plugin/
│   └── plugin.json          ← manifiesto (obligatorio)
├── skills/                  ← tus skills
│   ├── primer-skill/
│   │   └── SKILL.md
│   └── segundo-skill/
│       └── SKILL.md
├── agents/                  ← sub-agentes (opcional)
├── hooks/
│   └── hooks.json           ← eventos automáticos (opcional)
├── .mcp.json                ← conectores MCP (opcional)
├── commands/                ← slash commands (opcional)
└── README.md                ← documentación (muy recomendado)

Trampa importante: solo plugin.json va dentro de .claude-plugin/. Todas las demás carpetas van al nivel raíz. Es el error más común y la doc oficial lo señala explícitamente.

3. Plantilla de plugin.json lista para copiar

Crea el archivo en mi-plugin/.claude-plugin/plugin.json con esto:

{
  "name": "mi-plugin",
  "description": "Una línea que describe qué hace el plugin y para quién es.",
  "version": "1.0.0",
  "author": {
    "name": "Tu Nombre",
    "email": "tu@email.com",
    "url": "https://tusitio.com"
  },
  "homepage": "https://github.com/tu-usuario/tu-plugin",
  "repository": "https://github.com/tu-usuario/tu-plugin",
  "license": "MIT",
  "keywords": ["ventas", "automatizacion", "crm"]
}

Reglas mínimas:

• name es el namespace de tus skills. Si tu plugin se llama taveras-ventas y adentro tienes skills/cobrar-cliente/, el skill se invoca como /taveras-ventas:cobrar-cliente. Elígelo bien porque cambiarlo después rompe a tus usuarios.
• description aparece en el marketplace. Que sea específica, no genérica. "Automatiza el ciclo completo de cobro a clientes con Stripe + email + actualización de CRM" funciona. "Herramientas útiles para ventas" no.
• version controla las actualizaciones. Si la omites y distribuyes vía git, cada commit cuenta como versión nueva. Para distribución seria, bumpéala manualmente cuando publiques cambios.

Lo demás es opcional pero recomendado. homepage y repository apuntan a tu repo de GitHub. keywords ayuda a la búsqueda en el marketplace de comunidad.

4. Árbol de decisión: qué 3 skills agrupar primero

La pregunta correcta no es "¿qué plugin puedo construir?" sino "¿qué tres skills uso juntos cada semana?". Esos tres son tu primer plugin.

Si vendes servicios profesionales (consultoría, desarrollo, diseño, marketing)

Plugin sugerido: ventas-cliente

1. Skill que califica leads o redacta respuestas a prospectos
2. Skill que arma cotizaciones o links de pago
3. Skill que actualiza tu CRM o pipeline después del cobro

Conector MCP recomendado adentro: Stripe + tu CRM (HubSpot, GHL, Notion).

Si creas contenido (creador, agencia, marca personal)

Plugin sugerido: contenido-publicacion

1. Skill que escribe guiones o copy en tu voz
2. Skill que arma posts para distintas plataformas a partir de un mismo concepto
3. Skill que analiza qué funcionó (engagement, stats) y sugiere el siguiente

Conector MCP recomendado: Notion para tu pipeline + redes (si hay MCP disponible).

Si operas un negocio con clientes recurrentes (SaaS, suscripciones, e-commerce)

Plugin sugerido: operaciones-cliente

1. Skill que audita estado de cuenta y detecta churn temprano
2. Skill que redacta comunicaciones de renovación o reactivación
3. Skill que reporta métricas semanales

Conector MCP recomendado: Stripe + tu base de datos de clientes.

Si eres developer o trabajas con código

Plugin sugerido: dev-workflow

1. Skill que hace code review según tus reglas
2. Skill que genera tests o documentación
3. Hook que corre lint o tests automáticamente después de un edit

Conector MCP recomendado: GitHub + tu issue tracker.

La regla detrás del árbol

Tres skills probados, todos del mismo flujo de trabajo, todos accionables en un día normal. Si tienes que explicarle a alguien para qué sirve el plugin con más de una frase, la agrupación está mal. Vuelve a la lista de skills que usas y busca el cluster real.

5. Probar localmente antes de publicar

No subas nada a GitHub sin haberlo probado. Desde tu terminal, corres:

claude --plugin-dir ./mi-plugin

Eso carga el plugin en una sesión de Claude Code sin tener que instalarlo. Si modificas algo, dentro de la sesión corres /reload-plugins y recarga sin reiniciar.

Verifica tres cosas antes de pasar al siguiente paso:

1. Que tus skills aparezcan al correr /help con el namespace correcto (/mi-plugin:nombre-del-skill)
2. Que Claude los dispare cuando le hablas natural — no solo cuando los invocas por slash
3. Que las descripciones de los skills sean lo suficientemente específicas para que Claude sepa cuándo usarlos

Si un skill no se dispara solo, el problema casi siempre está en la descripción del frontmatter. Hazla más larga y más específica.

6. Subirlo a GitHub

Una vez que el plugin funciona local, lo subes a un repo público. Desde la carpeta de tu plugin:

git init
git add .
git commit -m "primer plugin"
git branch -M main
git remote add origin https://github.com/tu-usuario/mi-plugin.git
git push -u origin main

Asegúrate que el repo sea público si quieres distribuirlo. Si es para tu equipo interno, mantenlo privado pero los miembros del equipo necesitan acceso al repo para instalarlo.

7. Crear tu propio marketplace

Un marketplace es solo otro repo de GitHub que lista tus plugins. Puedes tener un repo por plugin, o un marketplace que agrupe varios. Lo segundo escala mejor.

Crea un repo nuevo, por ejemplo taveras-marketplace, con esta estructura:

taveras-marketplace/
├── .claude-plugin/
│   └── marketplace.json
├── mi-plugin/                    ← copia o submodule
└── otro-plugin/                  ← copia o submodule

El archivo marketplace.json se ve así:

{
  "name": "taveras-tools",
  "owner": {
    "name": "Tu Nombre",
    "url": "https://tusitio.com"
  },
  "description": "Plugins para automatizar ventas, contenido y operaciones.",
  "plugins": [
    {
      "name": "mi-plugin",
      "source": "./mi-plugin",
      "description": "Lo que hace este plugin específicamente."
    },
    {
      "name": "otro-plugin",
      "source": "./otro-plugin",
      "description": "Lo que hace el otro."
    }
  ]
}

Subes ese repo a GitHub. Ya tienes un marketplace propio.

8. Cómo instalan tu plugin tus usuarios

Una vez publicado, cualquier persona con Claude Code instalado puede agregar tu marketplace y bajar el plugin con dos comandos:

claude plugin marketplace add tu-usuario/taveras-marketplace
claude plugin install mi-plugin@taveras-tools

Si quieres que aparezca en el marketplace público de la comunidad de Anthropic, lo envías en claude.ai/settings/plugins/submit. Antes de enviarlo, corre claude plugin validate para que pase la misma validación que ellos van a aplicar.

9. Errores que vas a cometer (y cómo evitarlos)

Meter las carpetas dentro de .claude-plugin/. Solo plugin.json va ahí. Las demás carpetas (skills/, agents/, hooks/) van al nivel raíz del plugin.

Empezar por el plugin antes que por los skills. Si no tienes skills probados, no tienes plugin. Tienes una carpeta vacía con buenas intenciones.

Descripciones genéricas en el plugin.json. Si la descripción es vaga, nadie va a instalarlo y Claude no va a saber cuándo recomendarlo. Sé específico sobre el caso de uso exacto.

No bumpear la versión. Si distribuyes vía git sin version, cada commit es una versión nueva y tus usuarios reciben cambios que no esperan. Pon version explícita y bumpéala cuando publiques.

Empaquetar conectores MCP sensibles sin documentar. Si tu plugin lleva conectores que requieren claves o tokens, escríbelo claro en el README. Nadie debería instalar algo y descubrir tarde que necesita configurar tres credenciales.

10. Próximo paso

Abre tu lista de skills actuales. Identifica el grupo de tres que más usas. Ese es tu primer plugin. Sigue los pasos 2, 3 y 4 de esta guía hoy mismo, prueba local con --plugin-dir, y mañana lo subes.

Si tienes dudas concretas en algún paso, escríbeme un DM. Si quieres compartir el repo cuando lo tengas listo, también — me interesa ver qué arman ustedes.

Erik Taveras · taverassolutions.com