Plugins

Añade agentes, skills, herramientas y automatizaciones en un solo plugin.

Gestiona plugins en la 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.

Abre. Empieza en /extensions y elige Plugins and Marketplace.

Revisa el paquete. Una vista reúne todas las aportaciones antes de activar.

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.

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

Un plugin convencional puede ser tan pequeño como este:

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:

{
  "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 .<host>-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

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:

{
  "$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

Un manifiesto de otro anfitrión puede declarar un ajuste de texto del usuario y asignarlo a un valor completo del entorno stdio:

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

Clarvis añade un espacio de nombres a las aportaciones que deben ser únicas:

• agentes: <plugin>:<agent>;
• servidores MCP: <plugin>:<server>; herramientas: <plugin>:<server>.<tool>;
• 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/<name> o ~/.clarvis/plugins/<name>; los del espacio, en .agents/plugins/<name> o .clarvis/plugins/<name>. 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

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.

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

• Extension Profiles
• Marketplaces
• Hooks
• Skills
• Servidores MCP
• Referencia de extensiones