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# Referencia de plugins
6
7> Referencia técnica completa para el sistema de plugins de Claude Code, incluyendo esquemas, comandos CLI y especificaciones de componentes.
8
9<Tip>
10 ¿Buscando instalar plugins? Consulte [Descubrir e instalar plugins](/docs/es/discover-plugins). Para crear plugins, consulte [Plugins](/docs/es/plugins). Para distribuir plugins, consulte [Mercados de plugins](/docs/es/plugin-marketplaces).
11</Tip>
12
13Un **plugin** es un directorio independiente de componentes que extiende Claude Code con funcionalidad personalizada. Los componentes de plugins incluyen skills, agentes, hooks, servidores MCP, servidores LSP y monitores.
14
15<h2 id="plugin-components-reference">
16 Referencia de componentes de plugins
17</h2>
18
19<h3 id="skills">
20 Skills
21</h3>
22
23Los plugins añaden skills a Claude Code, creando atajos `/name` que usted o Claude pueden invocar.
24
25**Ubicación**: directorio `skills/` o `commands/` en la raíz del plugin, o un único archivo `SKILL.md` en la raíz del plugin
26
27**Formato de archivo**: Los skills son directorios con `SKILL.md`; los commands son archivos markdown simples
28
29**Estructura de skill**:
30
31```text theme={null}
32skills/
33├── pdf-processor/
34│ ├── SKILL.md
35│ ├── reference.md (opcional)
36│ └── scripts/ (opcional)
37└── code-reviewer/
38 └── SKILL.md
39```
40
41Los skills y commands se descubren automáticamente cuando se instala el plugin.
42
43Si un plugin no tiene directorio `skills/` y no tiene campo manifest `skills`, un `SKILL.md` en la raíz del plugin se carga como un único skill. Establezca el campo frontmatter `name` para controlar el nombre de invocación del skill. Sin él, Claude Code recurre al nombre del directorio de instalación. Para un plugin [copiado en la caché](#plugin-caching-and-file-resolution), ese nombre es una cadena de versión que cambia en cada actualización. Para plugins que incluyen más de un skill, use el diseño de directorio `skills/` mostrado arriba.
44
45En skills y commands de plugins, los campos frontmatter booleanos como `disable-model-invocation` aceptan `yes`, `no`, `on`, `off`, `1`, y `0` en cualquier caso de letra, además de `true` y `false`. Antes de v2.1.218, Claude Code reconocía solo `true` y `false`.
46
47Para detalles completos, consulte [Skills](/docs/es/skills).
48
49<h3 id="agents">
50 Agents
51</h3>
52
53Los plugins pueden proporcionar subagentes especializados para tareas específicas que Claude puede invocar automáticamente cuando sea apropiado.
54
55**Ubicación**: directorio `agents/` en la raíz del plugin
56
57**Formato de archivo**: Archivos markdown que describen las capacidades del agente
58
59**Estructura de agente**:
60
61```markdown theme={null}
62name: agent-name
63description: En qué se especializa este agente y cuándo Claude debe invocarlo
64model: sonnet
65effort: medium
66maxTurns: 20
67disallowedTools: Write, Edit
68
69Prompt del sistema detallado para el agente describiendo su rol, experiencia y comportamiento.
70```
71
72<h4 id="plugin-agent-frontmatter">
73 Frontmatter de agente de plugin
74</h4>
75
76Un archivo de agente de plugin utiliza los mismos [campos frontmatter que un archivo de subagente](/docs/es/sub-agents#supported-frontmatter-fields), excepto que Claude Code solo honra algunos de ellos cuando el agente proviene de un plugin:
77
78* **Soportados**: `name`, `description`, `model`, `effort`, `maxTurns`, `tools`, `disallowedTools`, `skills`, `memory`, `background`, `omitClaudeMd`, `isolation`, `color`, y `experimental`. El único valor válido de `isolation` es `"worktree"`.
79* **No soportados, por razones de seguridad**: `hooks`, `mcpServers`, y `permissionMode`. Claude Code ignora estos cuando carga un agente desde un plugin. Para usarlos, copie el archivo del agente en `.claude/agents/` o `~/.claude/agents/`.
80* **No soportados**: `initialPrompt`.
81
82Puede poner archivos de agente de plugin en subcarpetas de `agents/`. Claude Code [los carga recursivamente](/docs/es/sub-agents#choose-the-subagent-scope) y une el nombre del plugin, cada nombre de subcarpeta, y el nombre del archivo con dos puntos para formar el nombre con alcance del agente. Por ejemplo, `agents/review/security.md` en un plugin llamado `my-plugin` se carga como `my-plugin:review:security`. Dos configuraciones cambian ese nombre:
83
84* Frontmatter `name`: reemplaza solo el nombre del archivo, así que `name: audit` en `agents/review/security.md` se carga como `my-plugin:review:audit`
85* Campo manifest [`agents`](#component-path-fields): un archivo que lista allí se carga sin nombres de subcarpeta, así que `"agents": "./custom/review/security.md"` se carga como `my-plugin:security`
86
87Claude Code carga un agente de plugin incluso cuando su frontmatter no tiene `name` o no se analiza:
88
89* Sin `name`: Claude Code nombra el agente según el archivo, así que `agents/reviewer.md` en un plugin llamado `my-plugin` se carga como `my-plugin:reviewer`
90* Frontmatter que no se analiza: Claude Code nombra el agente según el archivo, usa `Agent from my-plugin plugin` como su descripción, e ignora cada campo en el archivo
91
92En contraste, Claude Code omite un archivo de agente de proyecto, usuario o administrado cuyo frontmatter no tiene `name` o no se analiza.
93
94Para encontrar archivos en el directorio `agents/` predeterminado de un plugin cuyo frontmatter no se analiza, ejecute `claude plugin validate`. La ruta que pase depende de si el plugin tiene un manifest, y ambos ejemplos usan `./my-plugin` como directorio del plugin:
95
96* Un plugin con manifest: `claude plugin validate ./my-plugin`
97* Un plugin sin manifest: `claude plugin validate ./my-plugin/agents`. Requiere Claude Code v2.1.233 o posterior.
98
99Los agentes aparecen en la [typeahead de @-mention](/docs/es/sub-agents#invoke-subagents-explicitly) bajo su nombre con alcance, como `my-plugin:code-reviewer`, una vez que el plugin está habilitado.
100
101Para detalles completos, consulte [Subagentes](/docs/es/sub-agents).
102
103<h3 id="hooks">
104 Hooks
105</h3>
106
107Los plugins pueden proporcionar manejadores de eventos que responden automáticamente a eventos de Claude Code.
108
109**Ubicación**: `hooks/hooks.json` en la raíz del plugin, o en línea en plugin.json
110
111**Formato**: Configuración JSON con coincidencias de eventos y acciones
112
113`hooks/hooks.json` puede llevar una clave `$schema` de nivel superior que nombre una URL de JSON Schema para autocompletado y validación del editor. Claude Code ignora la clave al cargar.
114
115**Configuración de hook**:
116
117```json theme={null}
118{
119 "hooks": {
120 "PostToolUse": [
121 {
122 "matcher": "Write|Edit",
123 "hooks": [
124 {
125 "type": "command",
126 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
127 }
128 ]
129 }
130 ]
131 }
132}
133```
134
135Los hooks de plugins responden a los mismos eventos del ciclo de vida que los [hooks definidos por el usuario](/docs/es/hooks):
136
137| Evento | Cuándo se dispara |
138| :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
139| `SessionStart` | Cuando una sesión comienza o se reanuda |
140| `Setup` | Cuando inicia Claude Code con `--init-only`, o con `--init` o `--maintenance` en modo `-p`. Para preparación única en CI o scripts |
141| `UserPromptSubmit` | Cuando envía un prompt, antes de que Claude lo procese |
142| `UserPromptExpansion` | Cuando un comando escrito por el usuario se expande en un prompt, antes de que llegue a Claude. Puede bloquear la expansión |
143| `PreToolUse` | Antes de que se ejecute una llamada a herramienta. Puede bloquearlo |
144| `PermissionRequest` | Cuando una llamada a herramienta necesita una decisión de permiso |
145| `PermissionDenied` | Cuando el modo automático deniega una llamada a herramienta, incluidas las denegaciones sin un veredicto del clasificador. Use JSON `hookSpecificOutput.retry: true` para indicar al modelo que puede reintentar la llamada a herramienta denegada. Claude Code ignora `retry` cuando el clasificador no produjo veredicto |
146| `PostToolUse` | Después de que una llamada a herramienta se ejecuta correctamente |
147| `PostToolUseFailure` | Después de que una llamada a herramienta falla |
148| `PostToolBatch` | Después de que se resuelve un lote completo de llamadas a herramientas paralelas, antes de la siguiente llamada al modelo |
149| `Notification` | Cuando Claude Code envía una notificación |
150| `MessageDisplay` | Mientras se muestra el texto del mensaje del asistente |
151| `SubagentStart` | Cuando se genera un subagente |
152| `SubagentStop` | Cuando un subagente finaliza |
153| `TaskCreated` | Cuando se está creando una tarea a través de `TaskCreate` |
154| `TaskCompleted` | Cuando se marca una tarea como completada |
155| `Stop` | Cuando Claude termina de responder |
156| `StopFailure` | Cuando el turno termina debido a un error de API |
157| `TeammateIdle` | Cuando un compañero de [equipo de agentes](/docs/es/agent-teams) está a punto de quedarse inactivo |
158| `InstructionsLoaded` | Cuando se carga un archivo CLAUDE.md o `.claude/rules/*.md` en el contexto. Se dispara al inicio de la sesión y cuando los archivos se cargan de forma diferida durante una sesión |
159| `ConfigChange` | Cuando un archivo de configuración cambia durante una sesión |
160| `CwdChanged` | Cuando el directorio de trabajo cambia, por ejemplo cuando Claude ejecuta un comando `cd`. Útil para la gestión reactiva del entorno con herramientas como direnv |
161| `DirectoryAdded` | Cuando se agrega un directorio de trabajo a mitad de sesión a través de `/add-dir` o la solicitud de control `register_repo_root` del SDK |
162| `FileChanged` | Cuando un archivo observado cambia en el disco. El campo `matcher` especifica qué nombres de archivo observar |
163| `WorktreeCreate` | Cuando se está creando un worktree a través de `--worktree`, `isolation: "worktree"`, o para una sesión en segundo plano. Reemplaza el comportamiento predeterminado de git |
164| `WorktreeRemove` | Cuando se está eliminando un worktree al salir de la sesión, cuando un subagente finaliza, o cuando elimina una sesión en segundo plano |
165| `PreCompact` | Antes de la compactación de contexto |
166| `PostCompact` | Después de que se completa la compactación de contexto |
167| `PreModelSwitch` | Antes de que Claude Code aplique un cambio de modelo que usted o un cliente solicitó. Puede bloquear el cambio |
168| `PostModelSwitch` | Después de que cambia el modelo de la sesión, incluidos los cambios que Claude Code realiza por su cuenta, como restaurar el modelo cuando reanuda una sesión |
169| `Elicitation` | Cuando un servidor MCP solicita entrada del usuario durante una llamada a herramienta |
170| `ElicitationResult` | Después de que un usuario responde a una solicitud de MCP, antes de que la respuesta se envíe de vuelta al servidor |
171| `SessionEnd` | Cuando una sesión termina |
172
173**Tipos de hook**:
174
175* `command`: ejecutar comandos shell o scripts
176* `http`: enviar el JSON del evento como una solicitud POST a una URL
177* `mcp_tool`: llamar a una herramienta en un [servidor MCP](/docs/es/mcp) configurado
178* `prompt`: evaluar un prompt con un LLM (usa el marcador de posición `$ARGUMENTS` para contexto)
179* `agent`: ejecutar un verificador agente con herramientas para tareas de verificación complejas
180
181Los hooks que apuntan al [servidor MCP agrupado](#mcp-servers) propio del plugin deben usar sus nombres con alcance. Los coincidentes de herramientas y campos `if` toman el nombre de herramienta con alcance `mcp__plugin_<plugin-name>_<server-name>__<tool>`, y el campo `server` de un hook `mcp_tool` toma `plugin:<plugin-name>:<server-name>`. Un coincidente escrito contra la clave del servidor desnuda nunca se dispara. Consulte [Match MCP tools](/docs/es/hooks#match-mcp-tools) y [Plugin-provided MCP servers](/docs/es/mcp#plugin-provided-mcp-servers).
182
183<h3 id="mcp-servers">
184 MCP servers
185</h3>
186
187Los plugins pueden agrupar servidores del Protocolo de Contexto de Modelo (MCP) para conectar Claude Code con herramientas y servicios externos.
188
189**Ubicación**: `.mcp.json` en la raíz del plugin, o en línea en plugin.json
190
191**Formato**: Configuración estándar de servidor MCP
192
193**Configuración de servidor MCP**:
194
195```json theme={null}
196{
197 "mcpServers": {
198 "plugin-database": {
199 "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
200 "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
201 "env": {
202 "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data"
203 }
204 },
205 "plugin-api-client": {
206 "command": "npx",
207 "args": ["@company/mcp-server", "--plugin-mode"]
208 }
209 }
210}
211```
212
213**Comportamiento de integración**:
214
215* Los servidores MCP de plugins se inician automáticamente cuando el plugin está habilitado
216* Los servidores aparecen como herramientas MCP estándar en el kit de herramientas de Claude
217* Los servidores de plugins se pueden configurar independientemente de los servidores MCP del usuario
218* Si ejecuta [`/reload-plugins`](/docs/es/discover-plugins#apply-plugin-changes-without-restarting) a mitad de sesión, Claude Code mantiene las conexiones activas de servidores cuya configuración no ha cambiado
219
220<h3 id="lsp-servers">
221 LSP servers
222</h3>
223
224<Tip>
225 ¿Buscando usar plugins LSP? Instálelos desde el marketplace oficial: busque "lsp" en la pestaña Discover de `/plugin`. Esta sección documenta cómo crear plugins LSP para lenguajes no cubiertos por el marketplace oficial.
226</Tip>
227
228Los plugins pueden proporcionar servidores del [Protocolo de Servidor de Lenguaje](https://microsoft.github.io/language-server-protocol/) (LSP) para dar a Claude [inteligencia de código en tiempo real](/docs/es/discover-plugins#code-intelligence) mientras trabaja en su base de código.
229
230**Ubicación**: `.lsp.json` en la raíz del plugin, o en línea en `plugin.json`
231
232**Formato**: Configuración JSON que asigna nombres de servidores de lenguaje a sus configuraciones
233
234**Formato de archivo `.lsp.json`**:
235
236```json theme={null}
237{
238 "go": {
239 "command": "gopls",
240 "args": ["serve"],
241 "extensionToLanguage": {
242 ".go": "go"
243 }
244 }
245}
246```
247
248**En línea en `plugin.json`**:
249
250```json theme={null}
251{
252 "name": "my-plugin",
253 "lspServers": {
254 "go": {
255 "command": "gopls",
256 "args": ["serve"],
257 "extensionToLanguage": {
258 ".go": "go"
259 }
260 }
261 }
262}
263```
264
265**Campos requeridos:**
266
267| Campo | Descripción |
268| :-------------------- | :---------------------------------------------------------- |
269| `command` | El binario LSP a ejecutar (debe estar en PATH) |
270| `extensionToLanguage` | Asigna extensiones de archivo a identificadores de lenguaje |
271
272**Campos opcionales:**
273
274| Campo | Descripción |
275| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
276| `args` | Argumentos de línea de comandos para el servidor LSP |
277| `transport` | Transporte de comunicación: `stdio` (predeterminado) o `socket`. Claude Code acepta `socket` pero ejecuta cada servidor sobre stdio, por lo que las reglas del protocolo stdout se aplican a todos los servidores |
278| `env` | Variables de entorno a establecer al iniciar el servidor |
279| `initializationOptions` | Opciones pasadas al servidor durante la inicialización |
280| `settings` | Configuración pasada vía `workspace/didChangeConfiguration` |
281| `workspaceFolder` | Ruta de carpeta de espacio de trabajo para el servidor |
282| `startupTimeout` | Tiempo máximo para esperar el inicio del servidor (milisegundos) |
283| `shutdownTimeout` | Tiempo máximo para esperar el apagado elegante (milisegundos). Cuando se agota el tiempo de espera, Claude Code termina el proceso del servidor. Cuando no se establece, no se aplica tiempo de espera |
284| `restartOnCrash` | Si reiniciar el servidor después de que falle. Por defecto es `true`. Establezca en `false` para dejar un servidor fallido detenido en lugar de reiniciarlo |
285| `maxRestarts` | Número máximo de intentos de reinicio antes de rendirse |
286| `diagnostics` | Si insertar diagnósticos en el contexto de Claude después de ediciones (por defecto `true`). Establezca en `false` para mantener la navegación de código pero suprimir la inyección automática de diagnósticos. |
287
288`restartOnCrash` y `shutdownTimeout` requieren Claude Code v2.1.205 o posterior. Antes de v2.1.205, el esquema de configuración aceptaba ambas opciones pero establecer cualquiera de ellas causaba que Claude Code omitiera ese servidor LSP completamente al inicio, con la razón visible solo en la salida de `claude --debug`.
289
290**Múltiples servidores para la misma extensión**: cuando más de un servidor LSP habilitado declara la misma extensión de archivo en `extensionToLanguage`, ya sea que los servidores provengan de un plugin o de diferentes plugins, el primer servidor registrado maneja archivos con esa extensión y los otros nunca se inician. La interfaz `/plugin` muestra una advertencia nombrando el plugin cuyo servidor está activo.
291
292**Servidores que fallan al inicializarse**: Claude Code omite un servidor cuya configuración es inválida, por ejemplo uno que falta `command` o `extensionToLanguage`, y los otros servidores configurados aún se inician. Ejecute `claude --debug` para ver por qué se omitió un servidor.
293
294Un servidor omitido no reclama sus extensiones de archivo, por lo que otro servidor válido que declare la misma extensión, del mismo plugin o de un plugin diferente, aún maneja esos archivos.
295
296**Envíe la salida de registro a stderr, no a stdout**: Claude Code lee el stdout de un servidor solo como mensajes de protocolo, y acepta encabezados de mensaje de hasta 64 KiB y un cuerpo de mensaje de hasta 32 MiB. Claude Code desconecta un servidor que excede cualquiera de los límites o escribe salida que no es de protocolo a stdout, y cuenta la desconexión como un fallo para `restartOnCrash` y `maxRestarts`. Cuando ejecuta con `--debug`, Claude Code escribe un error nombrando la causa en el registro de depuración.
297
298<Warning>
299 **Debe instalar el binario del servidor de lenguaje por separado.** Los plugins LSP configuran cómo Claude Code se conecta a un servidor de lenguaje, pero no incluyen el servidor en sí. Si ve `Executable not found in $PATH` en la pestaña Errores de `/plugin`, instale el binario requerido para su lenguaje.
300</Warning>
301
302**Plugins LSP disponibles:**
303
304| Plugin | Servidor de lenguaje | Comando de instalación |
305| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------- |
306| `pyright-lsp` | Pyright (Python) | `pip install pyright` o `npm install -g pyright` |
307| `typescript-lsp` | TypeScript Language Server | `npm install -g typescript-language-server typescript` |
308| `rust-analyzer-lsp` | rust-analyzer | [Ver instalación de rust-analyzer](https://rust-analyzer.github.io/manual.html#installation) |
309
310Instale el servidor de lenguaje primero, luego instale el plugin desde el marketplace.
311
312<h3 id="monitors">
313 Monitors
314</h3>
315
316Los plugins pueden declarar monitores de fondo que Claude Code inicia automáticamente cuando el plugin está activo. Cada monitor ejecuta un comando shell durante la vida útil de la sesión y entrega cada línea de stdout a Claude como una notificación, para que Claude pueda reaccionar a entradas de registro, cambios de estado, o eventos sondeados sin que se le pida que inicie la observación por sí mismo.
317
318Los monitores de plugins usan el mismo mecanismo que la [herramienta Monitor](/docs/es/tools-reference#monitor-tool) y comparten sus restricciones de disponibilidad. Se ejecutan solo en sesiones CLI interactivas, se ejecutan sin sandbox al mismo nivel de confianza que los [hooks](#hooks), y se omiten en hosts donde la herramienta Monitor no está disponible.
319
320**Ubicación**: `monitors/monitors.json` en la raíz del plugin, o en línea en `plugin.json`
321
322**Formato**: Matriz JSON de entradas de monitor
323
324El siguiente `monitors/monitors.json` observa un punto final de estado de implementación y un registro de errores local:
325
326```json theme={null}
327[
328 {
329 "name": "deploy-status",
330 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/poll-deploy.sh",
331 "description": "Cambios de estado de implementación"
332 },
333 {
334 "name": "error-log",
335 "command": "tail -F ./logs/error.log",
336 "description": "Registro de errores de aplicación",
337 "when": "on-skill-invoke:debug"
338 }
339]
340```
341
342Para declarar monitores en línea, establezca `experimental.monitors` en `plugin.json` en la misma matriz. Para cargar desde una ruta no predeterminada, establezca `experimental.monitors` en una cadena de ruta relativa como `"./config/monitors.json"`. Los monitores son un [componente experimental](#experimental-components).
343
344**Campos requeridos:**
345
346| Campo | Descripción |
347| :------------ | :------------------------------------------------------------------------------------------------------------------------------- |
348| `name` | Identificador único dentro del plugin. Previene procesos duplicados cuando el plugin se recarga o se invoca una skill nuevamente |
349| `command` | Comando shell ejecutado como un proceso de fondo persistente en el directorio de trabajo de la sesión |
350| `description` | Resumen breve de lo que se está observando. Se muestra en el panel de tareas y en resúmenes de notificaciones |
351
352**Campos opcionales:**
353
354| Campo | Descripción |
355| :----- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
356| `when` | Controla cuándo se inicia el monitor. `"always"` lo inicia al inicio de la sesión y en la recarga del plugin, y es el predeterminado. `"on-skill-invoke:<skill-name>"` lo inicia la primera vez que se envía la skill nombrada en este plugin |
357
358El valor `command` soporta las [sustituciones de ruta](#environment-variables) `${CLAUDE_PLUGIN_ROOT}`, `${CLAUDE_PLUGIN_DATA}`, y `${CLAUDE_PROJECT_DIR}`, más cualquier `${ENV_VAR}` del entorno. Prefije el comando con `cd "${CLAUDE_PLUGIN_ROOT}" && ` si el script necesita ejecutarse desde el directorio propio del plugin.
359
360Un `command` de monitor no puede referenciar valores [`${user_config.*}`](#user-configuration). El comando se ejecuta a través de un shell, por lo que Claude Code rechaza el monitor con un [error](/docs/es/errors#plugin-command-references-user-config) en lugar de sustituir el valor. Los procesos de monitor no reciben variables de entorno `CLAUDE_PLUGIN_OPTION_<KEY>`, así que haga que el script de monitor lea el valor de un archivo de configuración que posee.
361
362Si deshabilita un plugin a mitad de sesión, Claude Code no detiene los monitores que ya se están ejecutando; se detienen cuando termina la sesión.
363
364<h3 id="themes">
365 Themes
366</h3>
367
368Los plugins pueden enviar temas de color que aparecen en `/theme` junto a los presets integrados y los temas locales del usuario. Un tema es un archivo JSON en `themes/` con un preset `base` y un mapa disperso `overrides` de tokens de color. Los temas son un [componente experimental](#experimental-components).
369
370```json theme={null}
371{
372 "name": "Dracula",
373 "base": "dark",
374 "overrides": {
375 "claude": "#bd93f9",
376 "error": "#ff5555",
377 "success": "#50fa7b"
378 }
379}
380```
381
382Cuando un usuario selecciona un tema de plugin, Claude Code guarda `custom:<plugin-name>:<slug>` en su configuración. Los temas de plugins son de solo lectura: cuando un usuario presiona `Ctrl+E` en uno en `/theme`, Claude Code lo copia en `~/.claude/themes/` para que puedan editar la copia.
383
384***
385
386<h2 id="plugin-installation-scopes">
387 Alcances de instalación de plugins
388</h2>
389
390Cuando instala un plugin, elige un **alcance** que determina dónde está disponible el plugin y quién más puede usarlo:
391
392| Alcance | Archivo de configuración | Caso de uso |
393| :-------- | :--------------------------------------- | :---------------------------------------------------------------------------------------------------- |
394| `user` | `~/.claude/settings.json` | Plugins personales disponibles en todos los proyectos (predeterminado) |
395| `project` | `.claude/settings.json` | Plugins de equipo compartidos a través del control de versiones |
396| `local` | `.claude/settings.local.json` | Plugins específicos del proyecto, ignorados por git cuando Claude Code guarda una configuración en él |
397| `managed` | [Managed settings](/docs/es/managed-settings) | Plugins administrados (solo lectura, solo actualizar) |
398
399Los plugins utilizan el mismo sistema de alcances que otras configuraciones de Claude Code. Para instrucciones de instalación y banderas de alcance, consulte [Install plugins](/docs/es/discover-plugins#install-plugins). Para una explicación completa de los alcances, consulte [Configuration scopes](/docs/es/settings#where-settings-live).
400
401***
402
403<h2 id="skills-directory-plugins">
404 Plugins de directorio de skills
405</h2>
406
407Cualquier carpeta bajo un directorio de skills que contenga un manifiesto `.claude-plugin/plugin.json` se carga como un plugin llamado `<name>@skills-dir` en la siguiente sesión, sin marketplace ni paso de instalación. Cree uno con [`plugin init`](#plugin-init). A diferencia de una instalación de marketplace copiada, el plugin se descubre en su lugar en lugar de copiarse en la caché de plugins.
408
409Un árbol de directorio de skills admite tres cosas distintas:
410
411| Lo que tiene | Qué es |
412| :-------------------------------------------- | :------------------------------------------------------------------------------------- |
413| `<skills-dir>/foo/SKILL.md` sin manifiesto | Un [skill](/docs/es/skills) simple llamado `foo` |
414| `<skills-dir>/foo/.claude-plugin/plugin.json` | Un plugin `foo@skills-dir`, que puede agrupar sus propios skills, agentes, hooks y más |
415| `<plugin>/skills/bar/SKILL.md` | Un skill `bar` empaquetado dentro de un plugin |
416
417<h3 id="choose-where-the-plugin-loads-from">
418 Elija de dónde se carga el plugin
419</h3>
420
421| Directorio de skills | Alcance | Se carga |
422| :---------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------ |
423| `~/.claude/skills/` | personal | En cada proyecto, ya que la ubicación es solo suya |
424| `<cwd>/.claude/skills/` | proyecto | Solo después de que acepte el [diálogo de confianza](/docs/es/permissions#what-runs-before-you-trust-a-folder) del espacio de trabajo para esa carpeta |
425
426Un plugin de alcance de proyecto se verifica en el repositorio y llega a cada colaborador que lo clona. Debido a que ese contenido proviene del repositorio en lugar de provenir de usted, se carga solo después de la misma puerta de confianza que rige las reglas de permiso de proyecto en `.claude/settings.json`, por lo que confiar en una carpeta principal o ejecutar con `-p` no es suficiente, y los componentes que ejecutan código están restringidos aún más:
427
428* Los servidores MCP que declara pasan por la [misma aprobación por servidor](/docs/es/mcp) que un `.mcp.json` de proyecto
429* Los servidores LSP se inician solo después de que confía en el espacio de trabajo
430* [Los monitores de fondo](#monitors) no se cargan
431
432Los plugins de alcance personal no tienen ninguna de estas restricciones.
433
434<Warning>
435 Los plugins `@skills-dir` de alcance de proyecto se cargan solo desde `.claude/skills/` del [directorio de trabajo principal](/docs/es/permissions#working-directories) de la sesión. No [suben hasta la raíz del repositorio](/docs/es/skills#discovery-from-parent-and-nested-directories) de la manera que lo hacen los skills y comandos simples, por lo que lanzar desde un subdirectorio pierde un plugin que vive en la raíz del repositorio. Inicie desde la raíz del repositorio, o [mueva la sesión allí con `/cd`](/docs/es/permissions#move-the-session-to-another-directory) en v2.1.246 o posterior.
436</Warning>
437
438<h3 id="edit-reload-and-disable-a-skills-directory-plugin">
439 Edite, recargue y deshabilite un plugin de directorio de skills
440</h3>
441
442Los cambios que realiza en el `SKILL.md` de un skill surten efecto inmediatamente en la sesión actual. Los cambios en otros componentes del plugin, como `hooks/`, `.mcp.json`, `agents/` y `output-styles/`, no lo hacen. Ejecute `/reload-plugins` o reinicie Claude Code para aplicarlos. Consulte [Detección de cambios en vivo](/docs/es/skills#live-change-detection).
443
444Para dejar de cargar un plugin de directorio de skills, elimine su carpeta o deshabilítelo por nombre. No hay un paso `uninstall` porque nada se instaló desde un marketplace.
445
446```bash theme={null}
447claude plugin disable my-tool@skills-dir
448```
449
450***
451
452<h2 id="synced-plugins">
453 Plugins sincronizados desde claude.ai
454</h2>
455
456Claude Code carga los plugins habilitados para su cuenta de claude.ai, incluidos los plugins que su organización activa para sus miembros, junto con los plugins que instala desde marketplaces. Los descarga en `~/.claude/plugins/synced/` y los carga como `<name>@synced`, sin marketplace ni registro de instalación. Un plugin sincronizado se ejecuta con la misma confianza que un plugin de marketplace que instaló: sus skills, agentes, hooks, servidores MCP y servidores LSP se cargan todos.
457
458Dónde Claude Code sincroniza estos plugins depende de la sesión:
459
460* En [Cowork](https://claude.com/product/cowork) y [sesiones en la nube](/docs/es/cloud-environments#what-carries-over-from-your-setup), Claude Code los descarga en el entorno propio de la sesión cuando la sesión comienza. Antes de v2.1.239, Claude Code cargaba estos plugins como `<name>@inline`, la identidad que usan los plugins de `--plugin-dir`.
461* En sesiones de terminal donde inicia sesión con su cuenta de claude.ai, Claude Code verifica su cuenta una vez cada vez que comienza, luego descarga plugins nuevos y actualizados y elimina los que usted u su organización desactivaron, todo en segundo plano. La sincronización en sesiones de terminal requiere Claude Code v2.1.273 o posterior.
462
463La verificación de inicio se ejecuta en segundo plano, por lo que puede terminar después de que su sesión haya comenzado. Cuando agrega, actualiza o elimina un plugin sincronizado en una sesión interactiva, Claude Code muestra `Plugins changed. Run /reload-plugins to activate.` Ejecute [`/reload-plugins`](/docs/es/discover-plugins#apply-plugin-changes-without-restarting) para cargar el cambio en esa sesión, o déjelo para la próxima vez que inicie Claude Code. Si habilita un plugin en claude.ai mientras una sesión se está ejecutando, Claude Code lo descarga la próxima vez que comienza.
464
465La sincronización de plugins en sesiones de terminal se ejecuta bajo las mismas condiciones de inicio de sesión que [skills sincronizados desde claude.ai](/docs/es/skills#where-synced-skills-load). También necesita un inicio de sesión que otorgue a Claude Code acceso a los plugins de su cuenta.
466
467Un inicio de sesión de una versión anterior de Claude Code obtiene acceso a plugins la próxima vez que Claude Code renueva ese inicio de sesión en segundo plano, dentro de unas pocas horas, o de inmediato si ejecuta `/login` nuevamente. La sincronización de plugins comienza la próxima vez que inicia Claude Code después de eso.
468
469`claude plugin list` muestra plugins sincronizados bajo un encabezado `Synced from claude.ai`, y la pestaña **Installed** de `/plugin` los enumera con `synced` como su fuente. Administre un plugin sincronizado por el ID `<name>@synced` que imprime `claude plugin list`:
470
471* **Desactivar uno**: ejecute `claude plugin disable <name>@synced`, o desactívelo desde la pestaña **Installed** de `/plugin`. Claude Code guarda la opción como `"<name>@synced": false` en su [`enabledPlugins`](/docs/es/settings-reference#enabledplugins) a nivel de usuario. Para volver a activar el plugin, ejecute `claude plugin enable <name>@synced`.
472* **Mantener uno fuera en todas partes**: [desactívelo para su cuenta de claude.ai](/docs/es/desktop#extend-claude-code). Para mantenerlo fuera de un proyecto en todos los entornos, establezca `"<name>@synced": false` bajo `enabledPlugins` en el `.claude/settings.json` comprometido de ese proyecto.
473* **Administre el plugin en claude.ai**: `claude plugin install`, `update` y `uninstall` no se aplican a un plugin sincronizado. Claude Code descarga las actualizaciones del plugin en la próxima sincronización. Para eliminar uno, desactive el plugin para su cuenta de claude.ai, y Claude Code lo elimina en la próxima sincronización.
474* **Deje de sincronizar en una máquina**: establezca [`syncClaudeAiPlugins`](/docs/es/settings-reference#syncclaudeaiplugins) en `false` en su configuración de usuario. Claude Code deja de descargar, y la próxima vez que comienza mueve los plugins que ya sincronizó a `~/.claude/plugins/.trash/` y ya no los carga. Su organización puede establecer la misma clave en [configuración administrada](/docs/es/managed-settings), o desactivar Skills en claude.ai, lo que también detiene la sincronización de plugins.
475
476No puede desactivar un plugin que su organización marca como requerido en claude.ai. Claude Code lo carga incluso si lo desactivó anteriormente, y `claude plugin disable` rechaza con `Plugin "<name>@synced" is required by your organization and can't be disabled here. Contact your admin to change it.` En `claude plugin list`, estos plugins están marcados como `required by your org`.
477
478Cuando un plugin habilitado de cualquier otra fuente coincide con el nombre de un plugin sincronizado, Claude Code carga ese plugin e informa que la copia sincronizada no se cargó. Otras fuentes incluyen instalaciones de marketplace, [plugins del directorio de skills](#skills-directory-plugins), plugins de `--plugin-dir` y plugins integrados en Claude Code. Para usar la copia de claude.ai en su lugar, desactive su propia copia. Antes de v2.1.239, Claude Code cargaba la copia sincronizada en lugar de una instalación de marketplace con el mismo nombre.
479
480***
481
482<h2 id="plugin-manifest-schema">
483 Esquema de manifiesto de plugins
484</h2>
485
486El archivo `.claude-plugin/plugin.json` define los metadatos y la configuración de su plugin.
487
488El manifiesto es opcional. Si se omite, Claude Code detecta automáticamente componentes en [ubicaciones predeterminadas](#file-locations-reference) y deriva el nombre del plugin del nombre del directorio. Use un manifiesto cuando necesite proporcionar metadatos o rutas de componentes personalizadas.
489
490<h3 id="complete-schema">
491 Esquema completo
492</h3>
493
494```json theme={null}
495{
496 "name": "plugin-name",
497 "displayName": "Plugin Name",
498 "version": "1.2.0",
499 "description": "Brief plugin description",
500 "author": {
501 "name": "Author Name",
502 "email": "author@example.com",
503 "url": "https://github.com/author"
504 },
505 "homepage": "https://docs.example.com/plugin",
506 "repository": "https://github.com/author/plugin",
507 "license": "MIT",
508 "keywords": ["keyword1", "keyword2"],
509 "metadata": { "catalogId": "cat-123", "tier": "pro" },
510 "skills": "./custom/skills/",
511 "commands": ["./custom/commands/special.md"],
512 "agents": ["./custom/agents/reviewer.md"],
513 "hooks": "./config/hooks.json",
514 "mcpServers": "./mcp-config.json",
515 "outputStyles": "./styles/",
516 "lspServers": "./.lsp.json",
517 "experimental": {
518 "themes": "./themes/",
519 "monitors": "./monitors.json",
520 "evals": "quality/evals"
521 },
522 "dependencies": [
523 "helper-lib",
524 { "name": "secrets-vault", "version": "~2.1.0" }
525 ]
526}
527```
528
529<h3 id="required-fields">
530 Campos requeridos
531</h3>
532
533Si incluye un manifiesto, `name` es el único campo requerido.
534
535| Campo | Tipo | Descripción | Ejemplo |
536| :----- | :----- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
537| `name` | string | Identificador único en kebab-case, sin espacios, caracteres de control o caracteres de formato bidireccional. Cuando una [entrada de marketplace](/docs/es/plugin-marketplaces#plugin-entries) lista el plugin bajo un nombre diferente, el nombre de la entrada de marketplace es lo que `enabledPlugins` y `/plugin` usan | `"deployment-tools"` |
538
539Este nombre se utiliza para espacios de nombres de componentes. Por ejemplo, en la interfaz de usuario, el agente `agent-creator` para el plugin con nombre `plugin-dev` aparecerá como `plugin-dev:agent-creator`.
540
541<h3 id="unrecognized-fields">
542 Campos no reconocidos
543</h3>
544
545Claude Code ignora los campos de nivel superior que no reconoce. Puede mantener metadatos de otro ecosistema en `plugin.json` y el plugin aún se carga. Esto hace que sea práctico mantener un manifiesto que funcione como manifiesto de extensión de VS Code o Cursor, un `package.json` de npm, o un manifiesto de paquete MCPB/DXT.
546
547`claude plugin validate` reporta campos no reconocidos como advertencias, no como errores. Si un campo está a uno o dos caracteres de uno reconocido, la advertencia sugiere el nombre probable previsto. Un plugin con solo advertencias de campos no reconocidos aún pasa la validación y se carga en tiempo de ejecución.
548
549La forma en que Claude Code maneja un campo reconocido cuyo valor tiene el tipo incorrecto depende del campo:
550
551* **La mayoría de campos**: el plugin no se carga. Por ejemplo, un valor `keywords` que es una cadena en lugar de un array es un error de carga, y `claude plugin validate` lo reporta como tal.
552* **`experimental` y `metadata`**: Claude Code ignora un valor que no es un objeto, y `claude plugin validate` reporta una advertencia.
553
554Pase `--strict` para tratar las advertencias como errores. Úselo en CI para detectar un nombre de campo mal escrito o un campo dejado de otra herramienta de manifiesto antes de publicar, aunque el plugin se cargue en tiempo de ejecución.
555
556```bash theme={null}
557claude plugin validate ./my-plugin --strict
558```
559
560<h3 id="metadata-fields">
561 Campos de metadatos
562</h3>
563
564| Campo | Tipo | Descripción | Ejemplo |
565| :--------------- | :------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- |
566| `$schema` | string | URL de JSON Schema para autocompletado y validación del editor. Claude Code ignora este campo en tiempo de carga. | `"https://json.schemastore.org/claude-code-plugin-manifest.json"` |
567| `displayName` | string | Nombre legible por humanos mostrado en el selector `/plugin` y otras superficies de interfaz de usuario. Para un plugin instalado desde marketplace, un `displayName` en la [entrada de marketplace](/docs/es/plugin-marketplaces#optional-plugin-fields) tiene precedencia sobre este valor. Cuando no se establece un nombre de visualización en ninguno de los dos lugares, los usuarios ven `name`. A diferencia de `name`, puede contener espacios y cualquier mayúscula. No se utiliza para espacios de nombres o búsqueda. | `"Deployment Tools"` |
568| `version` | string | Opcional. Versión semántica. Establecer esto fija el plugin a esa cadena de versión, por lo que los usuarios solo reciben actualizaciones cuando la incrementa, excepto para una [`command` source](/docs/es/plugin-marketplaces#command-sources) o un plugin [cargado en lugar](#plugin-caching-and-file-resolution); vea [Gestión de versiones](#version-management). Si también se establece en la entrada de marketplace, `plugin.json` gana. Si se omite, la versión proviene de la siguiente fuente en [Gestión de versiones](#version-management). | `"2.1.0"` |
569| `description` | string | Breve explicación del propósito del plugin | `"Deployment automation tools"` |
570| `author` | object | Información del autor | `{"name": "Dev Team", "email": "dev@company.com"}` |
571| `homepage` | string | URL de documentación | `"https://docs.example.com"` |
572| `repository` | string | URL del código fuente | `"https://github.com/user/plugin"` |
573| `license` | string | Identificador de licencia | `"MIT"`, `"Apache-2.0"` |
574| `keywords` | array | Etiquetas de descubrimiento | `["deployment", "ci-cd"]` |
575| `metadata` | object | Objeto de forma libre para sus propios datos, como campos de derechos o catálogo. Claude Code no lo lee, por lo que los valores nunca afectan el comportamiento del plugin. Claude Code ignora un valor que no es un objeto, y `claude plugin validate` lo reporta como una advertencia. Antes de v2.1.222, Claude Code trataba la clave como un [campo no reconocido](#unrecognized-fields). | `{"catalogId": "cat-123"}` |
576| `defaultEnabled` | boolean | Si el plugin comienza en un estado habilitado cuando el usuario no ha establecido uno. Por defecto es `true`. Vea [Habilitación predeterminada](#default-enablement). | `false` |
577
578<h3 id="default-enablement">
579 Habilitación predeterminada
580</h3>
581
582Establezca `defaultEnabled: false` en `plugin.json` para enviar un plugin que se instale deshabilitado. El usuario lo activa con `claude plugin enable <plugin>` o la interfaz `/plugin`. Úselo para plugins que agregan costo o alcance en el que un usuario debe optar, como uno que se conecta a un servicio externo.
583
584`defaultEnabled` es la alternativa cuando nada más ha decidido el estado del plugin. La configuración del usuario y un requisito de dependencia tienen precedencia sobre ella:
585
586* **La configuración del usuario**: una entrada para el plugin en `enabledPlugins` en cualquier ámbito de configuración. Una vez escrita, persiste en actualizaciones y reinstalaciones de plugins, por lo que cambiar `defaultEnabled` en una versión posterior no invierte un usuario existente.
587* **Un requisito de dependencia**: cuando un plugin es requerido por otro que está activo, Claude Code escribe `true` para él en tiempo de instalación o habilitación. Eso le da una configuración explícita, por lo que su propio valor predeterminado ya no se aplica. Vea [Habilitar o deshabilitar un plugin con dependencias](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies).
588
589El mismo campo puede aparecer en la entrada de marketplace de un plugin, donde tiene precedencia sobre el valor en `plugin.json`. Vea [Campos de plugin opcionales](/docs/es/plugin-marketplaces#optional-plugin-fields).
590
591<h3 id="component-path-fields">
592 Campos de ruta de componentes
593</h3>
594
595| Campo | Tipo | Descripción | Ejemplo |
596| :---------------------- | :-------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------- |
597| `skills` | string\|array | Directorios de skills personalizados que contienen `<name>/SKILL.md`. Se agrega al escaneo predeterminado `skills/`. Vea [Reglas de comportamiento de ruta](#path-behavior-rules) para la excepción de raíz de marketplace | `"./custom/skills/"` |
598| `commands` | string\|array | Archivos de skills `.md` planos personalizados o directorios (reemplaza el `commands/` predeterminado) | `"./custom/cmd.md"` o `["./cmd1.md"]` |
599| `agents` | string\|array | Archivos de agentes personalizados (reemplaza el `agents/` predeterminado) | `"./custom/agents/reviewer.md"` |
600| `workflows` | string\|array | Archivos de scripts de [workflow](/docs/es/workflows) personalizados o directorios (reemplaza el `workflows/` predeterminado) | `"./custom/workflows/"` |
601| `hooks` | string\|array\|object | Rutas de configuración de hooks o configuración en línea | `"./my-extra-hooks.json"` |
602| `mcpServers` | string\|array\|object | Rutas de configuración de MCP o configuración en línea | `"./my-extra-mcp-config.json"` |
603| `outputStyles` | string\|array | Archivos/directorios de estilo de salida personalizados (reemplaza el `output-styles/` predeterminado) | `"./styles/"` |
604| `lspServers` | string\|array\|object | Configuraciones de [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) para inteligencia de código (ir a definición, encontrar referencias, etc.) | `"./.lsp.json"` |
605| `experimental.themes` | string\|array | Archivos/directorios de tema de color (reemplaza el `themes/` predeterminado). Vea [Temas](#themes) | `"./themes/"` |
606| `experimental.monitors` | string\|array | Configuraciones de [Monitor](/docs/es/tools-reference#monitor-tool) de fondo que se inician automáticamente cuando el plugin está activo. Vea [Monitores](#monitors) | `"./monitors.json"` |
607| `experimental.evals` | string\|array | Directorio debajo de la raíz del plugin que contiene los [casos de eval](/docs/es/plugin-evals#use-a-different-eval-directory) del plugin, cuando no es el `evals/` predeterminado. `claude plugin eval --eval-dir` lo anula | `"quality/evals"` |
608| `userConfig` | object | Valores configurables por el usuario solicitados en tiempo de habilitación. Vea [Configuración de usuario](#user-configuration) | |
609| `channels` | array | Declaraciones de canales para inyección de mensajes (estilo Telegram, Slack, Discord). Vea [Canales](#channels) | |
610| `dependencies` | array | Otros plugins que este plugin requiere, opcionalmente con restricciones de versión semver. Vea [Restringir versiones de dependencia de plugins](/docs/es/plugin-dependencies) | `[{ "name": "secrets-vault", "version": "~2.1.0" }]` |
611
612<h3 id="experimental-components">
613 Componentes experimentales
614</h3>
615
616Los componentes bajo la clave `experimental`, `themes` y `monitors`, tienen un esquema de manifiesto que puede cambiar entre versiones mientras se estabilizan. Dónde los declara es una migración separada: el nivel superior aún funciona, `claude plugin validate` advierte, y una versión futura requerirá `experimental.*`.
617
618<h3 id="user-configuration">
619 Configuración de usuario
620</h3>
621
622El campo `userConfig` declara valores que Claude Code solicita al usuario cuando el plugin está habilitado. Úselo en lugar de requerir que los usuarios editen manualmente `settings.json`.
623
624```json theme={null}
625{
626 "userConfig": {
627 "api_endpoint": {
628 "type": "string",
629 "title": "API endpoint",
630 "description": "Your team's API endpoint"
631 },
632 "api_token": {
633 "type": "string",
634 "title": "API token",
635 "description": "API authentication token",
636 "sensitive": true
637 }
638 }
639}
640```
641
642Las claves deben ser identificadores válidos. Cada opción admite estos campos:
643
644| Campo | Requerido | Descripción |
645| :------------ | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
646| `type` | Sí | Uno de `string`, `number`, `boolean`, `directory`, o `file` |
647| `title` | Sí | Etiqueta mostrada en el diálogo de configuración |
648| `description` | Sí | Texto de ayuda mostrado debajo del campo |
649| `sensitive` | No | Si es `true`, enmascara la entrada y almacena el valor en almacenamiento seguro en lugar de `settings.json` |
650| `required` | No | Si es `true`, la validación falla cuando el campo está vacío |
651| `default` | No | Valor utilizado cuando el usuario no proporciona nada |
652| `options` | No | Para tipo `string`, los valores que el campo acepta, mostrados en `/config` como un selector sobre ellos. Vea [Limitar un campo a opciones fijas](#limit-a-field-to-fixed-options). Requiere Claude Code v2.1.271 o posterior |
653| `multiple` | No | Para tipo `string`, permitir un array de cadenas |
654| `min` / `max` | No | Límites para tipo `number` |
655
656Excepto campos `sensitive` y listas `multiple`, cada campo de cada plugin habilitado también aparece como una fila en el panel `/config`. Las filas requieren Claude Code v2.1.269 o posterior.
657
658Cada valor está disponible para sustitución como `${user_config.KEY}` en configuraciones de servidores MCP y LSP y comandos de hooks. Los valores no sensibles también pueden sustituirse en contenido de skills y agentes. Todos los valores se exportan a procesos de hooks como variables de entorno `CLAUDE_PLUGIN_OPTION_<KEY>`, donde `<KEY>` es la clave de opción en mayúsculas.
659
660Los campos que se ejecutan en un shell rechazan `${user_config.*}`: sustituir un valor configurado en un comando de shell permitiría que el shell ejecute lo que ese valor contiene, por lo que el componente falla con un [error](/docs/es/errors#plugin-command-references-user-config) en su lugar. Cada campo rechazado tiene una forma alternativa de pasar el valor:
661
662| Campo rechazado | Cómo pasar el valor |
663| :--------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- |
664| Comandos de hooks en forma de shell | Use [forma exec](/docs/es/hooks#exec-form-and-shell-form) con `args`, o lea `CLAUDE_PLUGIN_OPTION_<KEY>` del entorno del hook |
665| Comandos de [Monitor](#monitors) | Lea el valor de un archivo de configuración en el script |
666| MCP [`headersHelper`](/docs/es/mcp#use-dynamic-headers-for-custom-authentication) | Lea el valor de un archivo de configuración en el script |
667
668Antes de v2.1.207, estos campos sustituían valores `${user_config.KEY}`; actualice los plugins que dependían de esto.
669
670Los valores no sensibles se almacenan bajo la clave [`pluginConfigs`](/docs/es/settings-reference#pluginconfigs) en su `settings.json` de usuario como `pluginConfigs[<plugin-id>].options`.
671
672En macOS, Claude Code almacena valores sensibles en el Keychain de macOS, retrocediendo a `~/.claude/.credentials.json` cuando el Keychain rechaza la escritura. En plataformas sin un keychain compatible, los almacena en `~/.claude/.credentials.json`. El almacenamiento de Keychain se comparte con tokens OAuth y tiene un límite total aproximado de 2 KB, por lo que mantenga los valores sensibles pequeños.
673
674Claude Code lee todos los valores `pluginConfigs` de solo tres fuentes de configuración:
675
676* **Configuración de usuario**: `~/.claude/settings.json`, el archivo que el aviso de tiempo de habilitación escribe
677* **`--settings`**: la bandera CLI o configuración en línea de SDK
678* **Configuración administrada**: [política controlada por la organización](/docs/es/permissions#managed-settings)
679
680Cuando más de una fuente establece la misma clave, la configuración administrada tiene precedencia, luego `--settings`, luego la configuración de usuario. La única fuente que puede eliminar de esta lista es la configuración de usuario: pase [`--setting-sources`](/docs/es/cli-reference#cli-flags) sin `user` y Claude Code las omite. La configuración administrada y `--settings` permanecen como usted las pase. La opción [`settingSources`](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) del SDK establece la misma lista.
681
682Las entradas en `.claude/settings.json` o `.claude/settings.local.json` de un proyecto se ignoran. Ambos archivos viven en el espacio de trabajo, por lo que un repositorio clonado podría suministrar valores allí, y esos valores fluirían hacia comandos de hooks de plugins, configuraciones de servidores MCP, comandos LSP y comandos de monitores. Antes de v2.1.207, estas entradas se leían. La restricción es específica de `pluginConfigs`: [`enabledPlugins`](/docs/es/settings-reference#enabledplugins) aún honra la configuración de proyecto y local.
683
684<h4 id="limit-a-field-to-fixed-options">
685 Limitar un campo a opciones fijas
686</h4>
687
688Establezca `options` en un campo `userConfig` para que los usuarios elijan su valor de una lista fija.
689
690Para limitar un campo `tone` a tres opciones, enumérelas en `options` y establezca `default` en una de ellas:
691
692```json theme={null}
693{
694 "userConfig": {
695 "tone": {
696 "type": "string",
697 "title": "Tone",
698 "description": "Voice for generated replies",
699 "options": ["neutral", "warm", "formal"],
700 "default": "neutral"
701 }
702 }
703}
704```
705
706Si declara `options` en cualquier campo, los usuarios en versiones de Claude Code anteriores a v2.1.271 no pueden cargar el plugin.
707
708Cuando establece `options` en un campo, siga estas reglas:
709
710* Establezca `type` en `string`
711* No establezca `multiple` o `sensitive` en `true`
712* Establezca `default` en una de las opciones
713* Si deja `default` sin establecer, establezca `required` en `true`
714* Liste al menos una opción, cada una de 1 a 64 caracteres de largo
715* No comience ni termine una opción con un espacio
716* No use caracteres de control, caracteres invisibles, caracteres que cambien la dirección del texto, o espacios que no sean un espacio regular en una opción
717* No liste la misma opción dos veces, ni siquiera en una letra diferente
718
719Si incumple cualquiera de estas reglas, el plugin no se carga. Ejecute `claude plugin validate` para ver qué campo incumple qué regla.
720
721<h3 id="channels">
722 Canales
723</h3>
724
725El campo `channels` permite que un plugin declare uno o más canales de mensaje que inyecten contenido en la conversación. Cada canal se vincula a un servidor MCP que proporciona el plugin.
726
727```json theme={null}
728{
729 "channels": [
730 {
731 "server": "telegram",
732 "userConfig": {
733 "bot_token": {
734 "type": "string",
735 "title": "Bot token",
736 "description": "Telegram bot token",
737 "sensitive": true
738 },
739 "owner_id": {
740 "type": "string",
741 "title": "Owner ID",
742 "description": "Your Telegram user ID"
743 }
744 }
745 }
746 ]
747}
748```
749
750El campo `server` es requerido y debe coincidir con una clave en los `mcpServers` del plugin. El `userConfig` opcional por canal usa el mismo esquema que el campo de nivel superior, permitiendo que el plugin solicite tokens de bot o IDs de propietario cuando el plugin está habilitado.
751
752<h3 id="path-behavior-rules">
753 Reglas de comportamiento de ruta
754</h3>
755
756Si una ruta personalizada reemplaza o extiende el directorio predeterminado del plugin depende del campo:
757
758* **Reemplaza el predeterminado**: `commands`, `agents`, `workflows`, `outputStyles`, `experimental.themes`, `experimental.monitors`. Por ejemplo, cuando el manifiesto especifica `commands`, el directorio predeterminado `commands/` no se escanea. Para mantener el predeterminado y agregar más, enumérelo explícitamente: `"commands": ["./commands/", "./extras/"]`
759* **Se agrega al predeterminado**: `skills`. El directorio predeterminado `skills/` siempre se escanea, y los directorios listados en `skills` se cargan junto a él. Excepción: para una [entrada de marketplace cuya `source` se resuelve a la raíz de marketplace](/docs/es/plugin-marketplaces#advanced-plugin-entries), declarar subdirectorios específicos reemplaza el escaneo predeterminado `skills/`
760* **Reglas de fusión propias**: [hooks](#hooks), [servidores MCP](#mcp-servers), y [servidores LSP](#lsp-servers). Vea cada sección para saber cómo se combinan múltiples fuentes
761
762Cuando un plugin tiene tanto una carpeta predeterminada como la clave de manifiesto coincidente, Claude Code advierte sobre la carpeta ignorada en `claude plugin list` y la vista de detalles `/plugin`. El plugin aún se carga usando las rutas de manifiesto. Claude Code no advierte cuando la clave de manifiesto apunta dentro de la carpeta predeterminada, por ejemplo `"commands": ["./commands/deploy.md"]`, porque esa ruta nombra la carpeta explícitamente.
763
764Para todos los campos de ruta:
765
766* Todas las rutas deben ser relativas a la raíz del plugin e iniciar con `./`, excepto que el campo `skills` también acepta `"."`
767 * Tanto `"."` como `"./"` denotan la raíz del plugin en sí
768 * Antes de v2.1.221, `"."` falló en la validación del manifiesto y el plugin no se cargó, así que use `"./"` para soportar versiones anteriores
769* Los componentes de rutas personalizadas usan las mismas reglas de nomenclatura y espacios de nombres, excepto archivos de agentes. Vea [Agentes](#agents) para saber cómo funcionan los nombres de agentes
770* Se pueden especificar múltiples rutas como arrays
771* Una ruta de skill puede apuntar a un directorio que contiene un `SKILL.md` directamente, por ejemplo `"skills": ["."]` para la raíz del plugin
772 * Claude Code toma el nombre de invocación del skill del campo `name` del frontmatter en `SKILL.md`, por lo que el nombre permanece estable sin importar cómo se nombre el directorio de instalación
773 * Si `name` no está establecido en el frontmatter, Claude Code retrocede al nombre base del directorio
774
775Un plugin que tiene un `SKILL.md` en su raíz, sin subdirectorio `skills/`, y sin campo de manifiesto `skills` se carga automáticamente como un plugin de un solo skill. No necesita establecer `"skills": ["./"]` en `plugin.json` para este diseño.
776
777**Ejemplos de ruta**:
778
779```json theme={null}
780{
781 "commands": [
782 "./specialized/deploy.md",
783 "./utilities/batch-process.md"
784 ],
785 "agents": [
786 "./custom-agents/reviewer.md",
787 "./custom-agents/tester.md"
788 ]
789}
790```
791
792<h3 id="environment-variables">
793 Variables de entorno
794</h3>
795
796Claude Code proporciona tres variables para referenciar rutas:
797
798| Variable | Se resuelve a | Úselo para |
799| :---------------------- | :---------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
800| `${CLAUDE_PLUGIN_ROOT}` | Ruta absoluta al directorio de instalación del plugin | Scripts, binarios y archivos de configuración incluidos con el plugin |
801| `${CLAUDE_PLUGIN_DATA}` | [Directorio persistente](#persistent-data-directory) que sobrevive a actualizaciones de plugins, creado en primera referencia | Dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado y cachés |
802| `${CLAUDE_PROJECT_DIR}` | La raíz del proyecto | Scripts y archivos de configuración locales del proyecto |
803
804Los tres se exportan como variables de entorno a procesos de hooks y a subprocesos de servidores MCP y LSP. No están presentes en el entorno de comandos que Claude ejecuta a través de la herramienta Bash, en la sesión principal o en un subagente. En contenido de plugins, escriba el marcador de posición en su lugar, y Claude Code sustituye la ruta en línea cuando carga el contenido. Qué campos sustituyen en línea depende del componente del plugin:
805
806| Componente del plugin | Campos donde se resuelven los marcadores de posición |
807| :--------------------------------- | :-------------------------------------------------------- |
808| Contenido de skill y agente | En cualquier lugar donde aparezca el marcador de posición |
809| Comandos de hook y monitor | En cualquier lugar donde aparezca el marcador de posición |
810| Servidores MCP `stdio` | `command`, `args`, `env` |
811| Servidores MCP `http`, `sse`, `ws` | `url`, `headers`, `headersHelper` |
812| Servidores LSP | `command`, `args`, `env`, `workspaceFolder` |
813
814En comandos de hooks, use [forma exec](/docs/es/hooks#exec-form-and-shell-form) con `args` para que cada ruta se pase como un argumento sin comillas. En hooks de forma shell y comandos de monitores, envuelva las variables entre comillas dobles, como en `"${CLAUDE_PROJECT_DIR}/scripts/server.sh"`. Este hook de forma shell ejecuta un script incluido con un plugin:
815
816```json theme={null}
817{
818 "hooks": {
819 "PostToolUse": [
820 {
821 "hooks": [
822 {
823 "type": "command",
824 "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/process.sh"
825 }
826 ]
827 }
828 ]
829 }
830}
831```
832
833Para un plugin copiado, `${CLAUDE_PLUGIN_ROOT}` cambia cuando el plugin se actualiza. El directorio de la versión anterior permanece en el disco durante un período de gracia después de una actualización, pero trátelo como efímero y no escriba estado allí. Para un plugin cargado en lugar desde un marketplace de directorio local, la variable apunta al directorio de origen estable. Vea [almacenamiento en caché de plugins](#plugin-caching-and-file-resolution) para saber qué plugins se copian y para semántica de limpieza.
834
835Cuando un plugin copiado se actualiza a mitad de sesión, comandos de hooks, monitores, servidores MCP y servidores LSP continúan usando la ruta de la versión anterior. Ejecute `/reload-plugins` para cambiar hooks, servidores MCP y servidores LSP a la nueva ruta; los monitores requieren un reinicio de sesión. En una sesión sin terminal interactiva, la recarga deja servidores MCP de plugins en la ruta anterior hasta la siguiente sesión.
836
837Para un plugin con una `command` source, Claude Code [puede recargar el plugin en sí](/docs/es/plugin-marketplaces#when-claude-code-re-runs-the-command).
838
839Los servidores MCP también pueden llamar a la solicitud `roots/list` para leer los directorios de trabajo de la sesión en tiempo de ejecución. Vea [qué devuelve `roots/list` y cuándo Claude Code notifica al servidor de cambios](/docs/es/mcp#option-3-add-a-local-stdio-server).
840
841<h4 id="persistent-data-directory">
842 Directorio de datos persistente
843</h4>
844
845El directorio `${CLAUDE_PLUGIN_DATA}` se resuelve a `~/.claude/plugins/data/{id}/`, donde `{id}` es el identificador del plugin con caracteres fuera de `a-z`, `A-Z`, `0-9`, `_`, y `-` reemplazados por `-`. Para un plugin instalado como `formatter@my-marketplace`, el directorio es `~/.claude/plugins/data/formatter-my-marketplace/`.
846
847Un uso común es instalar dependencias de lenguaje una vez y reutilizarlas en sesiones y actualizaciones de plugins. Úselo para dependencias de Python, dependencias bloqueadas con Yarn o pnpm, y paquetes cuyos scripts de ciclo de vida deben ejecutarse. Para un plugin instalado desde marketplace, es posible que no lo necesite en absoluto: Claude Code instala automáticamente [dependencias de paquetes Node.js](/docs/es/plugins-reference#node-js-package-dependencies) elegibles cuando almacena en caché el plugin.
848
849Debido a que el directorio de datos sobrevive a cualquier versión única de plugin, una verificación de existencia de directorio por sí sola no puede detectar cuándo una actualización cambia el manifiesto de dependencia del plugin. El patrón recomendado compara el manifiesto incluido contra una copia en el directorio de datos y reinstala cuando difieren.
850
851Este hook `SessionStart` instala `node_modules` en la primera ejecución y nuevamente cada vez que una actualización de plugin incluye un `package.json` cambiado:
852
853```json theme={null}
854{
855 "hooks": {
856 "SessionStart": [
857 {
858 "hooks": [
859 {
860 "type": "command",
861 "command": "diff -q \"${CLAUDE_PLUGIN_ROOT}/package.json\" \"${CLAUDE_PLUGIN_DATA}/package.json\" >/dev/null 2>&1 || (cd \"${CLAUDE_PLUGIN_DATA}\" && cp \"${CLAUDE_PLUGIN_ROOT}/package.json\" . && npm install) || rm -f \"${CLAUDE_PLUGIN_DATA}/package.json\""
862 }
863 ]
864 }
865 ]
866 }
867}
868```
869
870El `diff` sale con código distinto de cero cuando la copia almacenada falta o difiere de la incluida, cubriendo tanto la primera ejecución como actualizaciones que cambian dependencias. Si `npm install` falla, el `rm` final elimina el manifiesto copiado para que la siguiente sesión reintente.
871
872Los scripts incluidos en `${CLAUDE_PLUGIN_ROOT}` pueden ejecutarse contra los `node_modules` persistidos:
873
874```json theme={null}
875{
876 "mcpServers": {
877 "routines": {
878 "command": "node",
879 "args": ["${CLAUDE_PLUGIN_ROOT}/server.js"],
880 "env": {
881 "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules"
882 }
883 }
884 }
885}
886```
887
888El directorio de datos se elimina automáticamente cuando desinstala el plugin del último ámbito donde está instalado. La interfaz `/plugin` muestra el tamaño del directorio y solicita confirmación antes de eliminar. El CLI elimina por defecto; pase [`--keep-data`](#plugin-uninstall) para preservarlo.
889
890***
891
892<h2 id="plugin-caching-and-file-resolution">
893 Almacenamiento en caché de plugins y resolución de archivos
894</h2>
895
896Los plugins se especifican de una de tres formas:
897
898* A través de `claude --plugin-dir` o `claude --plugin-url`, durante la duración de una sesión.
899* A través de un marketplace, instalado para sesiones futuras.
900* A través de su cuenta de claude.ai, [sincronizado](#synced-plugins) en `~/.claude/plugins/synced/`.
901
902Por razones de seguridad y verificación, Claude Code copia los plugins del *marketplace* en la **caché de plugins** local del usuario (`~/.claude/plugins/cache`), a menos que el plugin se cargue en su lugar. Una [fuente `command` en modo de enlace](/docs/es/plugin-marketplaces#copy-mode-and-link-mode) se carga en su lugar a través de enlaces en la entrada de caché. Una [fuente de ruta relativa](/docs/es/plugin-marketplaces#relative-paths) en un marketplace agregado desde un directorio local se carga en su lugar desde la carpeta del marketplace.
903
904Para un plugin cargado en su lugar desde un marketplace de directorio local, sus ediciones al directorio de origen surten efecto en el siguiente inicio de sesión o `/reload-plugins`. No necesita un aumento de versión. Los procesos de hook del plugin y los servidores MCP y LSP reciben un `CLAUDE_PLUGIN_ROOT` que apunta al directorio de origen. Claude Code no instala las [dependencias de paquetes Node.js](#node-js-package-dependencies) del plugin en el directorio de origen. Instálelas allí usted mismo, o desde un hook en el [directorio de datos persistentes](#persistent-data-directory).
905
906Para plugins copiados, cada versión instalada es un directorio separado en la caché, agrupado por marketplace y plugin y nombrado para la versión resuelta, con su propia copia de los archivos del plugin y [dependencias de paquetes Node.js](#node-js-package-dependencies). Una dependencia resuelta desde una [etiqueta de lanzamiento](/docs/es/plugin-dependencies#tag-plugin-releases-for-version-resolution) obtiene un nombre de directorio con un sufijo de SHA de confirmación.
907
908Cuando actualiza o desinstala un plugin, Claude Code marca el directorio de versión anterior como huérfano y lo elimina en un barrido de fondo aproximadamente 14 días después. El período de gracia permite que las sesiones concurrentes de Claude Code que ya cargaron la versión anterior sigan ejecutándose sin errores. Claude Code ejecuta el barrido solo mientras al menos un plugin esté instalado; después de desinstalar su último plugin, los directorios huérfanos permanecen en el disco hasta que instale un plugin nuevamente.
909
910Claude Code elimina una carpeta de plugin o marketplace de la caché solo cuando ya no contiene ningún directorio o enlace simbólico. Si vincula un checkout de desarrollo en la caché como entrada de versión de un plugin, Claude Code nunca marca el enlace como huérfano y nunca lo elimina ni las carpetas que lo contienen. Claude Code tampoco escribe nunca sus archivos de seguimiento de versiones dentro del checkout vinculado.
911
912Las herramientas Glob y Grep de Claude omiten directorios de versión huérfanos durante búsquedas, por lo que los resultados de archivos no incluyen código de plugin obsoleto.
913
914<h3 id="node-js-package-dependencies">
915 Dependencias de paquetes Node.js
916</h3>
917
918Cuando Claude Code copia un plugin en la caché, también instala las dependencias de paquetes Node.js del plugin allí, para que los hooks y servidores MCP del plugin puedan cargarlas. Esta sección cubre los paquetes npm y Bun que un plugin declara en su propio `package.json`. Para plugins que dependen de otros plugins, consulte [versiones de dependencias de plugins](/docs/es/plugin-dependencies).
919
920Claude Code ejecuta la instalación dentro del directorio de versión copiado cada vez que crea uno: cuando instala un plugin, cuando Claude Code actualiza un plugin a una nueva versión, y al inicio de la sesión cuando un plugin habilitado aún no está en caché, como en una máquina nueva. La instalación se ejecuta solo cuando el directorio raíz del plugin contiene tanto un `package.json` como un archivo de bloqueo compatible:
921
922| Archivo de bloqueo | Comando |
923| :------------------------------------------ | :----------------------------------------------- |
924| `bun.lock` o `bun.lockb` | `bun install --frozen-lockfile --ignore-scripts` |
925| `npm-shrinkwrap.json` o `package-lock.json` | `npm ci --ignore-scripts` |
926
927Si un plugin contiene más de uno de estos archivos de bloqueo, Claude Code usa la primera coincidencia, verificando en orden: `bun.lock`, `bun.lockb`, `npm-shrinkwrap.json`, `package-lock.json`.
928
929Claude Code omite la instalación en dos casos, cada uno con su propia solución:
930
931* Si su plugin solo incluye un `yarn.lock` o `pnpm-lock.yaml`, reemplácelo con un archivo de bloqueo npm.
932* Si un `bunfig.toml` se encuentra junto al archivo de bloqueo bun, elimine el `bunfig.toml`, o reemplace el archivo de bloqueo bun con un archivo de bloqueo npm.
933
934Envíe un archivo de bloqueo npm para el alcance más amplio. Claude Code ejecuta el gestor de paquetes del archivo de bloqueo coincidente desde el PATH del usuario y no recurre al otro archivo de bloqueo si falta. Para un plugin distribuido a través de una fuente npm, use `npm-shrinkwrap.json`; npm excluye `package-lock.json` de los paquetes publicados.
935
936Claude Code restringe esta instalación de dependencias para que ningún código del plugin o sus paquetes se ejecute durante ella, y limita cuánto tiempo puede ejecutarse:
937
938* **Resolución congelada:** Bun y npm instalan exactamente lo que el archivo de bloqueo fija, y fallan en lugar de re-resolver versiones cuando `package.json` y el archivo de bloqueo no coinciden.
939* **Sin scripts de ciclo de vida:** `--ignore-scripts` evita que se ejecuten scripts `preinstall`, `install` y `postinstall`, por lo que las dependencias que construyen módulos nativos en esos scripts se descargan pero no se compilan durante esta instalación.
940* **Tiempo de espera de 60 segundos:** Claude Code detiene una instalación que se ejecuta más tiempo y la trata como fallida.
941
942Claude Code obtiene un plugin de fuente npm antes de esta instalación de dependencias, y ninguno de los scripts de instalación propios del paquete se ejecuta durante la obtención. Consulte [paquetes npm](/docs/es/plugin-marketplaces#npm-packages).
943
944Una instalación fallida u omitida nunca bloquea el plugin. Cuando la instalación falla, o Claude Code omite porque hay un archivo de bloqueo yarn o pnpm o un `bunfig.toml`, registra el motivo como una advertencia en [salida de depuración](#debugging-commands). Un plugin con un `package.json` y sin archivo de bloqueo se omite sin una entrada de registro. Una instalación que agota el tiempo de espera puede dejar un árbol `node_modules` parcial en la copia en caché.
945
946No puede desactivar la instalación automática; ninguna configuración o variable de entorno la desactiva. En redes restringidas, consulte los [requisitos de acceso a la red](/docs/es/network-config#network-access-requirements) para los hosts a permitir.
947
948Para dependencias que la instalación automática no puede proporcionar, como paquetes que necesitan sus scripts de ciclo de vida para construir, dependencias de Python, o un plugin bloqueado con Yarn o pnpm, instálelas desde un hook en el [directorio de datos persistentes](#persistent-data-directory).
949
950<h3 id="path-traversal-limitations">
951 Limitaciones de traversal de rutas
952</h3>
953
954Claude Code no permite que un plugin haga referencia a archivos fuera de su propio directorio. Rechaza una ruta de componente que se resuelve fuera de la raíz del plugin, ya sea que la ruta se declare en `plugin.json` o en una [entrada de marketplace](/docs/es/plugin-marketplaces#plugin-entries). Eso cubre una ruta que apunta fuera del plugin tal como está escrito, como `../shared-utils`, y un enlace simbólico que conduce fuera del plugin, que no sea [enlaces dentro de un marketplace](#share-files-within-a-marketplace-with-symlinks).
955
956En macOS y Linux, Claude Code también rechaza una ruta de componente que contiene una barra invertida en cualquier lugar, incluso cuando la ruta permanece dentro del plugin. Los componentes declarados con rutas de barra invertida, por lo tanto, se cargan solo en Windows. Escriba rutas de componentes con barras diagonales, como `./commands/deploy.md`.
957
958Cuando Claude Code rechaza una ruta, reporta un error [`path escapes plugin directory`](/docs/es/errors#path-escapes-plugin-directory) y carga el plugin sin ese componente.
959
960Claude Code tampoco copia archivos fuera del directorio del plugin en la caché cuando instala el plugin, por lo que cuando un script dentro de un plugin copiado lee una ruta por encima de la raíz del plugin, tampoco encuentra esos archivos.
961
962<h3 id="share-files-within-a-marketplace-with-symlinks">
963 Compartir archivos dentro de un marketplace con enlaces simbólicos
964</h3>
965
966Si su plugin necesita compartir archivos con otras partes del mismo marketplace, puede crear enlaces simbólicos dentro de su directorio de plugin. Cómo se maneja un enlace simbólico cuando el plugin se copia en la caché depende de dónde se resuelve su destino:
967
968* **Dentro del propio directorio del plugin:** el enlace simbólico se preserva como un enlace simbólico relativo en la caché, por lo que sigue resolviendo al destino copiado en tiempo de ejecución.
969* **En otro lugar dentro del mismo marketplace:** el enlace simbólico se desreferencia. El contenido del destino se copia en la caché en su lugar. Esto permite que el directorio `skills/` de un meta-plugin se vincule a skills definidas por otros plugins en el marketplace.
970* **Fuera del marketplace:** el enlace simbólico se omite por seguridad. Esto evita que los plugins extraigan archivos de host arbitrarios como rutas del sistema en la caché.
971
972Para plugins instalados con `--plugin-dir`, desde una ruta local, o desde una [fuente `command`](/docs/es/plugin-marketplaces#copy-mode-and-link-mode) en modo de copia, solo se preservan los enlaces simbólicos que se resuelven dentro del propio directorio del plugin. Todos los demás se omiten.
973
974El siguiente comando crea un enlace desde dentro de un plugin de marketplace a una skill compartida definida por un plugin hermano. En Windows, use `mklink /D` desde un símbolo del sistema elevado o habilite el Modo de desarrollador:
975
976```bash theme={null}
977ln -s ../../shared-plugin/skills/foo ./skills/foo
978```
979
980***
981
982<h2 id="plugin-directory-structure">
983 Estructura de directorios de plugins
984</h2>
985
986<h3 id="standard-plugin-layout">
987 Diseño estándar de plugins
988</h3>
989
990Un plugin completo sigue esta estructura:
991
992```text theme={null}
993enterprise-plugin/
994├── .claude-plugin/ # Directorio de metadatos (opcional)
995│ └── plugin.json # manifiesto del plugin
996├── skills/ # Skills
997│ ├── code-reviewer/
998│ │ └── SKILL.md
999│ └── pdf-processor/
1000│ ├── SKILL.md
1001│ └── scripts/
1002├── commands/ # Skills como archivos .md planos
1003│ ├── status.md
1004│ └── logs.md
1005├── agents/ # Definiciones de subagentes
1006│ ├── security-reviewer.md
1007│ ├── performance-tester.md
1008│ ├── compliance-checker.md
1009│ └── review/ # Los agentes aquí se cargan como enterprise-plugin:review:<name>
1010│ └── accessibility.md
1011├── workflows/ # Scripts de flujo de trabajo
1012│ └── release-audit.js
1013├── output-styles/ # Definiciones de estilos de salida
1014│ └── terse.md
1015├── themes/ # Definiciones de temas de color
1016│ └── dracula.json
1017├── monitors/ # Configuraciones de monitores de fondo
1018│ └── monitors.json
1019├── hooks/ # Configuraciones de hooks
1020│ ├── hooks.json # Configuración principal de hooks
1021│ └── security-hooks.json # Hooks adicionales
1022├── bin/ # Ejecutables de plugins agregados a PATH
1023│ └── my-tool # Invocable como comando desnudo en la herramienta Bash
1024├── settings.json # Configuración predeterminada para el plugin
1025├── .mcp.json # Definiciones de servidores MCP
1026├── .lsp.json # Configuraciones de servidores LSP
1027├── scripts/ # Scripts de hooks y utilidades
1028│ ├── security-scan.sh
1029│ ├── format-code.py
1030│ └── deploy.js
1031├── LICENSE # Archivo de licencia
1032└── CHANGELOG.md # Historial de versiones
1033```
1034
1035<Warning>
1036 El directorio `.claude-plugin/` contiene el archivo `plugin.json`. Todos los demás directorios (commands/, agents/, skills/, workflows/, output-styles/, themes/, monitors/, hooks/) deben estar en la raíz del plugin, no dentro de `.claude-plugin/`.
1037</Warning>
1038
1039Un archivo `CLAUDE.md` en la raíz del plugin no se carga como contexto del proyecto. Los plugins contribuyen contexto a través de skills, agentes y hooks en lugar de CLAUDE.md. Para enviar instrucciones que se carguen en el contexto de Claude, colóquelas en un [skill](#skills).
1040
1041<h3 id="file-locations-reference">
1042 Referencia de ubicaciones de archivos
1043</h3>
1044
1045| Componente | Ubicación predeterminada | Propósito |
1046| :-------------------- | :--------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1047| **Manifiesto** | `.claude-plugin/plugin.json` | Metadatos y configuración del plugin (opcional) |
1048| **Skills** | `skills/` | Skills con estructura `<name>/SKILL.md` |
1049| **Comandos** | `commands/` | Skills como archivos Markdown planos. Use `skills/` para nuevos plugins |
1050| **Agentes** | `agents/` | Archivos Markdown de subagentes. Las subcarpetas son parte del [nombre del agente](#agents) |
1051| **Flujos de trabajo** | `workflows/` | Archivos de script de [flujo de trabajo](/docs/es/workflows) |
1052| **Estilos de salida** | `output-styles/` | Definiciones de estilos de salida |
1053| **Temas** | `themes/` | Definiciones de temas de color |
1054| **Hooks** | `hooks/hooks.json` | Configuración de hooks |
1055| **Servidores MCP** | `.mcp.json` | Definiciones de servidores MCP |
1056| **Servidores LSP** | `.lsp.json` | Configuraciones de servidores de lenguaje |
1057| **Monitores** | `monitors/monitors.json` | Configuraciones de monitores de fondo |
1058| **Ejecutables** | `bin/` | Ejecutables agregados a `PATH` de la herramienta Bash e invocables como comandos desnudos mientras el plugin está habilitado. No puede incluir este directorio en un plugin que [distribuya a través de la configuración de la organización claude.ai](/docs/es/plugin-marketplaces#keep-executables-out-of-the-top-level-bin-directory) |
1059| **Configuración** | `settings.json` | Configuración predeterminada aplicada cuando el plugin está habilitado. Solo se admiten las claves [`agent`](/docs/es/sub-agents) y [`subagentStatusLine`](/docs/es/statusline#subagent-status-lines) |
1060
1061***
1062
1063<h2 id="cli-commands-reference">
1064 Referencia de comandos CLI
1065</h2>
1066
1067Claude Code proporciona comandos CLI para la gestión de plugins no interactiva, útil para scripting y automatización.
1068
1069<h3 id="plugin-init">
1070 plugin init
1071</h3>
1072
1073Crea un nuevo plugin en `~/.claude/skills/<name>/`. En la siguiente sesión de Claude Code se carga automáticamente como `<name>@skills-dir` y aparece en `/plugin` y `claude plugin list` sin necesidad de un paso de instalación.
1074
1075Consulte [Plugins de directorio de skills](#skills-directory-plugins) para conocer los requisitos de alcance y confianza.
1076
1077```bash theme={null}
1078claude plugin init <name> [options]
1079```
1080
1081El comando toma estos argumentos:
1082
1083* `<name>`: Nombre del plugin. Se convierte en el espacio de nombres de la skill y el nombre del directorio bajo `~/.claude/skills/`, por lo que no puede contener espacios ni separadores de ruta.
1084
1085El comando acepta estas opciones:
1086
1087| Opción | Descripción | Predeterminado |
1088| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :---------------------- |
1089| `--description <text>` | Descripción del manifiesto | |
1090| `--author <name>` | Nombre del autor | `git config user.name` |
1091| `--author-email <email>` | Correo electrónico del autor | `git config user.email` |
1092| `--with <components...>` | También crea carpetas de componentes. Valores válidos: `skills`, `agents`, `hooks`, `mcp`, `lsp`, `output-style`, `channel` | |
1093| `-f, --force` | Sobrescribe un `.claude-plugin/` existente en el destino | |
1094| `-h, --help` | Muestra la ayuda del comando | |
1095
1096`claude plugin new` es un alias para este comando.
1097
1098Cada valor `--with` añade un archivo de inicio para ese componente, listo para editar:
1099
1100| Componente | Lo que crea |
1101| :------------- | :---------------------------------------------------------------------------------------------------------- |
1102| `skills` | Una skill adicional con espacio de nombres `<name>:example` junto a la predeterminada |
1103| `agents` | Una definición de subagente en `agents/` |
1104| `hooks` | Un `hooks/hooks.json` con un controlador de eventos de ejemplo |
1105| `mcp` | Un `.mcp.json` con ejemplos de servidor HTTP y stdio |
1106| `lsp` | Un ejemplo de servidor de lenguaje `.lsp.json` |
1107| `output-style` | Un `output-styles/<name>.md` que se aplica automáticamente mientras el plugin está habilitado |
1108| `channel` | Un [canal](/docs/es/channels) basado en MCP: un servidor stdio (`server.ts`), su `.mcp.json` y un `package.json` |
1109
1110El plugin creado utiliza la fuente `@skills-dir` en lugar de un marketplace. Los administradores pueden bloquear esta fuente con `strictKnownMarketplaces` o añadiendo `{"source": "skills-dir"}` a `blockedMarketplaces` en [configuración administrada](/docs/es/plugin-marketplaces#managed-marketplace-restrictions). Cuando está bloqueado, `plugin init` falla antes de escribir.
1111
1112Estos ejemplos muestran invocaciones comunes:
1113
1114```bash theme={null}
1115# Crea un plugin mínimo
1116claude plugin init my-helper
1117
1118# Crea con carpetas de skill y hook
1119claude plugin init my-helper --with skills hooks
1120
1121# Sobrescribe un scaffold existente
1122claude plugin init my-helper --force
1123```
1124
1125<h3 id="plugin-install">
1126 plugin install
1127</h3>
1128
1129Instala un plugin desde los marketplaces disponibles.
1130
1131```bash theme={null}
1132claude plugin install <plugin> [options]
1133```
1134
1135El comando toma estos argumentos:
1136
1137* `<plugin>`: Nombre del plugin o `plugin-name@marketplace-name` para un marketplace específico
1138
1139El comando acepta estas opciones:
1140
1141| Opción | Descripción | Predeterminado |
1142| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------- |
1143| `-s, --scope <scope>` | Alcance de instalación: `user`, `project` o `local` | `user` |
1144| `--config <key=value>` | Establece una opción [`userConfig`](#user-configuration) declarada en el manifiesto del plugin. Repita la bandera para establecer múltiples opciones | |
1145| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |
1146| `--accept-command <sha256>` | Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con [`--json`](#plugin-json-result) reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior | |
1147| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout en lugar del mensaje legible por humanos, para usar en scripts. Consulte [formato de resultado JSON](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |
1148| `-h, --help` | Muestra la ayuda del comando | |
1149
1150El alcance determina qué archivo de configuración se añade al plugin instalado. Por ejemplo, `--scope project` escribe en `enabledPlugins` en .claude/settings.json, haciendo que el plugin esté disponible para todos los que clonan el repositorio del proyecto.
1151
1152<span id="plugin-json-result" />Con `--json`, la última línea de stdout es un objeto JSON. Analice solo esa línea, porque Claude Code imprime cualquier comando que el marketplace declara antes de ella. Tres campos siempre están presentes:
1153
1154* `command`: el subcomando que se ejecutó, como `install`
1155* `outcome`: `ok` o `failed`
1156* `message`: una descripción legible por humanos del resultado
1157
1158Otros campos, como `pluginId`, `scope` y `failureCode`, aparecen solo cuando aplican. La opción `--json` en `plugin uninstall`, `plugin update`, `plugin enable` y `plugin disable` imprime el mismo objeto con los propios campos de ese subcomando. Un error de uso, como un `--scope` inválido, no imprime ninguna línea de resultado y sale con 1 con la razón en stderr.
1159
1160Cuando una ejecución muestra un comando declarado por el marketplace y no lo ejecuta, el resultado `failed` también lleva un objeto `shownCommand` cuyos campos incluyen el comando tal como se mostró, el plugin al que pertenece y el `sha256` del comando. Para aceptar exactamente ese comando, vuelva a ejecutar con ese `sha256` como `--accept-command`. Requiere Claude Code v2.1.271 o posterior.
1161
1162Si `shownCommand.acceptCommandMatched` es `false`, el resumen que pasó no coincide con el comando ahora mostrado. Muestre ese comando a una persona antes de pasar su `sha256`.
1163
1164Estos ejemplos muestran invocaciones comunes:
1165
1166```bash theme={null}
1167# Instala en alcance de usuario (predeterminado)
1168claude plugin install formatter@my-marketplace
1169
1170# Instala en alcance de proyecto (compartido con el equipo)
1171claude plugin install formatter@my-marketplace --scope project
1172
1173# Instala en alcance local (no compartido con el equipo)
1174claude plugin install formatter@my-marketplace --scope local
1175```
1176
1177<h3 id="plugin-uninstall">
1178 plugin uninstall
1179</h3>
1180
1181Elimina un plugin instalado.
1182
1183```bash theme={null}
1184claude plugin uninstall <plugin> [options]
1185```
1186
1187El comando toma estos argumentos:
1188
1189* `<plugin>`: Nombre del plugin o `plugin-name@marketplace-name`
1190
1191El comando acepta estas opciones:
1192
1193| Opción | Descripción | Predeterminado |
1194| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
1195| `-s, --scope <scope>` | Desinstala del alcance: `user`, `project` o `local` | `user` |
1196| `--keep-data` | Preserva el [directorio de datos persistentes](#persistent-data-directory) del plugin | |
1197| `--prune` | También elimina las dependencias instaladas automáticamente que ningún otro plugin requiere. Consulte [plugin prune](#plugin-prune) | |
1198| `-y, --yes` | Omite el mensaje de confirmación de `--prune`. Requerido cuando stdin o stdout no es una TTY | |
1199| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). No se puede combinar con `--prune`. Requiere Claude Code v2.1.268 o posterior | |
1200| `-h, --help` | Muestra la ayuda del comando | |
1201
1202`claude plugin remove` y `claude plugin rm` son alias para este comando.
1203
1204De forma predeterminada, desinstalar desde el último alcance restante también elimina el directorio `${CLAUDE_PLUGIN_DATA}` del plugin. Use `--keep-data` para preservarlo, por ejemplo al reinstalar después de probar una nueva versión.
1205
1206<Note>
1207 Cuando los plugins instalados desde diferentes marketplaces comparten un nombre, el formulario `plugin-name@marketplace-name` desinstala solo el plugin del marketplace nombrado. Antes de v2.1.212, el formulario calificado podría coincidir y desinstalar el plugin con el mismo nombre desde un marketplace diferente.
1208</Note>
1209
1210<h3 id="plugin-prune">
1211 plugin prune
1212</h3>
1213
1214Elimina las dependencias de plugins instaladas automáticamente que ya no son requeridas por ningún plugin instalado. Las dependencias que Claude Code incluyó para satisfacer el campo [`dependencies`](/docs/es/plugin-dependencies) de otro plugin se eliminan; los plugins que instaló directamente nunca se tocan.
1215
1216```bash theme={null}
1217claude plugin prune [options]
1218```
1219
1220El comando acepta estas opciones:
1221
1222| Opción | Descripción | Predeterminado |
1223| :-------------------- | :------------------------------------------------------------------------------ | :------------- |
1224| `-s, --scope <scope>` | Limpia en alcance: `user`, `project` o `local` | `user` |
1225| `--dry-run` | Lista lo que se eliminaría sin eliminar nada | |
1226| `-y, --yes` | Omite el mensaje de confirmación. Requerido cuando stdin o stdout no es una TTY | |
1227| `-h, --help` | Muestra la ayuda del comando | |
1228
1229`claude plugin autoremove` es un alias para este comando.
1230
1231El comando lista las dependencias huérfanas y solicita confirmación antes de eliminarlas. Para eliminar un plugin y limpiar sus dependencias en un paso, ejecute `claude plugin uninstall <plugin> --prune`.
1232
1233<h3 id="plugin-enable">
1234 plugin enable
1235</h3>
1236
1237Habilita un plugin deshabilitado. Cuando el destino está instalado desde un marketplace y declara [dependencias](/docs/es/plugin-dependencies), Claude Code las habilita transitivamente en el mismo alcance. El comando falla bajo las condiciones que [Habilitar o deshabilitar un plugin con dependencias](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) lista.
1238
1239```bash theme={null}
1240claude plugin enable <plugin> [options]
1241```
1242
1243El comando toma estos argumentos:
1244
1245* `<plugin>`: Nombre del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` para un [plugin sincronizado desde claude.ai](#synced-plugins)
1246
1247El comando acepta estas opciones:
1248
1249| Opción | Descripción | Predeterminado |
1250| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
1251| `-s, --scope <scope>` | Alcance a habilitar: `user`, `project` o `local`. Cuando se omite, Claude Code detecta el alcance donde está instalado el plugin | Detección automática |
1252| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |
1253| `-h, --help` | Muestra la ayuda del comando | |
1254
1255<h3 id="plugin-disable">
1256 plugin disable
1257</h3>
1258
1259Deshabilita un plugin sin desinstalarlo.
1260
1261Cuando el destino está instalado desde un marketplace, el comando falla si otro plugin habilitado [depende de](/docs/es/plugin-dependencies#enable-or-disable-a-plugin-with-dependencies) él. El mensaje de error incluye un comando encadenado que deshabilita primero cada dependiente.
1262
1263Para un [plugin sincronizado](#synced-plugins) que su organización requiere, el comando falla y no guarda nada.
1264
1265```bash theme={null}
1266claude plugin disable [plugin] [options]
1267```
1268
1269El comando toma estos argumentos:
1270
1271* `[plugin]`: Nombre del plugin, `plugin-name@marketplace-name` o `plugin-name@synced` para un [plugin sincronizado desde claude.ai](#synced-plugins). Opcional cuando se usa `--all`
1272
1273El comando acepta estas opciones:
1274
1275| Opción | Descripción | Predeterminado |
1276| :-------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------- |
1277| `-a, --all` | Deshabilita todos los plugins habilitados. No se puede combinar con `--scope` | |
1278| `-s, --scope <scope>` | Alcance a deshabilitar: `user`, `project` o `local`. Cuando se omite, Claude Code detecta el alcance donde está instalado el plugin | Detección automática |
1279| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |
1280| `-h, --help` | Muestra la ayuda del comando | |
1281
1282<h3 id="plugin-update">
1283 plugin update
1284</h3>
1285
1286Actualiza un plugin a la versión más reciente.
1287
1288```bash theme={null}
1289claude plugin update <plugin> [options]
1290```
1291
1292El comando toma estos argumentos:
1293
1294* `<plugin>`: Nombre del plugin o `plugin-name@marketplace-name`
1295
1296El comando acepta estas opciones:
1297
1298| Opción | Descripción | Predeterminado |
1299| :-------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------- |
1300| `-s, --scope <scope>` | Alcance a actualizar: `user`, `project`, `local` o `managed` | `user` |
1301| `-y, --yes` | Acepta un comando que el marketplace del plugin declara, sin el mensaje de confirmación: el comando que produce un plugin con una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), o el [`headersHelper`](/docs/es/plugin-marketplaces#authenticate-archive-downloads) que autentica una descarga de archivo. Aceptar un `headersHelper` requiere Claude Code v2.1.238 o posterior. Claude Code aún imprime el comando primero. Requerido cuando stdin o stdout no es una TTY, a menos que pase `--accept-command`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal | |
1302| `--accept-command <sha256>` | Acepta el comando declarado por el marketplace cuyo `sha256` una ejecución anterior con [`--json`](#plugin-json-result) reportó en `shownCommand`, en lugar de `-y`. La aceptación cuenta para exactamente ese comando, plugin y catálogo de marketplace. Si alguno de ellos cambió desde que se mostró el comando, incluyendo a través de la actualización de marketplace de la propia ejecución, Claude Code no acepta el resumen y muestra el comando nuevamente. No se puede combinar con `-y`. No tiene efecto dentro de una sesión de Claude Code, así que ejecute el comando desde su propia terminal. Requiere Claude Code v2.1.271 o posterior | |
1303| `--json` | Imprime el resultado como un objeto JSON en la última línea de stdout, en el [mismo formato que `plugin install --json`](#plugin-json-result). Requiere Claude Code v2.1.268 o posterior | |
1304| `-h, --help` | Muestra la ayuda del comando | |
1305
1306<Note>
1307 Claude Code resuelve un nombre de plugin sin calificar contra sus plugins instalados. Cuando los plugins instalados desde diferentes marketplaces comparten el nombre, Claude Code rechaza la actualización y lista los comandos calificados `plugin-name@marketplace-name` a ejecutar en su lugar. Antes de v2.1.246, Claude Code aceptaba solo el formulario calificado y rechazaba un nombre sin calificar como no encontrado.
1308</Note>
1309
1310***
1311
1312<h3 id="plugin-list">
1313 plugin list
1314</h3>
1315
1316Lista los plugins instalados con su versión, marketplace de origen y estado de habilitación.
1317
1318```bash theme={null}
1319claude plugin list [options]
1320```
1321
1322El comando acepta estas opciones:
1323
1324| Opción | Descripción | Predeterminado |
1325| :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
1326| `--json` | Salida como JSON. Una fila de plugin con problemas de carga o advertencias de autoría lleva matrices de cadenas `errors` o `notes`. En Claude Code v2.1.268 o posterior, matrices paralelas `errorDetails` y `noteDetails` dan el `type` de diagnóstico de cada entrada y los nombres a los que se refiere, como el plugin, marketplace, servidor o archivo | |
1327| `--available` | Incluye plugins disponibles desde marketplaces. Requiere `--json` | |
1328| `-h, --help` | Muestra la ayuda del comando | |
1329
1330Dentro de una sesión interactiva, `/plugin list` imprime un listado similar en línea, pero solo cubre plugins instalados desde marketplace:
1331
1332* Los plugins cargados desde directorios de skills aparecen en la interfaz `/plugin` y en `claude plugin list`, pero no en la salida en línea de `/plugin list`.
1333* Los [plugins sincronizados desde claude.ai](#synced-plugins) aparecen en `claude plugin list` en Claude Code v2.1.239 o posterior y en la interfaz `/plugin`, pero no en la salida en línea de `/plugin list`.
1334* Los plugins cargados para la sesión con `--plugin-dir` o `--plugin-url` aparecen en la interfaz `/plugin`, y en `claude plugin list` solo cuando la misma bandera precede al subcomando, como en `claude --plugin-dir <dir> plugin list`. Solo el nombre de la bandera nombra su ubicación, así que un `claude plugin list` sin calificar no puede encontrarlos, a diferencia de los plugins sincronizados y los plugins del directorio de skills, cuyos directorios fijos escanea Claude Code.
1335
1336El formulario interactivo acepta `--enabled` o `--disabled` para mostrar solo los plugins en ese estado, y `ls` como abreviatura de `list`.
1337
1338<h3 id="plugin-details">
1339 plugin details
1340</h3>
1341
1342Muestra el inventario de componentes de un plugin y el costo de token proyectado. La salida lista todos los componentes que contribuye el plugin, agrupados como Skills, Agents, Hooks, servidores MCP y servidores LSP, junto con una estimación de cuántos tokens añade a cada sesión. El grupo Skills incluye entradas tanto de `skills/` como de `commands/`.
1343
1344```bash theme={null}
1345claude plugin details <name>
1346```
1347
1348El comando toma estos argumentos:
1349
1350* `<name>`: Nombre del plugin o `plugin-name@marketplace-name`
1351
1352El comando acepta estas opciones:
1353
1354| Opción | Descripción | Predeterminado |
1355| :----------- | :--------------------------- | :------------- |
1356| `-h, --help` | Muestra la ayuda del comando | |
1357
1358La salida muestra dos cifras de costo para cada componente:
1359
1360* **Siempre activo:** tokens añadidos a cada sesión por el texto de listado del plugin, como descripciones de skills, descripciones de agents y nombres de comandos, independientemente de si algún componente se activa.
1361* **Al invocar:** tokens que cuesta un componente cuando se activa. Se muestra por componente, no como total del plugin, porque una sesión típica invoca solo un subconjunto de componentes.
1362
1363Este ejemplo muestra cómo se ve la salida para un plugin con dos skills:
1364
1365```
1366dependency-guard 1.2.0
1367 Dependency analysis for Claude Code sessions
1368 Source: dependency-guard@example-marketplace
1369
1370Component inventory
1371 Skills (2) scan-dependencies, review-changes
1372 Agents (0)
1373 Hooks (1) SessionStart (harness-only — no model context cost)
1374 MCP servers (0)
1375 LSP servers (0)
1376
1377Projected token cost
1378 Always-on: ~180 tok added to every session
1379
1380Per-component (rounded)
1381 component always-on on-invoke
1382 scan-dependencies ~100 ~2400
1383 review-changes ~80 ~1800
1384
1385 On-invoke cost is paid each time a skill or agent fires.
1386 Token counts are estimates and may differ from actual usage.
1387```
1388
1389El total siempre activo se calcula a través de la API `count_tokens` para su modelo activo. Los números por componente se escalan proporcionalmente desde ese total. Si la API es inaccesible, el comando recurre a una estimación basada en caracteres.
1390
1391<h3 id="plugin-validate">
1392 plugin validate
1393</h3>
1394
1395Verifica un plugin o un marketplace para detectar errores de sintaxis y esquema antes de publicar.
1396
1397El comando sale con 0 cuando la validación pasa, 1 cuando falla, y 2 cuando la propia ejecución de validación falla, como cuando la ruta que pasa es ilegible.
1398
1399```bash theme={null}
1400claude plugin validate <path> [options]
1401```
1402
1403El comando toma estos argumentos:
1404
1405* `<path>`: Ruta a un directorio de plugin o un directorio de marketplace. Consulte [Validar un plugin o un directorio sin manifiesto](/docs/es/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) para saber qué archivos cubre una ejecución de plugin.
1406
1407El comando acepta estas opciones:
1408
1409| Opción | Descripción | Predeterminado |
1410| :----------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------- |
1411| `--strict` | Trata las advertencias como errores y sale con 1 en ellas. Use en CI para detectar problemas que el tiempo de ejecución tolera, como [campos no reconocidos](#unrecognized-fields) | |
1412| `--json` | Salida del informe de validación como un objeto JSON con los mismos códigos de salida. Requiere Claude Code v2.1.259 o posterior | |
1413| `-h, --help` | Muestra la ayuda del comando | |
1414
1415Con `--json`, Claude Code escribe el informe en stdout como un objeto JSON con estos campos de nivel superior:
1416
1417* `success`: el mismo veredicto que da el código de salida
1418* `strict`: si la ejecución trató las advertencias como errores
1419* `target`: la ruta resuelta que Claude Code validó
1420* `manifest`: el resultado del propio manifiesto, o `null` para una [ejecución sin manifiesto](/docs/es/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest)
1421* `contents`: resultados por archivo, cada uno nombrando su `file` y llevando matrices `errors`, `warnings` y `notes`
1422
1423En salida 2, el comando no escribe nada en stdout; el mensaje de error va a stderr.
1424
1425Dentro de una sesión interactiva, `/plugin validate <path>` ejecuta las mismas verificaciones en línea.
1426
1427<h3 id="plugin-eval">
1428 plugin eval
1429</h3>
1430
1431Ejecuta los [casos de eval](/docs/es/plugin-evals) de un plugin e informa resultados puntuados. Requiere Claude Code v2.1.269 o posterior. Cada caso es un prompt más calificadores; Claude Code lo ejecuta varias veces en una sesión aislada con solo el plugin de destino cargado, y por defecto también sin el plugin para que el informe muestre la diferencia. Consulte [Probar plugins con evals](/docs/es/plugin-evals) para el formato de caso, calificadores, resultados y uso en CI.
1432
1433```bash theme={null}
1434claude plugin eval [target] [options]
1435```
1436
1437El `target` opcional es un directorio de plugin, un archivo único `prompt.md` o `case.yaml`, un plugin instalado como `name` o `name@marketplace`, o `name@skills-dir`, y por defecto es el directorio actual. Colóquelo antes de `--tag`, `--allow-tools` y `--json`.
1438
1439Esta tabla lista las opciones que la mayoría de ejecuciones usan. Ejecute `claude plugin eval --help` para el conjunto completo, incluyendo `--case`, `--tag`, `--output-dir`, `--report`, `--allow-real-servers`, `--keep-temp` y `--verbose`.
1440
1441| Opción | Descripción | Predeterminado |
1442| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
1443| `--runs <n>` | Ejecuciones por caso por rama | El `runs` de cada caso, si no 3 |
1444| `-j, --concurrency <n>` | Sesiones de agent a ejecutar a la vez, 1 a 8. Comparten su límite de velocidad | `1` |
1445| `--model <model>` | Modelo para el agent bajo prueba | El `model` de cada caso, si no `ANTHROPIC_MODEL` si está establecido, si no el predeterminado de Claude Code |
1446| `--judge-model <model>` | Modelo para calificadores `llm` y `baseline` | Un modelo pequeño y rápido |
1447| `--ablation <mode>` | `none` o `with-without`. Consulte [Comparar contra una línea de base sin plugin](/docs/es/plugin-evals#compare-against-a-no-plugin-baseline) | `with-without` cuando un plugin se resuelve, si no `none` |
1448| `--threshold <0..1>` | Sale con 1 si algún caso puntúa por debajo de esto | `1.0` |
1449| `--max-cost-usd <usd>` | Detiene antes de la siguiente ejecución una vez que el gasto alcanza esto, sale con 2 e informa resultados parciales | Sin límite |
1450| `--allow-tools <tools...>` | Otorga herramientas más allá del conjunto de solo lectura, como `Bash`, `Write`, `Edit` o `"mcp__plugin_<plugin>_<server>__*"`. Consulte [Otorgar herramientas](/docs/es/plugin-evals#grant-tools) | |
1451| `--scaffold` | Ejecuta el [`scaffold_script`](/docs/es/plugin-evals#add-setup-or-history-with-case-yaml) de cada caso | Desactivado |
1452| `--trust-plugin` | Omite el primer mensaje de confianza, para CI. Consulte [Qué puede acceder una ejecución](/docs/es/plugin-evals#security) | Desactivado |
1453| `--mocks <mode>` | `record` u `off`. Consulte [Simular servidores MCP](/docs/es/plugin-evals#mock-mcp-servers) | `record` |
1454| `--eval-dir <dir>` | Directorio debajo del plugin que contiene los casos | El `experimental.evals` del manifiesto, si no `evals` |
1455| `--json [path]` | Imprime el [documento de resultado](/docs/es/plugin-evals#json-result) a stdout, o escríbelo en una ruta `.json` | |
1456| `--no-publish` | Mantiene el informe HTML local | |
1457| `-h, --help` | Muestra la ayuda del comando | |
1458
1459El comando sale con 0 cuando cada caso cumple el umbral, 1 en un caso fallido, un error de carga o un directorio de plugin no confiable, 2 en una ejecución parcial, 130 cuando se interrumpe y 143 cuando se termina. Consulte [Ejecutar evals en CI](/docs/es/plugin-evals#run-evals-in-ci).
1460
1461<h3 id="plugin-eval-init">
1462 plugin eval init
1463</h3>
1464
1465Crea un conjunto de eval para el plugin en el directorio actual. Requiere Claude Code v2.1.269 o posterior. En una terminal esto inicia una entrevista de autoría que lee el plugin, propone casos y calificadores, los prueba y escribe los archivos. Con `--bare`, o sin una terminal, escribe una plantilla de caso único en blanco en su lugar. Ejecutado desde dentro de una sesión interactiva de Claude Code, imprime las instrucciones de entrevista para que esa sesión siga en lugar de escribir una plantilla. Consulte [Crear su primer conjunto de eval](/docs/es/plugin-evals#create-your-first-eval-suite).
1466
1467```bash theme={null}
1468claude plugin eval init [name] [options]
1469```
1470
1471El `name` opcional es un nombre de caso: la entrevista no necesita uno, mientras que `--bare` y la ruta de plantilla sin terminal lo requieren. Acepta estas opciones:
1472
1473| Opción | Descripción | Predeterminado |
1474| :------------------ | :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------------- |
1475| `--bare` | Escribe un `prompt.md` en blanco y `graders/criteria.md` para `<name>` en lugar de ejecutar la entrevista | |
1476| `-i, --interactive` | Requiere la entrevista. Falla sin una terminal en lugar de escribir una plantilla | |
1477| `--eval-dir <dir>` | Directorio debajo del directorio actual para escribir casos en | El `experimental.evals` del manifiesto, si no `evals` |
1478| `-h, --help` | Muestra la ayuda del comando | |
1479
1480<h3 id="plugin-tag">
1481 plugin tag
1482</h3>
1483
1484Crea una etiqueta git de lanzamiento para un plugin. De forma predeterminada, el comando etiqueta el plugin en el directorio actual; pase una ruta para etiquetar un plugin en otro lugar. Consulte [Etiquetar lanzamientos de plugins](/docs/es/plugin-dependencies#tag-plugin-releases-for-version-resolution).
1485
1486```bash theme={null}
1487claude plugin tag [path] [options]
1488```
1489
1490El comando toma estos argumentos:
1491
1492* `[path]`: Ruta al directorio del plugin. Por defecto es el directorio actual.
1493
1494El comando acepta estas opciones:
1495
1496| Opción | Descripción | Predeterminado |
1497| :-------------------- | :----------------------------------------------------------------------------------- | :------------- |
1498| `--push` | Empuja la etiqueta al remoto después de crearla | |
1499| `--dry-run` | Imprime lo que se etiquetaría sin crear la etiqueta | |
1500| `-f, --force` | Crea la etiqueta incluso si el árbol de trabajo está sucio o la etiqueta ya existe | |
1501| `-m, --message <msg>` | Mensaje de anotación de etiqueta. Use `%s` como marcador de posición para la versión | |
1502| `--remote <name>` | Remoto al que empujar con `--push` | `origin` |
1503| `-h, --help` | Muestra la ayuda del comando | |
1504
1505***
1506
1507<h2 id="debugging-and-development-tools">
1508 Herramientas de depuración y desarrollo
1509</h2>
1510
1511<h3 id="debugging-commands">
1512 Comandos de depuración
1513</h3>
1514
1515Use `claude --debug` para ver detalles de carga de plugins:
1516
1517Esto muestra:
1518
1519* Qué plugins se están cargando
1520* Cualquier error en los manifiestos de plugins
1521* Registro de skills, agentes y hooks
1522* Inicialización del servidor MCP
1523
1524<h3 id="common-issues">
1525 Problemas comunes
1526</h3>
1527
1528| Problema | Causa | Solución |
1529| :---------------------------------- | :---------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1530| Plugin no se carga | `plugin.json` inválido | Ejecute `claude plugin validate ./my-plugin` o `/plugin validate ./my-plugin`, donde `./my-plugin` es su directorio de plugins, para verificar `plugin.json`, `hooks/hooks.json` y el frontmatter de los skills, agentes y comandos en los directorios predeterminados del plugin para errores de sintaxis y esquema. Consulte [Validar un plugin o un directorio sin un manifiesto](/docs/es/plugin-marketplaces#validate-a-plugin-or-a-directory-without-a-manifest) para ver qué cubre una ejecución |
1531| Skills no aparecen | Estructura de directorio incorrecta | Asegúrese de que `skills/` o `commands/` esté en la raíz del plugin, no dentro de `.claude-plugin/` |
1532| Hooks no se activan | Script no ejecutable | Ejecute `chmod +x script.sh` |
1533| El servidor MCP falla | Falta `${CLAUDE_PLUGIN_ROOT}` | Use la variable para todas las rutas de plugins |
1534| Errores de ruta | Se utilizaron rutas absolutas | Haga que las rutas sean relativas, comenzando con `./`; consulte [Reglas de comportamiento de rutas](#path-behavior-rules), que cubren la excepción `"."` del campo `skills` |
1535| LSP `Executable not found in $PATH` | Servidor de lenguaje no instalado | Instale el binario (por ejemplo, `npm install -g typescript-language-server typescript`) |
1536
1537<h3 id="example-error-messages">
1538 Ejemplos de mensajes de error
1539</h3>
1540
1541**Errores de validación de manifiestos**:
1542
1543* `Invalid JSON syntax: Unexpected token } in JSON at position 142`: verifique si hay comas faltantes, comas adicionales o cadenas sin comillas
1544* `Plugin <name> has an invalid manifest file at .claude-plugin/plugin.json. Validation errors: name: Invalid input: expected string, received undefined`: falta un campo requerido
1545* `Plugin <name> has a corrupt manifest file at .claude-plugin/plugin.json. JSON parse error: ...`: error de sintaxis JSON. Antes de v2.1.246, Claude Code también producía este error para un `plugin.json` guardado como UTF-8 con una marca de orden de bytes (BOM) inicial, incluso cuando el JSON era válido de otra manera.
1546
1547**Errores de carga de plugins**:
1548
1549* `Warning: No commands found in plugin my-plugin custom directory: ./cmds. Expected .md files or SKILL.md in subdirectories.`: la ruta del comando existe pero no contiene archivos de comando válidos
1550* `Plugin directory not found at path: ./plugins/my-plugin. Check that the marketplace entry has the correct path.`: la ruta `source` en marketplace.json apunta a un directorio inexistente
1551* `Plugin my-plugin has conflicting manifests: both plugin.json and marketplace entry specify components.`: elimine definiciones de componentes duplicadas o elimine `strict: false` en la entrada del marketplace
1552
1553<h3 id="hook-troubleshooting">
1554 Solución de problemas de hooks
1555</h3>
1556
1557**El script del hook no se ejecuta**:
1558
15591. Verifique que el script sea ejecutable: `chmod +x ./scripts/your-script.sh`
15602. Verifique la línea shebang: La primera línea debe ser `#!/bin/bash` o `#!/usr/bin/env bash`
15613. Verifique que la ruta use `${CLAUDE_PLUGIN_ROOT}`: `"command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/your-script.sh"`
15624. Pruebe el script manualmente: `./scripts/your-script.sh`
1563
1564**El hook no se activa en los eventos esperados**:
1565
15661. Verifique que el nombre del evento sea correcto (sensible a mayúsculas): `PostToolUse`, no `postToolUse`
15672. Verifique que el patrón del matcher coincida con sus herramientas: `"matcher": "Write|Edit"` para operaciones de archivo
15683. Confirme que el tipo de hook sea válido: `command`, `http`, `mcp_tool`, `prompt` o `agent`
1569
1570<h3 id="mcp-server-troubleshooting">
1571 Solución de problemas del servidor MCP
1572</h3>
1573
1574**El servidor no se inicia**:
1575
15761. Verifique que el comando exista y sea ejecutable
15772. Verifique que todas las rutas usen la variable `${CLAUDE_PLUGIN_ROOT}`
15783. Verifique los registros del servidor MCP: `claude --debug` muestra errores de inicialización
15794. Pruebe el servidor manualmente fuera de Claude Code
1580
1581**Las herramientas del servidor no aparecen**:
1582
15831. Asegúrese de que el servidor esté correctamente configurado en `.mcp.json` o `plugin.json`
15842. Verifique que el servidor implemente correctamente el protocolo MCP
15853. Verifique si hay tiempos de espera de conexión en la salida de depuración
1586
1587<h3 id="directory-structure-mistakes">
1588 Errores de estructura de directorio
1589</h3>
1590
1591**Síntomas**: El plugin se carga pero faltan componentes (skills, agentes, hooks).
1592
1593**Estructura correcta**: Los componentes deben estar en la raíz del plugin, no dentro de `.claude-plugin/`. Solo `plugin.json` pertenece a `.claude-plugin/`.
1594
1595**Lista de verificación de depuración**:
1596
15971. Ejecute `claude --debug` y busque mensajes "loading plugin"
15982. Verifique que cada directorio de componentes esté listado en la salida de depuración
15993. Verifique que los permisos de archivo permitan leer los archivos del plugin
1600
1601***
1602
1603<h2 id="distribution-and-versioning-reference">
1604 Referencia de distribución y versionado
1605</h2>
1606
1607<h3 id="version-management">
1608 Gestión de versiones
1609</h3>
1610
1611Claude Code utiliza la versión del plugin como clave de caché que determina si hay una actualización disponible. Cuando ejecuta `/plugin update` o se activa la actualización automática, Claude Code calcula la versión actual y omite la actualización si coincide con la que ya está instalada. Un plugin [cargado en su lugar](#plugin-caching-and-file-resolution) desde un marketplace de directorio local carga sus archivos de fuente actuales en cada inicio de sesión, sin importar lo que diga su cadena de versión.
1612
1613Para cada tipo de fuente excepto `command`, Claude Code resuelve la versión a partir de la primera de estas que esté establecida:
1614
16151. El campo `version` en el `plugin.json` del plugin
16162. El campo `version` en la entrada del plugin en el marketplace en `marketplace.json`
16173. El SHA del commit de git de la fuente del plugin, para fuentes `github`, `url`, `git-subdir` y relative-path en un marketplace alojado en git
16184. El resumen SHA-256, para [fuentes `archive`](/docs/es/plugin-marketplaces#zip-archives): el pin `sha256` en la entrada del marketplace, o el resumen del archivo descargado cuando no establece ningún pin. Claude Code lo acorta a los primeros 12 caracteres
16195. `unknown`, para fuentes `npm` o directorios locales cuando ni el directorio del plugin ni su marketplace es un repositorio de git. Claude Code no toma la versión de un repositorio que encierra la ruta de instalación, como un `~/.claude` gestionado por git
1620
1621Para una [fuente `command`](/docs/es/plugin-marketplaces#command-sources), Claude Code siempre deriva la versión de lo que produjo el comando: un hash de contenido de 12 caracteres por sí solo, o anexado a la versión `plugin.json` como `<version>-<hash>` cuando se establece uno. Claude Code ignora el campo `version` de la entrada del marketplace para fuentes de comando. Un comando cuya salida con hash cambia, por lo tanto, produce una nueva versión, incluso cuando la cadena de versión creada permanece igual. En [modo de enlace](/docs/es/plugin-marketplaces#copy-mode-and-link-mode), el hash cubre la ruta real del directorio impreso y sus entradas de nivel superior en lugar del contenido del archivo.
1622
1623Para esos tipos de fuente, esto le proporciona tres formas de versionar un plugin:
1624
1625| Enfoque | Cómo | Comportamiento de actualización | Mejor para |
1626| :--------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |
1627| **Versión explícita** | Establezca `"version": "2.1.0"` en `plugin.json` | Los usuarios obtienen actualizaciones solo cuando incrementa este campo. Insertar nuevos commits sin incrementarlo no tiene efecto, y `/plugin update` informa "already at the latest version". Para un plugin [cargado en su lugar](#plugin-caching-and-file-resolution), el nuevo contenido se carga de todas formas. | Plugins publicados con ciclos de lanzamiento estables |
1628| **Versión de SHA de commit** | Omita `version` tanto de `plugin.json` como de la entrada del marketplace | Los usuarios obtienen actualizaciones cada vez que cambia el commit resuelto de la fuente | Plugins internos o de equipo en desarrollo activo |
1629| **Versión de resumen** | Utilice una [fuente `archive`](/docs/es/plugin-marketplaces#zip-archives) y omita `version` tanto de `plugin.json` como de la entrada del marketplace | Con un pin `sha256`, los usuarios obtienen actualizaciones cuando cambia el pin. Sin uno, los usuarios obtienen actualizaciones cada vez que cambian los bytes del archivo zip alojado | Plugins publicados como archivos zip en un servidor estático o repositorio de artefactos |
1630
1631Si utiliza versiones explícitas, siga [versionado semántico](https://semver.org) (`MAJOR.MINOR.PATCH`): incremente MAJOR para cambios que rompan la compatibilidad, MINOR para nuevas características, PATCH para correcciones de errores. Documente los cambios en un `CHANGELOG.md`.
1632
1633***
1634
1635<h2 id="see-also">
1636 Ver también
1637</h2>
1638
1639* [Plugins](/docs/es/plugins) - Tutoriales y uso práctico
1640* [Marketplaces de plugins](/docs/es/plugin-marketplaces) - Crear y gestionar marketplaces
1641* [Skills](/docs/es/skills) - Detalles de desarrollo de skills
1642* [Subagents](/docs/es/sub-agents) - Configuración y capacidades del agent
1643* [Hooks](/docs/es/hooks) - Manejo de eventos y automatización
1644* [MCP](/docs/es/mcp) - Integración de herramientas externas
1645* [Configuración](/docs/es/settings) - Opciones de configuración para plugins
