Crear y distribuir un marketplace de plugins

​

Descripción general

1. Crear plugins: construya uno o más plugins con comandos, agentes, hooks, MCP servers 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).

​

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

​

Crear el archivo de marketplace

{
  "name": "company-tools",
  "owner": {
    "name": "DevTools Team",
    "email": "[email protected]"
  },
  "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

​

Metadatos 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": "[email protected]"
  },
  "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. 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.

​

Modo estricto

• strict: true: el plugin tiene su propio plugin.json y gestiona sus propios componentes. La entrada del marketplace puede agregar comandos 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 comandos, agentes, 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

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

​

Probar localmente antes de la distribución

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

​

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

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

​

Configurar canales de lanzamiento

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

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

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

​

Validación y pruebas

claude plugin validate .

/plugin validate .

/plugin marketplace add ./path/to/marketplace

/plugin install test-plugin@marketplace-name

​

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 y el frontmatter esté bien formado usando claude plugin validate o /plugin validate
• Para repositorios privados, confirme que tiene permisos de acceso

​

Errores de validación de marketplace

• Marketplace has no plugins defined: agregue al menos un plugin al array plugins
• No marketplace description provided: agregue metadata.description 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

​

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

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