Agentes

Elige un agente integrado, sustituye su system prompt o crea uno propio para una tarea concreta.

Un perfil de agente define su forma de trabajar: system prompt, modelo, herramientas, permisos, límites y capacidad de delegar. Puedes sustituir por completo el system prompt de cualquier agente integrado, incluido Marshall, el principal por defecto.

Usa /agent para elegir el agente principal de la siguiente tarea. Usa un Extension Profile para elegir las extensiones instaladas que tendrá disponibles.

Elige entre los agentes integrados

Clarvis incluye cinco agentes listos para usar, sin generar archivos.

Agente	Uso principal
marshall	Programación general: investiga, implementa y delega trabajo acotado cuando resulta útil.
admiral	Ejecutar flujos reutilizables y coordinar ejecuciones independientes de agentes principales.
coder	Una implementación acotada; pensado principalmente como subagente.
explorer	Investigación de solo lectura con pruebas concretas.
planner	Desglosar trabajo, dependencias, riesgos y criterios de finalización, sin escribir.

Abre /agent para cambiar el agente activo. Intro cambia solo la sesión actual. Pulsa S en el selector para guardar el agente como valor global o del espacio de trabajo. El valor del espacio tiene prioridad sobre el global.

Crea un agente

El editor integrado crea el archivo a partir de una plantilla de solo lectura:

1. Abre /settings/agents.
2. Pulsa Ctrl+T y elige ámbito global o del espacio.
3. Pulsa A, escribe un nombre como reviewer y pulsa Intro.
4. Abre el agente y revisa descripción, permisos, herramientas, modelo, límite de iteraciones, política de creación de subagentes e instrucciones.
5. Pulsa Ctrl+S después de cambiar un campo.
6. Si lo has creado en el espacio, aprueba la nueva configuración ejecutable con /workspace-trust.
7. Abre /agent, selecciona reviewer y pulsa Intro para usarlo en la sesión. Pulsa S solo si debe ser el valor persistente por defecto.

Pasos 1 y 2. Abre el editor y elige el ámbito del archivo.

Paso 3. Usa un nombre estable en minúsculas. El editor parte de una plantilla de solo lectura.

Pasos 4 y 5. Revisa todos los campos y concede solo los permisos necesarios.

Paso 6. El agente no estará disponible hasta aprobar su huella exacta.

Paso 7. Usa reviewer en la sesión o guárdalo explícitamente como valor por defecto.

La plantilla inicial puede leer el espacio, pero no editarlo ni ejecutar comandos. Añade permisos solo si el trabajo los necesita.

Crea el archivo manualmente

Las definiciones son archivos Markdown cuyo nombre identifica al agente. No existe un agent.md genérico. Para crear manualmente un agente reviewer del espacio:

mkdir -p .clarvis/agents
$EDITOR .clarvis/agents/reviewer.md

Guarda esta definición completa en .clarvis/agents/reviewer.md:

---
description: Reviews changes without modifying the workspace.
tools: []
grants:
  - read_workspace
  - use_skills
iteration_limit: 12
---

You are a read-only reviewer. Inspect the requested surface, verify claims against current source,
and report findings in severity order with precise file references. Do not edit files or run
mutating commands.

Aprueba el archivo con /workspace-trust y selecciónalo en /agent. Como agente principal, hereda el modelo por defecto configurado. Un model: provider/model declarado tiene prioridad cuando actúa como subagente; para el principal prevalece el modelo elegido por el usuario.

Campos habituales:

Campo	Significado
description	Finalidad que aparece en el selector.
model	Modelo opcional del subagente; para el principal prevalece el valor del usuario.
tools	Herramientas MCP con nombre separado por punto, como project.search.
grants	Capacidades integradas: acceso a archivos, comandos, skills o flujos.
can_spawn	Agentes que puede iniciar este agente principal.
default_spawn	Subagente por defecto; también debe figurar en can_spawn.
iteration_limit	Punto de revisión flexible del principal en escalate; en otro caso, límite estricto por agente.
reasoning_effort	off, minimal, low, medium, high, xhigh o max.
budget	Política opcional de presupuesto de ejecución.

El cuerpo Markdown después del cierre --- es el system prompt. Los campos anteriores, llamados frontmatter, definen permisos y otras opciones.

Las herramientas nativas proceden de los permisos:

Permiso	Capacidad
read_workspace	Inspección de solo lectura del espacio.
edit_workspace	Modificar archivos y leerlos.
run_commands	Ejecutar comandos, editar y leer.
ask_user	Pedir información al operador; solo tiene sentido en el agente de entrada.
use_skills	Descubrir y cargar skills.
workflow	Gestionar flujos desde un agente de entrada.

tools enumera herramientas MCP con el formato server.tool. No concede acceso a archivos ni al intérprete de comandos.

Atención

Los permisos proceden de grants y de las herramientas seleccionadas, no del texto del prompt. Concede solo el acceso necesario.

Sustituye un agente integrado

Sustituye todo el system prompt

Crea un archivo con el nombre del agente integrado. Por ejemplo, guarda esto como .clarvis/agents/marshall.md para sustituir el system prompt de Marshall en un proyecto:

---
description: A coding agent for this project's maintenance work.
---

You maintain this project. Read its contribution guide before making changes.
Keep fixes small, use the existing code style, and run the checks for the affected code.
Explain what changed, how you checked it, and anything that remains unresolved.
Ask before publishing a release or changing production infrastructure.

Aprueba el archivo con /workspace-trust. Su cuerpo Markdown sustituye todo el prompt integrado: no se añade al final. El mismo método sirve para Admiral, Coder, Explorer y Planner. Usa ~/.clarvis/agents/<name>.md para aplicar la sustitución a distintos proyectos.

El ejemplo cambia el prompt y mantiene los permisos integrados y los campos omitidos. Los permisos siguen dependiendo de grants y tools. Clarvis también añade el contexto necesario para la tarea actual: sustituir el prompt no elimina el resto del contexto de ejecución.

Cambia ajustes sin sustituir el prompt integrado

Un archivo con nombre integrado modifica solo los campos que contiene. El nombre del archivo determina el agente. Puedes crearlo desde /settings/agents o en el directorio agents/ global o del espacio. Estos son ejemplos mínimos completos para cada agente:

.clarvis/agents/marshall.md:

---
iteration_limit: 60
compaction:
  prompt: |
    Preserve accepted decisions, current implementation state, failed approaches, unresolved risks,
    and the exact next action. Keep concrete file paths and validation results.
---

.clarvis/agents/admiral.md:

---
iteration_limit: 60
---

.clarvis/agents/coder.md:

---
iteration_limit: 40
---

.clarvis/agents/explorer.md:

---
iteration_limit: 40
---

.clarvis/agents/planner.md:

---
iteration_limit: 40
---

Los campos omitidos conservan sus valores integrados. Una lista vacía elimina la lista heredada. Deja vacío el cuerpo Markdown para conservar el system prompt integrado. Un cuerpo no vacío o base_prompt sustituye el prompt completo.

Un archivo aprobado del espacio tiene prioridad sobre uno global del mismo nombre. Clarvis usa solo el archivo seleccionado para modificar los campos integrados. Los campos avanzados budget, compaction, retry y call_timeout_ms requieren actualmente edición manual. En llamadas en streaming, call_timeout_ms mide inactividad y se reinicia con progreso de texto, razonamiento o entrada de herramientas; antes del primer progreso observable, es un límite absoluto.

Las claves desconocidas se conservan por compatibilidad futura, pero no cambian el comportamiento. Comprueba la escritura de los campos: /doctor detecta valores inválidos, pero una clave mal escrita puede no tener efecto.

Asigna un presupuesto propio a un agente de entrada

Usa un presupuesto de perfil si este agente necesita límites distintos de los generales:

---
description: Reviews one bounded change without modifying the workspace.
grants:
  - read_workspace
iteration_limit: 20
budget:
  on_exceed: stop
  total_token_limit: 100000
  timeout_ms: 300000
---

Review the requested change and report findings with precise evidence. Do not modify files.

Se aplica cuando el perfil es el agente de entrada y sustituye por completo el presupuesto general. Para un subagente, iteration_limit sigue siendo un límite estricto.

Sustituye el prompt de compactación

La opción admitida es compaction.prompt dentro de la definición del agente, como en el ejemplo de Marshall. No existe un archivo independiente compaction-prompt.md ni un prompt de compactación general en settings.json.

Primero se resuelve el agente efectivo: archivo aprobado del espacio, archivo global del mismo nombre o definición integrada, en ese orden. Su compaction.prompt no vacío sustituye el prompt de resumen de ese agente. Si falta, sigue activo el integrado. Clarvis añade en cualquier caso el objetivo actual del principal o la tarea del subagente a la petición de compactación.

Para desactivar el resumen mediante LLM y usar descarte mecánico en un agente:

---
compaction:
  prompt_mode: none
---

prompt_mode: none no puede combinarse con compaction.prompt.

Si una sustitución tiene un formato inválido, Clarvis mantiene intacto el agente integrado e informa del archivo rechazado en /doctor. Un agente propio nuevo inválido no tiene alternativa integrada y queda indisponible.

Elige ámbito global o del espacio de trabajo

Usa ~/.clarvis/agents/<name>.md para un agente disponible en cualquier proyecto, o <workspace>/.clarvis/agents/<name>.md para una definición específica. Si existe, $CLARVIS_HOME sustituye a ~/.clarvis. Tras aprobarse, la definición del espacio prevalece sobre la global del mismo nombre.

También puedes gestionarlas en /settings/agents. Un agente integrado puede restablecerse o copiarse con otro nombre; no se puede eliminar ni renombrar directamente.

Consulta también

• Flujos de trabajo
• Ámbitos y confianza
• Configuración
• Skills