Cómo convertí mi repo de skills en un marketplace de Claude Code

Hasta hace nada, instalar una skill de mi repo de skills para Claude Code era copiar carpetas a mano. Y con save-image, además, había que editar el settings.json para registrar el hook, con una ruta local fija. Funcionaba, pero era un engorro, y actualizar era volver a copiarlo todo.

Así que he convertido el repo en un marketplace de plugins de Claude Code. Ahora instalar es un comando y actualizar, otro. En este post cuento cómo se hace paso a paso, con los archivos reales del repo, y los tropiezos que me encontré, que son lo que de verdad te va a ahorrar tiempo.

El empujón vino de la última skill que he publicado, senior-mindset, que hace que Claude programe como un senior pragmático. Lo que hace la skill lo cuento en su propio post: senior-mindset, la skill para que Claude Code programe como un senior. Aquí va la parte de fontanería.

Qué es un marketplace de plugins en Claude Code

Un plugin es una carpeta que Claude Code sabe instalar: puede llevar skills, hooks y otras piezas. Un marketplace es un catálogo de plugins: un repositorio (o una carpeta) con un archivo que dice qué plugins hay y dónde está cada uno.

La gracia es que quien lo usa no copia nada. Añade el marketplace una vez, instala el plugin que quiere por su nombre y, cuando subes una versión nueva, la actualiza con un comando. Y si el plugin trae hooks, quedan registrados solos. Se acabó lo de editar el settings.json a mano.

Las tres formas de instalar una skill de mi repo

Antes de entrar en cómo se monta, así queda la instalación ahora. Hay tres formas, y valen para todas las skills del repo.

1. Desde el marketplace, que es la novedad y la que yo recomiendo:

/plugin marketplace add MarcosRamirez/SKILLS
/plugin install senior-mindset@marcosramirez-skills

¿Por qué esta? Porque al instalarla con /plugin install, Claude Code la gestiona como un plugin, y eso te permite actualizarla después y recargarla con /reload-plugins sin cerrar la sesión. Con las otras dos formas no tienes nada de eso: es una carpeta copiada que se queda como estaba.

Para actualizar después, según el README del repo:

claude plugin marketplace update marcosramirez-skills
claude plugin update senior-mindset@marcosramirez-skills

2. Pedírselo al agente, pegando la URL de la skill en GitHub:

Install the senior-mindset skill from https://github.com/MarcosRamirez/SKILLS/tree/master/skills/senior-mindset
into ~/.claude/skills/senior-mindset. Copy the whole folder, including references/.

3. A mano, con git clone y copiando la carpeta:

git clone --depth 1 https://github.com/MarcosRamirez/SKILLS.git /tmp/skills
cp -r /tmp/skills/skills/senior-mindset ~/.claude/skills/senior-mindset

Las skills con hooks, como save-image, necesitan un paso extra si las instalas a mano. Lo explica su README. Con el marketplace, ese paso desaparece.

Paso 1: el marketplace.json en la raíz del repo

Lo que convierte un repo en un marketplace es un único archivo: .claude-plugin/marketplace.json en la raíz. Lleva un name, un owner y la lista plugins. Cada plugin tiene su name, su description y un source que apunta a su carpeta. El mío:

{
  "name": "marcosramirez-skills",
  "owner": {
    "name": "Marcos Ramírez",
    "url": "https://github.com/MarcosRamirez"
  },
  "description": "Plug-and-play Claude Code skills by Marcos Ramírez",
  "plugins": [
    {
      "name": "save-image",
      "source": "./skills/save-image",
      "description": "Paste an image in Claude Code and it lands on disk automatically — no filenames, no export dialogs"
    },
    {
      "name": "senior-mindset",
      "source": "./skills/senior-mindset",
      "description": "Claude builds software like a pragmatic senior engineer: spec first, ADRs, reuse, readable, secure, tested code"
    }
  ]
}

El name del marketplace es lo que va detrás de la arroba al instalar: senior-mindset@marcosramirez-skills. La description de cada plugin es la línea que la gente ve al lado cuando explora el marketplace desde /plugin.

El source: empieza por ./ y no sale del repo

El source tiene que empezar por ./ y no puede salir del repo. La ruta se escribe desde la raíz del marketplace, que es la carpeta que contiene .claude-plugin/, no desde dentro de .claude-plugin/.

La documentación oficial explica que los dos errores típicos fallan en sitios distintos, y conviene saberlo:

• Una ruta con ..: claude plugin validate la marca como inválida.
• Una ruta a una carpeta que no existe: la validación pasa, pero claude plugin install falla con Source path does not exist.

Es decir, que validar no basta: hay que instalar al menos una vez antes de compartirlo.

Según esa misma documentación, el source también puede apuntar fuera del repo (otro repositorio de GitHub, una subcarpeta de un monorepo, un paquete de npm…). En mi caso todos los plugins viven dentro del repo, así que me basta con rutas relativas.

Paso 2: un plugin.json (opcional) en cada skill

Cada skill puede llevar su propio .claude-plugin/plugin.json con name, version, description, author, license y demás. El de senior-mindset:

{
  "name": "senior-mindset",
  "version": "1.0.0",
  "description": "Claude builds software like a pragmatic senior engineer: spec first, ADRs, reuse, readable, secure, tested code",
  "author": {
    "name": "Marcos Ramírez",
    "url": "https://marcosramirez.info"
  },
  "homepage": "https://github.com/MarcosRamirez/SKILLS/tree/master/skills/senior-mindset",
  "repository": "https://github.com/MarcosRamirez/SKILLS",
  "license": "MIT"
}

El campo version decide cómo llegan las actualizaciones

Ojo con version, porque cambia cómo le llegan las actualizaciones a la gente:

• Si fijas version, quien tenga el plugin instalado solo recibe actualizaciones cuando la subes.
• Si no la pones, cada commit cuenta como una versión nueva.

Ninguna de las dos es mejor por sí misma. Si haces muchos commits pequeños y no quieres que cada uno llegue a la gente, fija la versión. Si prefieres que todo llegue en cuanto lo subes, déjala fuera.

El nombre del plugin, igual en los dos sitios

La documentación avisa de otra cosa: el name de la entrada en marketplace.json y el name del plugin.json deberían ser el mismo. El primero es el que se escribe para instalar; el segundo es el prefijo de las skills del plugin. Si no coinciden, instalar por el nombre del manifiesto falla con un error de plugin no encontrado. En mi repo son iguales, así que no me tocó pelearme con eso.

Paso 3: los hooks, sin tocar el settings.json

Esta era la parte fea de save-image. Ahora el hook va en hooks/hooks.json dentro de la carpeta de la skill, usando ${CLAUDE_PLUGIN_ROOT} en vez de una ruta fija:

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python",
            "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/save-image-hook.py"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

${CLAUDE_PLUGIN_ROOT} es la carpeta donde quede instalado el plugin, esté donde esté en la máquina de cada uno. El hook queda registrado solo al instalar el plugin.

Y un aviso importante para quien ya tuviera save-image instalada a mano: si tenías el hook en tu settings.json, quítalo, o se ejecutará dos veces.

Paso 4: validar y probar en local

Antes de publicar, toca validar. En la raíz del repo, y luego cada plugin en modo estricto:

claude plugin validate .
claude plugin validate ./skills/senior-mindset --strict

La validación revisa la sintaxis del JSON, los campos obligatorios, los nombres y las rutas, y también el plugin.json de cada plugin. Lo que no revisa (como que la carpeta del source exista de verdad) aparece al instalar.

Para probar el marketplace en tu máquina antes de subirlo:

claude plugin marketplace add ./

Con un marketplace local y rutas relativas, Claude Code lee los archivos directamente de tu carpeta, así que los cambios se aplican al empezar una sesión nueva o con /reload-plugins, sin tocar la versión. Quien lo instala desde GitHub, en cambio, recibe una copia.

Cómo se actualizan las skills

Instalas una skill hoy y mañana yo la cambio. ¿Cómo te llega el cambio? Depende de cómo la instalaste.

Si la instalaste desde el marketplace

Según la documentación sobre mantener un marketplace, tienes dos opciones.

La cómoda: activar la actualización automática. Viene desactivada por defecto, y no es algo que yo pueda encender desde el repo: lo activa cada usuario. Entra en /plugin, ve a Marketplaces, elige marcosramirez-skills y selecciona Enable auto-update. A partir de ahí, las versiones nuevas te llegan solas en segundo plano.

La manual: actualizar cuando quieras. Dentro de una sesión de Claude Code:

/plugin marketplace update marcosramirez-skills

O desde la terminal, primero el catálogo y luego el plugin:

claude plugin marketplace update marcosramirez-skills
claude plugin update senior-mindset@marcosramirez-skills

Y una vez actualizada, un /reload-plugins dentro de la sesión carga la versión nueva sin tener que cerrar Claude Code y volver a abrirlo. Es la razón por la que recomiendo instalar siempre con /plugin install.

Solo te llega si cambia la versión

Aquí vuelve a salir el campo version del paso 2. Claude Code solo te descarga una copia nueva cuando la versión calculada del plugin es distinta de la que tienes. Mis plugins llevan la versión fijada en su plugin.json, así que lo que te llega son las versiones que publico, no cada commit que hago. Si un plugin no tuviera version, cada commit contaría como una versión nueva.

Un detalle que avisa la documentación: la versión se pone en el plugin.json o en la entrada del marketplace.json, no en los dos. Si están en los dos sitios, manda la del plugin.json sin avisar, y claude plugin validate te marca la diferencia.

Si la instalaste a mano o se la pediste al agente

Entonces no hay nada que la actualice: es una copia de la carpeta y se queda como estaba. Para ponerla al día, repite la instalación (vuelve a clonar el repo y copia la carpeta encima) o vuelve a pedírselo al agente con la misma URL. Esta es la razón principal para usar el marketplace: con él, actualizar es un comando o directamente nada.

Lo que aprendí montando el marketplace

Esto es lo que no venía en ningún sitio, o venía pero no lo vi hasta que me tropecé con ello:

• No hizo falta reestructurar nada. Un SKILL.md en la raíz de la carpeta del plugin ya se carga como skill. Mis carpetas de skills/ valían tal cual.
• Al instalar, Claude Code copia a una caché solo la carpeta del plugin. Cualquier archivo que el plugin necesite (scripts, referencias, plantillas) tiene que estar dentro de esa carpeta. Nada de apuntar a algo que vive en la raíz del repo, porque en la máquina del que lo instala no va a estar.
• claude plugin marketplace add . falla. Devuelve Invalid marketplace source format. Hay que poner ./, con la barra. Dos caracteres que me costaron un rato.
• La skill instalada lleva el nombre del plugin delante: queda como /senior-mindset:senior-mindset. Aun así, Claude la carga sola cuando la descripción encaja con lo que le pides, así que en el día a día ni lo notas.

Ninguno de estos tropiezos es grave, pero juntos se comen una tarde. Y casi todos tienen la misma raíz: un plugin instalado no vive en tu repo, vive en una copia. En cuanto lo interiorizas, la mitad de los problemas dejan de aparecer.

Si tu empresa quiere distribuir sus propias skills y plugins internos para Claude Code, escríbeme.

Cómo añadir tu propia skill al repo

El repo está abierto a contribuciones. Si tienes una skill que hace mejor a Claude en algo, el proceso es el mismo que he seguido yo:

• Una carpeta por skill en skills/<nombre>/, con su SKILL.md y su README.md.
• Un .claude-plugin/plugin.json dentro y una entrada en el .claude-plugin/marketplace.json de la raíz.
• Pasar claude plugin validate . y claude plugin validate ./skills/<nombre> --strict.
• Licencia MIT.

Todo está en github.com/MarcosRamirez/SKILLS.

Preguntas frecuentes

¿Qué archivo convierte un repositorio en un marketplace de plugins de Claude Code?

Un .claude-plugin/marketplace.json en la raíz del repo, con name, owner y la lista plugins. Cada plugin indica su source, que debe ser una ruta que empiece por ./ y no salga del repositorio.

¿Cómo se instala un plugin desde un marketplace de Claude Code?

Se añade el marketplace con /plugin marketplace add usuario/repo y se instala el plugin con /plugin install nombre@marketplace. Por ejemplo: /plugin marketplace add MarcosRamirez/SKILLS y /plugin install senior-mindset@marcosramirez-skills.

¿Es obligatorio el campo version en plugin.json?

No. Si lo fijas, la gente solo recibe actualizaciones cuando subes la versión. Si no lo pones, cada commit cuenta como una versión nueva.

¿Por qué falla claude plugin marketplace add con un punto?

Porque claude plugin marketplace add . devuelve Invalid marketplace source format. Para añadir un marketplace local hay que escribir la ruta con barra: claude plugin marketplace add ./.

Fuentes

• Claude Code: Create a plugin marketplace (documentación oficial)
• Claude Code: Host and maintain a marketplace (documentación oficial)
• Repositorio MarcosRamirez/SKILLS en GitHub

Compártelo si te ha resultado útil.

¿Tienes alguna skill propia que te gustaría compartir como plugin? Cuéntame.

Y… si montas tu propio marketplace, me cuentas qué tropiezos te encontraste tú.