Crear y distribuir un marketplace de plugins

Cree y aloje marketplaces de plugins para distribuir extensiones de Claude Code en equipos y comunidades.

Un marketplace de plugins es un catálogo que le permite distribuir plugins a otros. Los marketplaces proporcionan descubrimiento centralizado, seguimiento de versiones, actualizaciones automáticas y soporte para múltiples tipos de fuentes (repositorios git, rutas locales y más). Esta guía le muestra cómo crear su propio marketplace para compartir plugins con su equipo o comunidad.

¿Busca instalar plugins desde un marketplace existente? Consulte Descubrir e instalar plugins precompilados.

Descripción general

Crear y distribuir un marketplace implica:

1. Crear plugins: construya uno o más plugins con skills, agentes, hooks, servidores MCP o servidores LSP. Esta guía asume que ya tiene plugins para distribuir; consulte Crear plugins para obtener detalles sobre cómo crearlos.
2. Crear un archivo de marketplace: defina un marketplace.json que enumere sus plugins y dónde encontrarlos (consulte Crear el archivo de marketplace).
3. Alojar el marketplace: envíe a GitHub, GitLab u otro host git (consulte Alojar y distribuir marketplaces).
4. Compartir con usuarios: los usuarios agregan su marketplace con /plugin marketplace add e instalan plugins individuales (consulte Descubrir e instalar plugins).

Una vez que su marketplace esté activo, puede actualizarlo enviando cambios a su repositorio. Los usuarios actualizan su copia local con /plugin marketplace update.

Tutorial: crear un marketplace local

Este ejemplo crea un marketplace con un plugin: una skill quality-review para revisiones de código. Creará la estructura de directorios, agregará una skill, creará el manifiesto del plugin y el catálogo del marketplace, luego lo instalará y probará.

mkdir -p my-marketplace/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/.claude-plugin
mkdir -p my-marketplace/plugins/quality-review-plugin/skills/quality-review

---
description: Review code for bugs, security, and performance
disable-model-invocation: true
---

Review the code I've selected or the recent changes for:
- Potential bugs or edge cases
- Security concerns
- Performance issues
- Readability improvements

Be concise and actionable.

{
"name": "quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews",
"version": "1.0.0"
}

{
"name": "my-plugins",
"owner": {
"name": "Your Name"
},
"plugins": [
{
"name": "quality-review-plugin",
"source": "./plugins/quality-review-plugin",
"description": "Adds a quality-review skill for quick code reviews"
}
]
}

/plugin marketplace add ./my-marketplace
/plugin install quality-review-plugin@my-plugins

/quality-review-plugin:quality-review

Para obtener más información sobre lo que los plugins pueden hacer, incluidos hooks, agentes, servidores MCP y servidores LSP, consulte Plugins.

Crear el archivo de marketplace

Cree .claude-plugin/marketplace.json en la raíz de su repositorio. Este archivo define el nombre de su marketplace, información del propietario y una lista de plugins con sus fuentes.

Cada entrada de plugin necesita como mínimo un name y source (dónde obtenerlo). Consulte el esquema completo a continuación para todos los campos disponibles.

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "devtools@example.com"
  },
  "plugins": [
    {
      "name": "code-formatter",
      "source": "./plugins/formatter",
      "description": "Automatic code formatting on save",
      "version": "2.1.0",
      "author": {
        "name": "DevTools Team"
      }
    },
    {
      "name": "deployment-tools",
      "source": {
        "source": "github",
        "repo": "company/deploy-plugin"
      },
      "description": "Deployment automation tools"
    }
  ]
}

Esquema de marketplace

Campos requeridos

Campos del propietario

Campos opcionales

description y version también se aceptan bajo metadata para compatibilidad con versiones anteriores.

Entradas de plugins

Cada entrada de plugin en el array plugins describe un plugin y dónde encontrarlo. Puede incluir cualquier campo del esquema de manifiesto de plugin (como description, version, author, commands, hooks, etc.), más estos campos específicos del marketplace: source, category, tags y strict.

Campos requeridos

Campos de plugin opcionales

Campos de metadatos estándar:

Campos de configuración de componentes:

Fuentes de plugins

Las fuentes de plugins le indican a Claude Code dónde obtener cada plugin individual listado en su marketplace. Estos se establecen en el campo source de cada entrada de plugin en marketplace.json.

Una vez que un plugin se clona o copia en la máquina local, se copia en el caché de plugins versionado local en ~/.claude/plugins/cache.

Los tipos de fuente basados en git que se muestran a continuación son github, url y git-subdir. Cuando tanto ref como sha se establecen en cualquiera de ellos, sha es el pin efectivo. Claude Code obtiene y verifica el commit fijado directamente, por lo que la instalación tiene éxito incluso si la rama o etiqueta nombrada por ref ha sido eliminada posteriormente, siempre que el commit aún sea alcanzable desde el repositorio.

Rutas relativas

Para plugins en el mismo repositorio, use una ruta que comience con ./:

{
  "name": "my-plugin",
  "source": "./plugins/my-plugin"
}

Las rutas se resuelven relativas a la raíz del marketplace, que es el directorio que contiene .claude-plugin/. En el ejemplo anterior, ./plugins/my-plugin apunta a <repo>/plugins/my-plugin, aunque marketplace.json vive en <repo>/.claude-plugin/marketplace.json. No use ../ para hacer referencia a rutas fuera de la raíz del marketplace.

Repositorios de GitHub

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "github-plugin",
  "source": {
    "source": "github",
    "repo": "owner/plugin-repo",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Repositorios de Git

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "git-plugin",
  "source": {
    "source": "url",
    "url": "https://gitlab.com/team/plugin.git",
    "ref": "main",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

Subdirectorios de Git

Use git-subdir para apuntar a un plugin que vive dentro de un subdirectorio de un repositorio de git. Claude Code usa un clon parcial y escaso para obtener solo el subdirectorio, minimizando el ancho de banda para monorepos grandes.

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin"
  }
}

Puede fijar a una rama, etiqueta o commit específico:

{
  "name": "my-plugin",
  "source": {
    "source": "git-subdir",
    "url": "https://github.com/acme-corp/monorepo.git",
    "path": "tools/claude-plugin",
    "ref": "v2.0.0",
    "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
  }
}

El campo url también acepta una abreviatura de GitHub (owner/repo) o URLs SSH (git@github.com:owner/repo.git).

Paquetes npm

Los plugins distribuidos como paquetes npm se instalan usando npm install. Esto funciona con cualquier paquete en el registro npm público o un registro privado que su equipo aloje.

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin"
  }
}

Para fijar a una versión específica, agregue el campo version:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "2.1.0"
  }
}

Para instalar desde un registro privado o interno, agregue el campo registry:

{
  "name": "my-npm-plugin",
  "source": {
    "source": "npm",
    "package": "@acme/claude-plugin",
    "version": "^2.0.0",
    "registry": "https://npm.example.com"
  }
}

Entradas de plugins avanzadas

Este ejemplo muestra una entrada de plugin usando muchos de los campos opcionales, incluidas rutas personalizadas para commands, agents, hooks y MCP servers:

{
  "name": "enterprise-tools",
  "source": {
    "source": "github",
    "repo": "company/enterprise-plugin"
  },
  "description": "Enterprise workflow automation tools",
  "version": "2.1.0",
  "author": {
    "name": "Enterprise Team",
    "email": "enterprise@example.com"
  },
  "homepage": "https://docs.example.com/plugins/enterprise-tools",
  "repository": "https://github.com/company/enterprise-plugin",
  "license": "MIT",
  "keywords": ["enterprise", "workflow", "automation"],
  "category": "productivity",
  "commands": [
    "./commands/core/",
    "./commands/enterprise/",
    "./commands/experimental/preview.md"
  ],
  "agents": ["./agents/security-reviewer.md", "./agents/compliance-checker.md"],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
          }
        ]
      }
    ]
  },
  "mcpServers": {
    "enterprise-db": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
    }
  },
  "strict": false
}

Cosas clave a notar:

• commands y agents: Puede especificar múltiples directorios o archivos individuales. Las rutas son relativas a la raíz del plugin.
• ${CLAUDE_PLUGIN_ROOT}: Use esta variable en hooks y configuraciones de MCP server para hacer referencia a archivos dentro del directorio de instalación del plugin. Esto es necesario porque los plugins se copian a una ubicación de caché cuando se instalan. Para dependencias o estado que deben sobrevivir a las actualizaciones de plugins, use ${CLAUDE_PLUGIN_DATA} en su lugar.
• strict: false: Dado que esto se establece en false, el plugin no necesita su propio plugin.json. La entrada del marketplace define todo. Consulte Modo estricto a continuación.

Por defecto, las skills de un plugin se cargan desde el directorio skills/ bajo su source, y cualquier ruta listada bajo skills se agrega a ese escaneo. La excepción es una fuente de raíz de marketplace como source: "./", donde varias entradas de plugin comparten una carpeta skills/. En ese caso, listar subdirectorios específicos bajo skills hace que esa lista sea el conjunto completo para la entrada, y otros directorios bajo skills/ no se cargan. Listar el directorio skills/ en sí o la raíz del plugin mantiene el escaneo completo. Si ninguna de las rutas listadas existe, se ejecuta el escaneo predeterminado en su lugar.

Modo estricto

El campo strict controla si plugin.json es la autoridad para definiciones de componentes (skills, agents, hooks, MCP servers, estilos de salida).

Cuándo usar cada modo:

• strict: true: el plugin tiene su propio plugin.json y gestiona sus propios componentes. La entrada del marketplace puede agregar skills o hooks adicionales encima. Este es el predeterminado y funciona para la mayoría de los plugins.
• strict: false: el operador del marketplace quiere control total. El repositorio del plugin proporciona archivos sin procesar, y la entrada del marketplace define cuáles de esos archivos se exponen como skills, agents, hooks, etc. Útil cuando el marketplace reestructura o cura los componentes de un plugin de manera diferente a la que el autor del plugin pretendía.

Alojar y distribuir marketplaces

Alojar en GitHub (recomendado)

GitHub proporciona el método de distribución más fácil:

1. Crear un repositorio: Configure un nuevo repositorio para su marketplace
2. Agregar archivo de marketplace: Cree .claude-plugin/marketplace.json con sus definiciones de plugins
3. Compartir con equipos: Los usuarios agregan su marketplace con /plugin marketplace add owner/repo

Beneficios: Control de versiones integrado, seguimiento de problemas y características de colaboración en equipo.

Alojar en otros servicios de git

Cualquier servicio de alojamiento de git funciona, como GitLab, Bitbucket y servidores autohospedados. Los usuarios agregan con la URL completa del repositorio:

/plugin marketplace add https://gitlab.com/company/plugins.git

Repositorios privados

Claude Code soporta instalar plugins desde repositorios privados. Para instalación manual y actualizaciones, Claude Code usa sus ayudantes de credenciales de git existentes, por lo que el acceso HTTPS a través de gh auth login, Keychain de macOS o git-credential-store funciona igual que en su terminal. El acceso SSH funciona siempre que el host ya esté en su archivo known_hosts y la clave esté cargada en ssh-agent, ya que Claude Code suprime los mensajes interactivos de SSH para la huella digital del host y la contraseña de la clave.

Las actualizaciones automáticas en segundo plano se ejecutan al inicio sin ayudantes de credenciales, ya que los mensajes interactivos bloquearían que Claude Code se inicie. Para habilitar actualizaciones automáticas para marketplaces privados, establezca el token de autenticación apropiado en su entorno:

Establezca el token en su configuración de shell (por ejemplo, .bashrc, .zshrc) o páselo al ejecutar Claude Code:

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Probar localmente antes de la distribución

Pruebe su marketplace localmente antes de compartirlo:

/plugin marketplace add ./my-local-marketplace
/plugin install test-plugin@my-local-marketplace

Para el rango completo de comandos add (GitHub, URLs de Git, rutas locales, URLs remotas), consulte Agregar marketplaces.

Requerir marketplaces para su equipo

Puede configurar su repositorio para que los miembros del equipo sean automáticamente solicitados para instalar su marketplace cuando confíen en la carpeta del proyecto. Agregue su marketplace a .claude/settings.json:

{
  "extraKnownMarketplaces": {
    "company-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

También puede especificar qué plugins deben estar habilitados de forma predeterminada:

{
  "enabledPlugins": {
    "code-formatter@company-tools": true,
    "deployment-tools@company-tools": true
  }
}

Para opciones de configuración completas, consulte Configuración de plugins.

Precargar plugins para contenedores

Para imágenes de contenedor y entornos de CI, puede precargar un directorio de plugins en tiempo de compilación para que Claude Code comience con marketplaces y plugins ya disponibles, sin clonar nada en tiempo de ejecución. Establezca la variable de entorno CLAUDE_CODE_PLUGIN_SEED_DIR para apuntar a este directorio.

Para superponer múltiples directorios seed, separe las rutas con : en Unix o ; en Windows. Claude Code busca cada directorio en orden, y el primer seed que contiene un marketplace o caché de plugin dado gana.

El directorio seed refleja la estructura de ~/.claude/plugins:

$CLAUDE_CODE_PLUGIN_SEED_DIR/
  known_marketplaces.json
  marketplaces/<name>/...
  cache/<marketplace>/<plugin>/<version>/...

Para construir un directorio seed, ejecute Claude Code una vez durante la compilación de la imagen, instale los plugins que necesita, luego copie el directorio ~/.claude/plugins resultante en su imagen y apunte CLAUDE_CODE_PLUGIN_SEED_DIR a él.

Para omitir el paso de copia, establezca CLAUDE_CODE_PLUGIN_CACHE_DIR en su ruta de seed de destino durante la compilación para que los plugins se instalen directamente allí:

CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin marketplace add your-org/plugins
CLAUDE_CODE_PLUGIN_CACHE_DIR=/opt/claude-seed claude plugin install my-tool@your-plugins

Luego establezca CLAUDE_CODE_PLUGIN_SEED_DIR=/opt/claude-seed en el entorno de tiempo de ejecución de su contenedor para que Claude Code lea desde el seed al inicio.

Al inicio, Claude Code registra los marketplaces encontrados en el known_marketplaces.json del seed en la configuración principal, y usa cachés de plugins encontrados bajo cache/ en su lugar sin re-clonar. Esto funciona tanto en modo interactivo como en modo no interactivo con la bandera -p.

Detalles de comportamiento:

• Solo lectura: el directorio seed nunca se escribe. Las actualizaciones automáticas están deshabilitadas para marketplaces seed ya que git pull fallaría en un sistema de archivos de solo lectura.
• Las entradas seed tienen precedencia: los marketplaces declarados en el seed sobrescriben cualquier entrada coincidente en la configuración del usuario en cada inicio. Para optar por no participar en un plugin seed, use /plugin disable en lugar de eliminar el marketplace.
• Resolución de rutas: Claude Code localiza contenido de marketplace sondeando $CLAUDE_CODE_PLUGIN_SEED_DIR/marketplaces/<name>/ en tiempo de ejecución, no confiando en rutas almacenadas dentro del JSON del seed. Esto significa que el seed funciona correctamente incluso cuando se monta en una ruta diferente a donde fue construido.
• Se bloquea la mutación: ejecutar /plugin marketplace remove o /plugin marketplace update contra un marketplace administrado por seed falla con orientación para pedir a su administrador que actualice la imagen seed.
• Se compone con configuración: si extraKnownMarketplaces o enabledPlugins declaran un marketplace que ya existe en el seed, Claude Code usa la copia del seed en lugar de clonar.

Restricciones de marketplace administrado

Para organizaciones que requieren control estricto sobre las fuentes de plugins, los administradores pueden restringir qué marketplaces de plugins se permite a los usuarios agregar usando la configuración strictKnownMarketplaces en configuración administrada.

Cuando strictKnownMarketplaces se configura en configuración administrada, el comportamiento de restricción depende del valor:

Configuraciones comunes

Deshabilitar todas las adiciones de marketplace:

{
  "strictKnownMarketplaces": []
}

Permitir solo marketplaces específicos:

{
  "strictKnownMarketplaces": [
    {
      "source": "github",
      "repo": "acme-corp/approved-plugins"
    },
    {
      "source": "github",
      "repo": "acme-corp/security-tools",
      "ref": "v2.0"
    },
    {
      "source": "url",
      "url": "https://plugins.example.com/marketplace.json"
    }
  ]
}

Permitir todos los marketplaces desde un servidor git interno usando coincidencia de patrón regex en el host. Este es el enfoque recomendado para GitHub Enterprise Server o instancias de GitLab autohospedadas:

{
  "strictKnownMarketplaces": [
    {
      "source": "hostPattern",
      "hostPattern": "^github\\.example\\.com$"
    }
  ]
}

Permitir marketplaces basados en sistema de archivos desde un directorio específico usando coincidencia de patrón regex en la ruta:

{
  "strictKnownMarketplaces": [
    {
      "source": "pathPattern",
      "pathPattern": "^/opt/approved/"
    }
  ]
}

Use ".*" como pathPattern para permitir cualquier ruta del sistema de archivos mientras aún controla fuentes de red con hostPattern.

Cómo funcionan las restricciones

Las restricciones se validan antes de cualquier operación de red o del sistema de archivos. La verificación se ejecuta al agregar marketplace y al instalar, actualizar, actualizar y auto-actualizar plugins. Si un marketplace se agregó antes de que se configurara la política y su fuente ya no coincide con la lista de permitidos, Claude Code se niega a instalar o actualizar plugins desde él. La misma aplicación se aplica a blockedMarketplaces.

La lista de permitidos usa coincidencia exacta para la mayoría de tipos de fuente. Para que un marketplace sea permitido, todos los campos especificados deben coincidir exactamente:

• Para fuentes de GitHub: repo es requerido, y ref o path también deben coincidir si se especifican en la lista de permitidos
• Para fuentes de URL: la URL completa debe coincidir exactamente
• Para fuentes hostPattern: el host del marketplace se compara contra el patrón regex
• Para fuentes pathPattern: la ruta del sistema de archivos del marketplace se compara contra el patrón regex

La coincidencia exacta no normaliza URLs: una barra diagonal final, sufijo .git o forma ssh:// versus https:// se tratan como valores diferentes. Si el marketplace de su organización se puede clonar por más de una forma de URL, prefiera una entrada hostPattern sobre una URL literal para que todas las formas coincidan.

Debido a que strictKnownMarketplaces se establece en configuración administrada, los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.

Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con extraKnownMarketplaces, consulte la referencia de strictKnownMarketplaces.

Resolución de versiones y canales de lanzamiento

Las versiones de plugins determinan rutas de caché y detección de actualizaciones: si la versión resuelta coincide con lo que un usuario ya tiene, /plugin update y auto-actualización omiten el plugin.

Claude Code resuelve la versión de un plugin desde el primero de estos que esté establecido:

1. version en el plugin.json del plugin
2. version en la entrada del marketplace del plugin
3. El SHA del commit de git de la fuente del plugin

Para los tipos de fuente basados en git github, url, git-subdir y rutas relativas dentro de un marketplace alojado en git, puede omitir version completamente y cada nuevo commit se trata como una nueva versión. Esta es la configuración más simple para plugins internos o en desarrollo activo.

Configurar canales de lanzamiento

Para soportar canales de lanzamiento "estable" y "último" para sus plugins, puede configurar dos marketplaces que apunten a diferentes refs o SHAs del mismo repositorio. Luego puede asignar los dos marketplaces a diferentes grupos de usuarios a través de configuración administrada.

Ejemplo

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "stable"
      }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": {
        "source": "github",
        "repo": "acme-corp/code-formatter",
        "ref": "latest"
      }
    }
  ]
}

Asignar canales a grupos de usuarios

Asigne cada marketplace al grupo de usuarios apropiado a través de configuración administrada. Por ejemplo, el grupo estable recibe:

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/stable-tools"
      }
    }
  }
}

El grupo de acceso temprano recibe latest-tools en su lugar:

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": {
        "source": "github",
        "repo": "acme-corp/latest-tools"
      }
    }
  }
}

Fijar versiones de dependencias

Un plugin puede restringir sus dependencias a un rango semver para que las actualizaciones de una dependencia no rompan el plugin dependiente. Consulte Restringir versiones de dependencias de plugins para la convención de etiqueta de git {plugin-name}--v{version}, sintaxis de rango y cómo se combinan múltiples restricciones en la misma dependencia.

Validación y pruebas

Pruebe su marketplace antes de compartirlo.

Valide la sintaxis JSON de su marketplace:

claude plugin validate .

O desde dentro de Claude Code:

/plugin validate .

Agregue el marketplace para pruebas:

/plugin marketplace add ./path/to/marketplace

Instale un plugin de prueba para verificar que todo funciona:

/plugin install test-plugin@marketplace-name

Para flujos de trabajo completos de prueba de plugins, consulte Pruebe sus plugins localmente. Para solución de problemas técnicos, consulte Referencia de plugins.

Administrar marketplaces desde la CLI

Claude Code proporciona subcomandos no interactivos claude plugin marketplace para scripting y automatización. Estos son equivalentes a los comandos /plugin marketplace disponibles dentro de una sesión interactiva.

Plugin marketplace add

Agregue un marketplace desde un repositorio de GitHub, URL de git, URL remota o ruta local.

claude plugin marketplace add <source> [options]

Argumentos:

• <source>: Abreviatura de GitHub owner/repo, URL de git, URL remota a un archivo marketplace.json o ruta de directorio local. Para fijar a una rama o etiqueta, agregue @ref a la abreviatura de GitHub o #ref a una URL de git

Opciones:

Agregue un marketplace desde GitHub usando la abreviatura owner/repo:

claude plugin marketplace add acme-corp/claude-plugins

Fije a una rama o etiqueta específica con @ref:

claude plugin marketplace add acme-corp/claude-plugins@v2.0

Agregue desde una URL de git en un host que no sea GitHub:

claude plugin marketplace add https://gitlab.example.com/team/plugins.git

Agregue desde una URL remota que sirva el archivo marketplace.json directamente:

claude plugin marketplace add https://example.com/marketplace.json

Agregue desde un directorio local para pruebas:

claude plugin marketplace add ./my-marketplace

Declare el marketplace en alcance de proyecto para que se comparta con su equipo a través de .claude/settings.json:

claude plugin marketplace add acme-corp/claude-plugins --scope project

Para un monorepo, limite el checkout a los directorios que contienen contenido de plugins:

claude plugin marketplace add acme-corp/monorepo --sparse .claude-plugin plugins

Plugin marketplace list

Enumere todos los marketplaces configurados.

claude plugin marketplace list [options]

Opciones:

Con --json, cada entrada incluye name, source y campos específicos de la fuente: repo para fuentes de GitHub, url para fuentes de git y URL, y path para fuentes locales. Las fuentes de GitHub y git también incluyen un campo ref cuando el marketplace se agregó con una rama o etiqueta fija.

Plugin marketplace remove

Elimine un marketplace configurado. El alias rm también se acepta.

claude plugin marketplace remove <name> [options]

Argumentos:

• <name>: nombre del marketplace a eliminar, como se muestra en claude plugin marketplace list. Este es el name de marketplace.json, no la fuente que pasó a add

Opciones:

Plugin marketplace update

Actualice marketplaces desde sus fuentes para recuperar nuevos plugins y cambios de versión.

claude plugin marketplace update [name]

Argumentos:

• [name]: nombre del marketplace a actualizar, como se muestra en claude plugin marketplace list. Actualiza todos los marketplaces si se omite

Tanto remove como update fallan cuando se ejecutan contra un marketplace administrado por seed, que es de solo lectura. Al actualizar todos los marketplaces, las entradas administradas por seed se omiten y otros marketplaces aún se actualizan. Para cambiar plugins proporcionados por seed, pida a su administrador que actualice la imagen seed. Consulte Precargar plugins para contenedores.

Solución de problemas

Marketplace no se carga

Síntomas: No puede agregar marketplace o ver plugins de él

Soluciones:

• Verifique que la URL del marketplace sea accesible
• Compruebe que .claude-plugin/marketplace.json existe en la ruta especificada
• Asegúrese de que la sintaxis JSON sea válida usando claude plugin validate o /plugin validate. Para verificar el frontmatter de skill, agente y comando, ejecute el comando contra cada directorio de plugin
• Para repositorios privados, confirme que tiene permisos de acceso

Errores de validación de marketplace

Ejecute claude plugin validate . o /plugin validate . desde su directorio de marketplace para verificar problemas. Cuando se apunta a un directorio de marketplace, el validador verifica solo marketplace.json: esquema, nombres de plugins duplicados, traversal de ruta de fuente y desajustes de versión contra cada plugin.json referenciado.

Para validar el plugin.json de un plugin individual y sus archivos de skill, agente, comando y hook, ejecute el comando contra el directorio del plugin en sí, por ejemplo claude plugin validate ./plugins/my-plugin. Errores comunes:

Advertencias (no bloqueantes):

• Marketplace has no plugins defined: agregue al menos un plugin al array plugins
• No marketplace description provided: agregue una description de nivel superior para ayudar a los usuarios a entender su marketplace
• Plugin name "x" is not kebab-case: el nombre del plugin contiene letras mayúsculas, espacios o caracteres especiales. Renombre a letras minúsculas, dígitos y guiones solamente (por ejemplo, my-plugin). Claude Code acepta otras formas, pero la sincronización del marketplace de Claude.ai las rechaza.

Fallos de instalación de plugins

Síntomas: El marketplace aparece pero la instalación del plugin falla

Soluciones:

• Verifique que las URLs de fuente del plugin sean accesibles
• Compruebe que los directorios de plugins contengan archivos requeridos
• Para fuentes de GitHub, asegúrese de que los repositorios sean públicos o tenga acceso
• Pruebe las fuentes de plugins manualmente clonando/descargando
• Si la fuente fija tanto ref como sha, una rama o etiqueta ascendente eliminada no bloquea la instalación. Si la instalación aún falla, confirme que el commit fijado aún existe en el repositorio

La autenticación del repositorio privado falla

Síntomas: Errores de autenticación al instalar plugins desde repositorios privados

Soluciones:

Para instalación manual y actualizaciones:

• Verifique que esté autenticado con su proveedor de git (por ejemplo, ejecute gh auth status para GitHub)
• Compruebe que su ayudante de credenciales esté configurado correctamente: git config --global credential.helper
• Intente clonar el repositorio manualmente para verificar que sus credenciales funcionan

Para actualizaciones automáticas en segundo plano:

• Establezca el token apropiado en su entorno: echo $GITHUB_TOKEN
• Compruebe que el token tiene los permisos requeridos (acceso de lectura al repositorio)
• Para GitHub, asegúrese de que el token tiene el alcance repo para repositorios privados
• Para GitLab, asegúrese de que el token tiene al menos alcance read_repository
• Verifique que el token no haya expirado

Las actualizaciones del marketplace fallan en entornos sin conexión

Síntomas: El git pull del marketplace falla y Claude Code borra el caché existente, causando que los plugins se vuelvan no disponibles.

Causa: Por defecto, cuando un git pull falla, Claude Code elimina el clon obsoleto e intenta re-clonar. En entornos sin conexión o aislados, el re-clonado falla de la misma manera, dejando el directorio del marketplace vacío.

Solución: Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el caché existente cuando el pull falla en lugar de borrarlo:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

Con esta variable establecida, Claude Code retiene el clon obsoleto del marketplace en fallo de git pull y continúa usando el último estado conocido bueno. Para implementaciones completamente sin conexión donde el repositorio nunca será alcanzable, use CLAUDE_CODE_PLUGIN_SEED_DIR para precargar el directorio de plugins en tiempo de compilación en su lugar.

Las operaciones de Git agotan el tiempo de espera

Síntomas: La instalación del plugin o las actualizaciones del marketplace fallan con un error de tiempo de espera como "Git clone timed out after 120s" o "Git pull timed out after 120s".

Causa: Claude Code usa un tiempo de espera de 120 segundos para todas las operaciones de git, incluida la clonación de repositorios de plugins y la extracción de actualizaciones de marketplace. Los repositorios grandes o las conexiones de red lentas pueden exceder este límite.

Solución: Aumente el tiempo de espera usando la variable de entorno CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS. El valor está en milisegundos:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutos

Los plugins con rutas relativas fallan en marketplaces basados en URL

Síntomas: Agregó un marketplace a través de URL (como https://example.com/marketplace.json), pero los plugins con fuentes de ruta relativa como "./plugins/my-plugin" fallan al instalar con errores "path not found".

Causa: Los marketplaces basados en URL solo descargan el archivo marketplace.json en sí. No descargan archivos de plugins del servidor. Las rutas relativas en la entrada del marketplace hacen referencia a archivos en el servidor remoto que no fueron descargados.

Soluciones:

• Use fuentes externas: Cambie las entradas de plugins para usar fuentes de GitHub, npm o URL de git en lugar de rutas relativas:

  { "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }
  

• Use un marketplace basado en Git: Aloje su marketplace en un repositorio de Git y agréguelo con la URL de git. Los marketplaces basados en Git clonan el repositorio completo, haciendo que las rutas relativas funcionen correctamente.

Archivos no encontrados después de la instalación

Síntomas: El plugin se instala pero las referencias a archivos fallan, especialmente archivos fuera del directorio del plugin

Causa: Los plugins se copian a un directorio de caché en lugar de usarse en el lugar. Las rutas que hacen referencia a archivos fuera del directorio del plugin (como ../shared-utils) no funcionarán porque esos archivos no se copian.

Soluciones: Consulte Plugin caching and file resolution para soluciones alternativas incluyendo enlaces simbólicos y reestructuración de directorios.

Para herramientas de depuración adicionales y problemas comunes, consulte Debugging and development tools.

Ver también

• Descubrir e instalar plugins precompilados - Instalación de plugins desde marketplaces existentes
• Plugins - Creación de sus propios plugins
• Referencia de plugins - Especificaciones técnicas completas y esquemas
• Configuración de plugins - Opciones de configuración de plugins
• Referencia de strictKnownMarketplaces - Restricciones de marketplace administrado