Saltar al contenido principal
Si mantienes una CLI o SDK y tienes un plugin en el marketplace oficial de Anthropic, tu herramienta puede solicitar a los usuarios de Claude Code que instalen ese plugin. Tu CLI escribe un marcador de una línea en stderr cuando detecta que se está ejecutando dentro de Claude Code. Claude Code lee el marcador, lo elimina de la salida y muestra al usuario un mensaje de instalación de una sola vez. Claude Code elimina la línea de sugerencia de la salida del comando antes de enviarla al modelo, por lo que el marcador nunca aparece en la conversación y no se cuenta hacia el uso de tokens. El protocolo no requiere comandos adicionales y no cambia lo que tu CLI imprime para usuarios fuera de Claude Code. Esta página es para mantenedores de CLI y SDK. Si buscas instalar plugins, consulta Descubre e instala plugins.

​
Cómo funciona

Claude Code establece la variable de entorno CLAUDECODE en 1 para cada comando que ejecuta a través de las herramientas Bash y PowerShell, y para comandos de hook. Cuando tu CLI ve esa variable, escribe una etiqueta <claude-code-hint /> que se cierra automáticamente en stderr. En comandos hook la etiqueta de sugerencia se elimina e ignora. Solo la salida de las herramientas Bash y PowerShell activa el mensaje de instalación. Cuando Claude Code recibe la salida del comando, hace lo siguiente:
  1. Busca líneas de sugerencia y las elimina antes de que la salida llegue al modelo
  2. Verifica que la sugerencia apunte a un plugin en un marketplace oficial de Anthropic
  3. Verifica que el plugin no esté ya instalado y no haya sido sugerido antes
  4. Muestra al usuario un mensaje de instalación que nombra el comando que emitió la sugerencia
Claude Code nunca instala un plugin automáticamente. El usuario siempre confirma.

​
Emite la sugerencia

Condiciona la emisión en la variable de entorno CLAUDECODE para que el marcador nunca aparezca en la terminal de un usuario humano. Luego escribe la etiqueta en stderr en su propia línea. Los siguientes ejemplos emiten una sugerencia para un plugin llamado example-cli en el marketplace oficial: 
if (process.env.CLAUDECODE) {
  process.stderr.write(
    '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
  )
}
Reemplaza example-cli con el nombre de tu plugin en el marketplace oficial.

​
Elige dónde emitir

Controlas qué rutas de código emiten la sugerencia. Claude Code deduplica por plugin, por lo que emitir en cada invocación no tiene desventajas. Los puntos de contacto que funcionan bien incluyen:
UbicaciónPor qué funciona
Salida de --helpClaude a menudo ejecuta help al explorar una CLI desconocida
Errores de subcomando desconocidoLlega al momento en que Claude está confundido sobre tu interfaz
Éxito de inicio de sesión o autenticaciónEl usuario ya está en una mentalidad de configuración
Mensaje de bienvenida de primera ejecuciónUn momento natural de incorporación

​
Lo que ve el usuario

Cuando la sugerencia pasa todas las verificaciones, Claude Code muestra un mensaje como el siguiente: 
─────────────────────────────────────────────────────────────
  Recomendación de Plugin

    El comando example-cli sugiere instalar un plugin.

    Plugin: example-cli
    Marketplace: claude-plugins-official
    Integración oficial para implementaciones de example-cli

    ¿Te gustaría instalarlo?
    ❯ 1. Sí, instalar example-cli
      2. No
      3. No, y no mostrar sugerencias de instalación de plugins nuevamente

─────────────────────────────────────────────────────────────
El mensaje nombra el comando que produjo la sugerencia para que los usuarios puedan detectar una discrepancia entre la herramienta y el plugin que recomienda. Si el usuario no responde dentro de 30 segundos, el mensaje se descarta como No. La frecuencia del mensaje está limitada:
  • Una vez por plugin: después de que se muestre el mensaje, Claude Code registra el plugin y nunca vuelve a solicitar para él, independientemente de la respuesta del usuario.
  • Una vez por sesión: en todas las CLI de la máquina, como máximo aparece un mensaje de sugerencia por sesión de Claude Code.
Seleccionar Sí instala el plugin en el ámbito del usuario. Seleccionar No, y no mostrar sugerencias de instalación de plugins nuevamente desactiva todos los mensajes de sugerencia futuros para el usuario.

​
Formato de sugerencia

La sugerencia es una etiqueta que se cierra automáticamente con tres atributos requeridos. 
<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
AtributoRequeridoDescripción
vSíVersión del protocolo. 1 es el único valor soportado
typeSíTipo de sugerencia. plugin es el único valor soportado
valueSíIdentificador del plugin en forma name@marketplace
Los valores de atributo pueden estar entrecomillados con comillas dobles o dejarse sin comillas. Los valores sin comillas no pueden contener espacios en blanco. Las secuencias de escape no son compatibles.

​
Requisitos

Claude Code aplica dos condiciones antes de actuar sobre una sugerencia. Las sugerencias que fallan en cualquiera de las verificaciones se descartan:
  • Línea propia: la etiqueta debe ocupar su propia línea. Una etiqueta incrustada a mitad de línea, por ejemplo dentro de una declaración de registro, se ignora. Se permite espacios en blanco al principio y al final de la línea.
  • Marketplace oficial: el value debe hacer referencia a un plugin en un marketplace controlado por Anthropic como claude-plugins-official. Las sugerencias que apuntan a otros marketplaces se descartan silenciosamente.
La línea de sugerencia siempre se elimina de la salida antes de que llegue al modelo, incluso cuando la versión o el tipo no se reconocen, por lo que el marcador nunca se cuenta hacia el uso de tokens. La orientación restante se recomienda pero no se aplica. Claude Code no puede observar si tu CLI la sigue:
  • Escribe en stderr: stderr mantiene la etiqueta fuera de tuberías de shell como example-cli deploy | jq. Claude Code escanea ambas secuencias, por lo que stdout también funciona.
  • Condiciona en CLAUDECODE: solo emite cuando la variable de entorno CLAUDECODE está establecida. Esto evita que el marcador aparezca a los usuarios que ejecutan tu CLI directamente.

​
Obtén tu plugin en el marketplace oficial

El protocolo de sugerencia solo tiene efecto para plugins que se enumeran en el marketplace oficial de Anthropic, claude-plugins-official. Anthropic cura ese marketplace a su discreción, y los formularios de envío en la aplicación agregan plugins al marketplace de la comunidad en su lugar, que el protocolo de sugerencia no verifica. Si trabajas con un contacto de socio de Anthropic, comunícate con ellos para coordinar una enumeración en el marketplace oficial.

​
Ver también