# Plugins {#plugins} > Añade agentes, skills, herramientas y automatizaciones en un solo plugin. ## Gestiona plugins en la TUI {#manage-plugins-in-the-tui} Escribe `/extensions` y pulsa `m` para abrir el navegador unificado de Plugins. - Izquierda y derecha alternan entre **All**, **Installed**, cada marketplace, **Workspace** y **Add Marketplace**. - Arriba y abajo recorren la colección. `/` busca e Intro abre los detalles desplazables. - Antes de modificar nada, los detalles muestran identidad exacta, estado en el perfil, revisión, agentes, skills, MCP, hooks, servicios, comandos y notas del origen. - Pulsa Intro de nuevo en una entrada disponible para instalar y activar. Usa `g` para una URL Git directa, `u` para revisar y actualizar un plugin global instalado o `d` para desinstalar. - Pulsa `e` en un plugin instalado para configurar su pertenencia al perfil mediante el editor de Extension Profiles.
Inicio de Extensions con el editor guiado y las rutas a perfiles, plugins y MCP
Abre. Empieza en /extensions y elige Plugins and Marketplace.
Detalles del plugin con datos del editor y recuentos de agentes, skills, servidores MCP y hooks
Revisa el paquete. Una vista reúne todas las aportaciones antes de activar.
Detalles con agente, skill, servidor MCP, hook activo y comandos ejecutables exactos
Revisa lo ejecutable. Examina los comandos MCP y hooks como parte del mismo conjunto.
La instalación Git directa pregunta si la copia irá a `.agents/plugins` —convención compartida de Agent Plugins— o a `.clarvis/plugins` —inventario nativo—. Las entradas de marketplaces se instalan en `.agents/plugins`. En ambos casos, instalar supone consentir el plugin completo y añade esa instalación exacta al perfil actual. No hay una segunda pantalla de aprobación del plugin o sus hooks. Las instalaciones globales pertenecen al operador y no necesitan otra aprobación del espacio al seleccionarlas. En cambio, tras mostrar la primera pantalla ligera, Clarvis calcula la huella de todo el inventario de plugins del repositorio, incluidos los no seleccionados. Una aprobación cubre ese inventario exacto para todos los perfiles. Cualquier cambio en bytes o permisos de ejecución incluidos en la huella la invalida. En un perfil mixto, los plugins globales aprobados siguen activos y los locales sin aprobar quedan retenidos. El pie muestra la operación y el tiempo transcurrido durante instalaciones, actualizaciones, eliminaciones y reconexiones. Espera a que termine antes de cambiar otra opción. `u` actualiza una instalación Git global gestionada al HEAD actual de su origen. `d` desinstala un plugin global. Si está seleccionado, Clarvis recompone el backend; al desinstalarlo, el perfil queda visiblemente degradado hasta quitar su referencia o reinstalarlo. Clarvis bloquea actualizar o eliminar un plugin seleccionado durante una ejecución para no modificar su copia fija. El kernel impide iniciar otra ejecución mientras se modifica. Si un cliente cambia el plugin sin realizar la reconexión de la TUI, el kernel desactualizado rechaza nuevas ejecuciones hasta `/reconnect`. Los plugins del espacio forman parte del repositorio: elimínalos allí. Un enlace simbólico a una copia externa sigue visible y se puede activar, pero Clarvis no ofrece ni realiza actualizaciones gestionadas sobre ese destino. ::: warning El plugin se activa como un conjunto Sus agentes, skills, MCP, hooks y servicios entran y salen juntos. Si cambia el contenido instalado, Clarvis espera a un punto de reposo y pide revisión antes de incorporarlo; una ejecución en curso no cambia por debajo. La copia fija incluye los bytes y permisos de ejecución de los archivos locales de procesos MCP, hooks y capacidades referenciados directamente, no solo sus declaraciones. ::: ## Crea un plugin {#create-a-plugin} Un plugin convencional puede ser tan pequeño como este: ```text quality-kit/ ├── plugin.json ├── agents/ │ └── reviewer.md ├── skills/ │ └── quality-check/ │ └── SKILL.md └── hooks/ └── hooks.json ``` Coloca `plugin.json` en la raíz. Los nombres usan minúsculas, números, guiones bajos y guiones. Una instalación Git utiliza el campo `name` como directorio. En una estructura multiherramienta ya instalada, el directorio define el espacio de nombres; si falta el nombre en el manifiesto, Clarvis puede deducirlo: ```json { "name": "quality-kit", "version": "0.0.1", "description": "Review-oriented agents, skills, and checks.", "author": { "name": "Acme Engineering" }, "mcpServers": { "checks": { "type": "stdio", "command": "quality-kit-mcp", "args": ["--stdio"], "resources": false } }, "hooks": [ { "event": "pre_finalize", "command": "bun run lint", "timeout_ms": 60000, "on_failure": "deny" } ], "bootstrapSkill": "quality-check", "capabilityRunPolicies": { "plans": { "skills": { "quality-check": "review" } } } } ``` El único campo nativo obligatorio es `name`. Si existe `version`, debe ser una cadena no vacía. Puedes declarar hooks dentro del manifiesto; si no los declara, Clarvis busca `hooks/hooks.json`. Las rutas relativas del manifiesto deben permanecer dentro del plugin. Clarvis admite un `plugin.json` en la raíz y manifiestos bajo directorios `.-plugin/plugin.json`. Un manifiesto raíz que declare el esquema portátil Agent Plugins tiene prioridad. Si no existe, prevalece `.clarvis-plugin/plugin.json`. Sin ninguno de ellos, se elige el único manifiesto legible que declare el conjunto más amplio de aportaciones admitidas. Nunca se fusionan dos manifiestos de anfitriones distintos. Declara `skills` como un directorio relativo o una lista. Cada ubicación puede ser una colección o un directorio con `SKILL.md`. Clarvis conserva hasta cuatro raíces de exploración efectivas. Una lista completa de directorios hermanos puede representarse por su padre sin hacer visibles hermanos no declarados. Declara MCP directamente, indica un documento auxiliar en `mcpServers` o, si omites la clave, usa `.mcp.json` o `mcp.json`. ## Usa paquetes Agent Plugin y Codex directamente {#use-agent-plugin-and-codex-packages-directly} Clarvis reconoce Agent Plugins v1 sin conversión. Un `plugin.json` raíz con su esquema canónico tiene prioridad, usa los componentes fijos `skills/` y `mcp.json` y aplica las reglas de Agent Skills: ```json { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "quality-kit", "version": "preview" } ``` Cada hijo directo de `skills/` debe contener exactamente `SKILL.md`. Los nombres portátiles usan segmentos alfanuméricos en minúsculas separados por un solo guion, tienen hasta 64 caracteres y coinciden con el directorio. Se validan `license`, `compatibility`, `metadata` con valores de texto y `allowed-tools` separado por espacios. El `mcp.json` raíz puede declarar `stdio`, `streamable-http` o `sse`. Los servidores stdio reciben `PLUGIN_ROOT` y `PLUGIN_DATA`, gestionados por el cliente; esos marcadores se expanden una vez en argumentos, entorno y directorio de trabajo. Los datos persistentes se guardan en el estado de Clarvis, no en la instalación, y sobreviven a una actualización. Un documento MCP inválido desactiva solo MCP. Cada servidor inválido, incluidos los que exceden límites de Clarvis tras normalizarse, se descarta por separado; no elimina otros componentes válidos. Los paquetes de estilo Codex también se cargan directamente: `.codex-plugin/plugin.json`, `.mcp.json`, `agents/` y `skills/` no necesitan reempaquetarse. Las rutas como `../skills` se resuelven desde `.codex-plugin/` sin salir del paquete. Su `.mcp.json` puede ser un mapa directo o contener `mcpServers` o `mcp_servers`. Un servidor con `url` sin transporte explícito usa HTTP; `http_headers` se adapta a `headers`, y los campos OAuth camelCase admitidos pasan a snake_case. Los MCP de Agent Plugins portátiles expanden solo `PLUGIN_ROOT` y `PLUGIN_DATA` antes de desactivar la expansión general; las referencias explícitas a credenciales siguen resolviéndose por la vía normal de Clarvis. ### Adapta un valor userConfig de otro anfitrión {#map-a-borrowed-host-userconfig-value-safely} Un manifiesto de otro anfitrión puede declarar un ajuste de texto del usuario y asignarlo a un valor completo del entorno stdio: ```json { "userConfig": { "apiKey": { "type": "string" } }, "mcpServers": { "service": { "command": "service-mcp", "env": { "SERVICE_TOKEN": "${user_config.apiKey}" } } } } ``` Clarvis lo convierte exactamente en `${SERVICE_TOKEN}` y obtiene el valor del entorno del operador; no importa valores por defecto ni marcadores de secreto del manifiesto. Las referencias incrustadas, argumentos de comandos, cabeceras, ajustes no declarados o no textuales y servidores con `expandVariables: false` hacen que se retenga solo ese servidor MCP. El resto sigue disponible. Los documentos de hooks compatibles, organizados por eventos, pueden estar bajo `hooks`, referenciados por ruta o en `hooks/hooks.json`. Clarvis adapta nombres de eventos, patrones de herramientas, marcadores de raíz, tiempos y veredictos al contrato nativo. Lo que no puede adaptar aparece en las notas, sin ampliar silenciosamente un patrón. Si un comando adaptado comienza por un ejecutable relativo como `./hooks/session-start.cmd`, se fija a la raíz del plugin instalado. Su directorio de trabajo sigue siendo el espacio de trabajo. Los hooks reciben `PLUGIN_ROOT`, `PLUGIN_DATA` y los alias `CODEX_PLUGIN_ROOT` y `CODEX_PLUGIN_DATA`. Se conservan los comandos Windows, ejecución asíncrona, texto de estado, límites de salida y llamadas `mcp_tool` admitidos. Los hooks de tipo prompt o agente no admitidos se notifican y omiten, sin ejecutarlos con más autoridad. `bootstrapSkill` nombra una skill del plugin cuyo cuerpo debe estar disponible antes de que responda el modelo. La política de plan `review` solicita revisión del plan de esa skill cuando ella y el proveedor de Plans seleccionado proceden de este plugin. ## Entiende los nombres e identidades exactas {#understand-names-and-exact-identities} Clarvis añade un espacio de nombres a las aportaciones que deben ser únicas: - agentes: `:`; - servidores MCP: `:`; herramientas: `:.`; - skills: conservan su nombre y siguen la prioridad habitual. El ejemplo aporta el MCP `quality-kit:checks`. Un agente `reviewer.md` se referencia como `quality-kit:reviewer`. Activar el plugin ofrece todas las herramientas anunciadas por ese servidor a todos los agentes efectivos de nuevas ejecuciones, sin editar los perfiles guardados. Si los ajustes globales o del espacio sustituyen ese MCP exacto, prevalece la declaración del operador y solo se ofrece a perfiles que seleccionen sus herramientas; no hereda la concesión automática del plugin. Los plugins globales pueden estar en `~/.agents/plugins/` o `~/.clarvis/plugins/`; los del espacio, en `.agents/plugins/` o `.clarvis/plugins/`. Los cuatro inventarios se pueden descubrir y activar con o sin perfil propio. Toda referencia es exacta: `{ scope, source, name }`, con `source` igual a `agents` o `clarvis`. Una instalación del mismo nombre no sustituye ni oculta otra. Seleccionar dos a la vez es inválido porque comparten espacio de nombres. Una entrada puede ser un directorio o un enlace simbólico a un plugin compartido. Todas sus rutas se confinan al paquete resuelto. Las copias externas enlazadas solo se descubren; debes actualizarlas en su repositorio de origen. Los ajustes globales y del espacio siempre prevalecen sobre las aportaciones del plugin. Los detalles conservan autor o editor original, licencia, web, repositorio, enlaces legales, palabras clave, descripciones de capacidades y prompts, categoría, colores y recursos visuales limitados. Solo son metadatos de presentación: no conceden herramientas, inician procesos ni eluden la confianza. La huella de recursos de skills admite hasta 8 MiB por archivo y 32 MiB por plugin. El límite para ejecutar auxiliares es el directorio de la skill, no toda la colección o el plugin. Su dependencia MCP opcional debe nombrar un servidor realmente disponible en el perfil activo. ## Qué acepta Clarvis {#know-what-clarvis-accepts} `settings.json` es estricto: una clave desconocida de nivel superior es un error. `plugin.json` es deliberadamente flexible para no rechazar paquetes multiherramienta solo por sus metadatos ajenos. Clarvis informa de las claves desconocidas, pero no actúa sobre ellas. Una clave mal escrita puede dejar una aportación inactiva aunque cargue el plugin; revisa las notas. ::: warning Activa solo código en el que confíes Los plugins pueden aportar MCP ejecutables, agentes con permisos propios, servicios y hooks que se ejecutan con tus privilegios. Instalar desde Plugins supone consentir todo ese conjunto. Los plugins del repositorio requieren además revisar su huella exacta antes de incorporar contenido modificado. ::: ## Consulta también {#see-also} - [Extension Profiles](/es-ES/guide/extension-profiles) - [Marketplaces](/es-ES/guide/marketplaces) - [Hooks](/es-ES/guide/hooks) - [Skills](/es-ES/guide/skills) - [Servidores MCP](/es-ES/guide/mcp-servers) - [Referencia de extensiones](/es-ES/reference/extensions) --- [HTML canónico](https://clarvis.dev/es-ES/guide/plugins) [Índice de documentación](https://clarvis.dev/es-ES/llms.txt)