Skills

Convierte instrucciones reutilizables en skills que tú o tus agentes podáis cargar cuando hagan falta.

Crea una skill del espacio de trabajo

Crea un directorio bajo .clarvis/skills con un archivo SKILL.md:

.clarvis/skills/release-notes/
├── SKILL.md
├── references/
│   └── style-guide.md
└── examples/
    └── release.md

Usa una cabecera YAML para el descubrimiento y Markdown para las instrucciones:

---
name: release-notes
description: Draft concise release notes from a Git commit range.
argument-hint: "<from>..<to>"
user-invocable: true
allowed-tools:
  - shell
  - grep
  - read_file
---

Draft release notes for `$ARGUMENTS`.

1. Read `references/style-guide.md` before writing.
2. Group user-visible changes by outcome.
3. Omit internal refactors unless they change behavior.
4. Match the tone and structure in `examples/release.md`.

Ejecútala desde el campo de mensaje:

/release-notes v0.0.0..HEAD

Cada marcador $ARGUMENTS o se sustituye por el texto que sigue al comando con barra. Si no hay marcador, Clarvis añade la tarea en una sección Target.

En /extensions, el paso 3 muestra cada skill independiente con su origen exacto user|workspace / agents|clarvis, junto a plugins instalados y de marketplaces. Intro añade o quita esa skill del borrador. Las skills de plugins no se seleccionan individualmente: seleccionar el plugin incluye todas a la vez. El paso 4 muestra las independientes y las de plugins en grupos separados antes de activar nada.

Paso 3 del perfil. Selecciona el origen exacto de una skill independiente o el plugin completo que la contiene.

Paso 4 del perfil. Las skills empaquetadas aparecen en la revisión del conjunto completo del plugin.

Elige dónde guardar la skill

builtin:default lee estas ubicaciones de menor a mayor prioridad:

1. ~/.agents/skills
2. <workspace>/.agents/skills
3. ~/.clarvis/skills
4. <workspace>/.clarvis/skills

Si coinciden los nombres, prevalece la de mayor prioridad. Clarvis lee .agents/skills para interoperar con el ecosistema, pero escribe su contenido en .clarvis.

Un perfil propio enumera ámbito, origen y nombre exactos de cada skill independiente. Los directorios no representados quedan inactivos. Un plugin seleccionado aporta todas sus skills como un conjunto. Las skills de plugins tienen menor prioridad que las independientes seleccionadas y conservan su nombre original, por lo que puedes sustituirlas deliberadamente por una independiente.

Controla la invocación y las herramientas

• user-invocable: true es el valor por defecto y muestra /<name> en el autocompletado.
• user-invocable: false oculta el comando, pero no impide la carga progresiva iniciada por el agente.
• allowed-tools es metadato de compatibilidad. Clarvis lo conserva y valida, pero actualmente no cambia permisos de ejecución; las herramientas efectivas dependen del agente.
• agent: reviewer ejecuta una skill invocada con barra en una ejecución propia de ese agente. Sin agent, se inserta en el turno actual. Para agentes de plugins, usa agent: quality-kit:reviewer.

allowed-tools también admite una cadena separada por comas y el alias tools. Es preferible la lista porque resulta más fácil de revisar.

Las skills de paquetes portátiles Agent Plugins v1 siguen el formato más estricto Agent Skills: allowed-tools es una cadena separada por espacios, el nombre debe coincidir con el directorio y usar minúsculas y guiones, y los metadatos opcionales portátiles inválidos hacen que se omita solo esa skill. Las independientes y las nativas mantienen las formas flexibles anteriores.

Añade metadatos y una dependencia MCP

El primer archivo .yaml o .yml del directorio agents/ de una skill contiene metadatos del anfitrión, no un recurso para el modelo. Puede ajustar la presentación, ocultarla del catálogo implícito y declarar dependencias MCP:

display-name: Documentation research
short-description: Search the connected documentation service.
dependencies:
  tools:
    - type: mcp
      value: docs
      description: Documentation search
      transport: http
      url: https://docs.example.com/mcp

Si la ejecución no incluye docs —o el servidor con espacio de nombres indicado por el archivo auxiliar—, Clarvis no presenta la skill en su catálogo para el modelo. La dependencia no instala, conecta ni concede el servidor. Los tipos de dependencia no admitidos se conservan como metadatos sin efecto.

Empaqueta recursos y scripts con seguridad

Un recurso de skill puede ocupar hasta 8 MiB y un snapshot de plugin hasta 32 MiB de recursos de skills. Las lecturas para el modelo se dividen en páginas de 256 KiB y 50.000 caracteres decodificados, con un cursor exacto de bytes para continuar textos grandes sin retener todo el archivo en memoria. Los binarios forman parte de la huella del perfil, pero no se decodifican como prompt.

Las skills empaquetadas seleccionadas pueden exponer su directorio exacto como raíz para ejecutar scripts auxiliares. Eso no ejecuta nada automáticamente: el agente debe llamar a shell o monitor_start, sigue aplicándose la revisión de comandos y el sandbox nativo monta el paquete en solo lectura. Sin sandbox nativo, el comando es un proceso normal del anfitrión con secretos filtrados; permitir una ruta no vuelve inmutables los scripts de terceros.

Mantén pequeña la primera carga

Clarvis descubre nombres y descripciones sin cargar todos los cuerpos. Guarda material detallado en references, scripts en scripts, recursos reutilizables en assets y ejemplos en examples. El agente solo puede cargarlos tras elegir la skill.

Las skills son instrucciones, no un sandbox

Una skill puede orientar al agente para usar sus herramientas. Revisa las instrucciones y los scripts antes de añadir una skill de terceros. No trates allowed-tools como una barrera de seguridad.

Consulta también

• Extension Profiles
• Plugins
• Hooks
• Referencia de extensiones
• Servidores MCP