Crear y distribuir un marketplace de plugins

​

Descripción general

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 el 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.

​

Tutorial: crear un marketplace local

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
---

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

​

Crear el archivo de marketplace

{
  "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

​

Entradas de plugins

​

Campos requeridos

​

Campos de plugin opcionales

​

Fuentes de plugins

​

Rutas relativas

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

​

Repositorios de GitHub

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

{
  "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"
  }
}

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

​

Subdirectorios de Git

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

{
  "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"
  }
}

​

Paquetes npm

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

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

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

​

Entradas de plugins avanzadas

{
  "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
}

• 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.
  • Consulte la tabla de sustitución para ver qué campos de configuración la sustituyen por tipo de servidor
  • 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.

"skills": ["./skills/", "./extra-skills/"]

"source": "./",
"skills": ["./skills/code-review", "./skills/docs"]

​

Modo estricto

• 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)

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

​

Alojar en otros servicios de git

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

​

Repositorios privados

• Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el clon existente cuando la extracción en segundo plano falla, en lugar de eliminar y re-clonar. Sus plugins siguen funcionando desde el último estado sincronizado, y las actualizaciones manuales con /plugin marketplace update aún extraen con sus credenciales.
• Configure un ayudante de credenciales de git, por ejemplo con gh auth setup-git para GitHub, para que la alternativa de re-clonado pueda autenticarse sin solicitar.

git config --global url."https://x-access-token:YOUR_TOKEN@github.com/acme-corp/plugins".insteadOf "https://github.com/acme-corp/plugins"

​

Probar localmente antes de la distribución

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

​

Requerir marketplaces para su equipo

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

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

​

Precargar plugins para contenedores

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

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

• 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

​

Configuraciones comunes

{
  "strictKnownMarketplaces": []
}

{
  "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"
    }
  ]
}

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

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

​

Cómo funcionan las restricciones

• 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

​

Resolución de versiones y canales de lanzamiento

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

​

Configurar canales de lanzamiento

{
  "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"
      }
    }
  ]
}

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

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

​

Fijar versiones de dependencias

​

Renombrar o eliminar un plugin

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "code-formatter", "source": "./plugins/code-formatter" }
  ],
  "renames": {
    "formatter": "code-formatter",
    "legacy-linter": null
  }
}

• Si la entrada apunta a un nuevo nombre, Claude Code carga el plugin bajo su nuevo nombre y muestra un aviso de una línea como Renamed to "code-formatter" in the "acme-tools" marketplace. Luego reescribe la clave anterior a la nueva clave en los ámbitos de configuración del usuario, proyecto y local para enabledPlugins y pluginConfigs, por lo que el aviso aparece una vez.
• Para una entrada null, Claude Code elimina la clave anterior y el aviso reporta que el plugin fue eliminado del marketplace.
• Si el plugin renombrado usa una fuente remota como github o npm, Claude Code reporta plugin-cache-miss después del renombramiento y el usuario debe ejecutar /plugin install una vez para obtenerlo bajo el nuevo nombre.

​

Validación y pruebas

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

Administrar marketplaces desde la CLI

​

Plugin marketplace add

claude plugin marketplace add <source> [options]

• <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

claude plugin marketplace add acme-corp/claude-plugins

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

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

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

claude plugin marketplace add ./my-marketplace

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

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

​

Plugin marketplace list

claude plugin marketplace list [options]

​

Plugin marketplace remove

claude plugin marketplace remove <name> [options]

• <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

​

Plugin marketplace update

claude plugin marketplace update [name]

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

​

Solución de problemas

​

Marketplace no se carga

• 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

• incluye plugins cuya source es .
• se ejecuta cuando marketplace.json está fuera de un directorio .claude-plugin, resolviendo fuentes contra el directorio del archivo en sí
• reporta los problemas de cada entrada incluso cuando otra parte del archivo tiene errores de esquema

• 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

• 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 en la mayoría de los hosts de git, incluyendo GitHub, GitLab y Bitbucket. En servidores que no soportan obtener commits por SHA, como AWS CodeCommit, el ref aún debe existir y el commit fijado debe ser alcanzable desde él. 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

• 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

• Por defecto, las actualizaciones en segundo plano desactivan los ayudantes de credenciales de git para la extracción, por lo que la extracción no puede autenticarse sobre HTTPS. Los remotos SSH con una clave cargada en ssh-agent aún se autentican. Una extracción fallida desencadena un re-clonado desde cero, que usa sus credenciales almacenadas pero puede agotar el tiempo de espera en repositorios grandes
• Establezca CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1 para mantener el clon existente cuando la extracción en segundo plano falla
• Configure un ayudante de credenciales de git, por ejemplo gh auth setup-git, para que el re-clonado fallback pueda autenticarse
• Si el re-clonado agota el tiempo de espera en un repositorio grande, aumente el límite con CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS
• Configure una reescritura de URL de git limitada al repositorio del marketplace para que la extracción en segundo plano se autentique directamente
• O actualice marketplaces privados manualmente con /plugin marketplace update <name>, que usa sus credenciales

​

Las actualizaciones del marketplace fallan en entornos sin conexión

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

​

Las operaciones de Git agotan el tiempo de espera

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000  # 5 minutos

​

Los plugins con rutas relativas fallan en marketplaces basados en URL

• 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

​

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