plugin-hints.md +0 −172 deleted
File Deleted View Diff
1> ## Documentation Index
2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.
4
5# Recomienda tu plugin desde tu CLI
6
7> Emite un marcador de una línea desde tu CLI para que Claude Code solicite a los usuarios instalar tu plugin oficial.
8
9Si 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.
10
11El protocolo no requiere comandos adicionales y no cambia lo que tu CLI imprime para usuarios fuera de Claude Code.
12
13Esta página es para mantenedores de CLI y SDK. Si buscas instalar plugins, consulta [Descubre e instala plugins](/docs/es/discover-plugins).
14
15<h2 id="how-it-works">
16 Cómo funciona
17</h2>
18
19Claude Code establece la variable de entorno [`CLAUDECODE`](/docs/es/env-vars) en `1` para cada comando que ejecuta a través de las herramientas Bash y PowerShell, y para comandos de [hook](/docs/es/hooks). A partir de v2.1.172 también establece [`CLAUDE_CODE_CHILD_SESSION`](/docs/es/env-vars) en `1` en esos mismos subprocesos. Cuando tu CLI ve una de estas variables, 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.
20
21Cuando Claude Code recibe la salida del comando, hace lo siguiente:
22
231. Busca líneas de sugerencia y las elimina antes de que la salida llegue al modelo
242. Verifica que la sugerencia apunte a un plugin en un marketplace oficial de Anthropic
253. Verifica que el plugin no esté ya instalado y no haya sido sugerido antes
264. Muestra al usuario un mensaje de instalación que nombra el comando que emitió la sugerencia
27
28Claude Code nunca instala un plugin automáticamente. El usuario siempre confirma.
29
30<h2 id="emit-the-hint">
31 Emite la sugerencia
32</h2>
33
34Las sugerencias solo se activan para plugins listados en el marketplace oficial de Anthropic. Consulta [Obtén tu plugin en el marketplace oficial](#get-your-plugin-into-the-official-marketplace) antes de enviar la integración.
35
36Condiciona la emisión en una variable de entorno para que el marcador sea poco probable que aparezca cuando un usuario humano ejecute tu CLI directamente, luego escribe la etiqueta en stderr en su propia línea. Elige qué variable verificar:
37
38* `CLAUDECODE`: se establece en cada versión de Claude Code, por lo que llega a la mayoría de sesiones. También se establece en sesiones de tmux y subprocesos del servidor MCP de stdio que Claude Code inicia, y las extensiones de IDE la establecen en sus terminales integradas, donde un usuario humano puede estar ejecutando tu CLI directamente.
39* `CLAUDE_CODE_CHILD_SESSION`: se establece solo en subprocesos que el propio Claude Code genera, como llamadas de herramientas, comandos de hook y comandos de [línea de estado](/docs/es/statusline), por lo que la etiqueta normalmente no llega a una terminal humana. Un proceso de larga duración que se inició dentro de una sesión, como un servidor tmux, captura la variable, por lo que los shells lanzados posteriormente desde ese proceso aún muestran la etiqueta sin procesar.
40
41Los siguientes ejemplos condicionan `CLAUDECODE` para máximo alcance y emiten una sugerencia para un plugin llamado `example-cli` en el marketplace oficial:
42
43<CodeGroup>
44 ```javascript Node.js theme={null}
45 if (process.env.CLAUDECODE) {
46 process.stderr.write(
47 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />\n',
48 )
49 }
50 ```
51
52 ```python Python theme={null}
53 import os, sys
54
55 if os.environ.get("CLAUDECODE"):
56 print(
57 '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />',
58 file=sys.stderr,
59 )
60 ```
61
62 ```go Go theme={null}
63 if os.Getenv("CLAUDECODE") != "" {
64 fmt.Fprintln(os.Stderr,
65 `<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />`)
66 }
67 ```
68
69 ```shell Shell theme={null}
70 if [ -n "$CLAUDECODE" ]; then
71 printf '%s\n' '<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />' >&2
72 fi
73 ```
74</CodeGroup>
75
76Reemplaza `example-cli` con el nombre de tu plugin en el marketplace oficial.
77
78<h2 id="choose-where-to-emit">
79 Elige dónde emitir
80</h2>
81
82Controlas 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:
83
84| Ubicación | Por qué funciona |
85| :----------------------------------------- | :--------------------------------------------------------------- |
86| Salida de `--help` | Claude a menudo ejecuta help al explorar una CLI desconocida |
87| Errores de subcomando desconocido | Llega al momento en que Claude está confundido sobre tu interfaz |
88| Éxito de inicio de sesión o autenticación | El usuario ya está en una mentalidad de configuración |
89| Mensaje de bienvenida de primera ejecución | Un momento natural de incorporación |
90
91<h2 id="what-the-user-sees">
92 Lo que ve el usuario
93</h2>
94
95Cuando la sugerencia pasa todas las verificaciones, Claude Code muestra un mensaje como el siguiente:
96
97```text theme={null}
98─────────────────────────────────────────────────────────────
99 Recomendación de Plugin
100
101 El comando example-cli sugiere instalar un plugin.
102
103 Plugin: example-cli
104 Marketplace: claude-plugins-official
105 Integración oficial para implementaciones de example-cli
106
107 ¿Te gustaría instalarlo?
108 ❯ 1. Sí, instalar example-cli
109 2. No
110 3. No, y no mostrar sugerencias de instalación de plugins nuevamente
111
112─────────────────────────────────────────────────────────────
113```
114
115El 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, Claude Code descarta el mensaje como **No**.
116
117La frecuencia del mensaje está limitada, y algunas sesiones nunca muestran el mensaje:
118
119* **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.
120* **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.
121* **Solo en la sesión interactiva principal**: Claude Code muestra el mensaje solo en la sesión de terminal en la que el usuario está escribiendo. Claude Code nunca solicita un comando que ejecuta un [subagente](/docs/es/sub-agents), y nunca solicita cuando el usuario ejecuta Claude Code en [modo no interactivo](/docs/es/headless) con la bandera `-p` o a través del [Agent SDK](/docs/es/agent-sdk/overview). Claude Code aún elimina la línea de sugerencia de la salida del comando en todos estos casos.
122* **Exclusiones de telemetría**: las sesiones donde el análisis está deshabilitado nunca muestran mensajes de sugerencia. Esto incluye sesiones con `DISABLE_TELEMETRY` o `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` establecidas, y sesiones en proveedores de terceros como Amazon Bedrock o Google Cloud's Agent Platform donde se aplica la [exclusión automática de telemetría](/docs/es/data-usage#default-behaviors-by-api-provider).
123
124Seleccionar **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.
125
126<h2 id="hint-format">
127 Formato de sugerencia
128</h2>
129
130La sugerencia es una etiqueta que se cierra automáticamente con tres atributos requeridos.
131
132```text theme={null}
133<claude-code-hint v="1" type="plugin" value="example-cli@claude-plugins-official" />
134```
135
136| Atributo | Requerido | Descripción |
137| :------- | :-------- | :------------------------------------------------------- |
138| `v` | Sí | Versión del protocolo. `1` es el único valor soportado |
139| `type` | Sí | Tipo de sugerencia. `plugin` es el único valor soportado |
140| `value` | Sí | Identificador del plugin en forma `name@marketplace` |
141
142Los 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.
143
144<h2 id="requirements">
145 Requisitos
146</h2>
147
148Claude Code aplica dos condiciones antes de actuar sobre una sugerencia. Las sugerencias que fallan en cualquiera de las verificaciones se descartan:
149
150* **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.
151* **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.
152
153La 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.
154
155La orientación restante se recomienda pero no se aplica. Claude Code no puede observar si tu CLI la sigue:
156
157* **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.
158* **Condiciona en una variable de entorno**: solo emite cuando `CLAUDECODE` o `CLAUDE_CODE_CHILD_SESSION` está establecida. Consulta [Emitir la sugerencia](#emit-the-hint) para saber cómo difieren las dos variables.
159
160<h2 id="get-your-plugin-into-the-official-marketplace">
161 Obtén tu plugin en el marketplace oficial
162</h2>
163
164El 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](/docs/es/plugins#submit-your-plugin-to-the-community-marketplace) 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.
165
166<h2 id="see-also">
167 Ver también
168</h2>
169
170* [Crea plugins](/docs/es/plugins): construye el plugin que tu CLI recomienda
171* [Crea y distribuye un marketplace de plugins](/docs/es/plugin-marketplaces): aloja plugins fuera del marketplace oficial
172* [Variables de entorno](/docs/es/env-vars): referencia completa para `CLAUDECODE` y variables relacionadas