Saltar al contenido
Docs de V1
Colocar archivos

Habilidades del agente

Las habilidades del agente permiten a OpenCode descubrir instrucciones reutilizables de su repositorio o directorio de inicio. Las habilidades se cargan bajo demanda a través de la herramienta nativa skill: los agentes ven las habilidades disponibles y pueden cargar el contenido completo cuando sea necesario.


Cree una carpeta por nombre de habilidad y coloque un SKILL.md dentro de ella. OpenCode busca estas ubicaciones:

  • Configuración del proyecto: .opencode/skills/<name>/SKILL.md
  • Configuración global: ~/.config/opencode/skills/<name>/SKILL.md
  • Compatible con Proyecto Claude: .claude/skills/<name>/SKILL.md
  • Compatible con Claude global: ~/.claude/skills/<name>/SKILL.md
  • Compatible con agente de proyecto: .agents/skills/<name>/SKILL.md
  • Compatible con agentes globales: ~/.agents/skills/<name>/SKILL.md

Para las rutas locales del proyecto, OpenCode sube desde su directorio de trabajo actual hasta llegar al árbol de trabajo de git. Carga cualquier skills/*/SKILL.md coincidente en .opencode/ y cualquier .claude/skills/*/SKILL.md o .agents/skills/*/SKILL.md coincidente a lo largo del camino.

Las definiciones globales también se cargan desde ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md y ~/.agents/skills/*/SKILL.md.


Cada SKILL.md debe comenzar con el frontmatter de YAML. Sólo se reconocen estos campos:

  • name (obligatorio)
  • description (obligatorio)
  • license (opcional)
  • compatibility (opcional)
  • metadata (opcional, mapa de cadena a cadena)

Los campos desconocidos se ignoran.


name debe:

  • Tener entre 1 y 64 caracteres.
  • Ser alfanuméricos en minúsculas con separadores de guión simple
  • No comienza ni termina con -
  • No contener -- consecutivos
  • Coincide con el nombre del directorio que contiene SKILL.md

expresión regular equivalente:

^[a-z0-9]+(-[a-z0-9]+)*$

description debe tener entre 1 y 1024 caracteres. Manténgalo lo suficientemente específico para que el agente elija correctamente.


Crea .opencode/skills/git-release/SKILL.md así:

Markdown
---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

OpenCode enumera las habilidades disponibles en la descripción de la herramienta skill. Cada entrada incluye el nombre y la descripción de la habilidad:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

El agente carga una habilidad llamando a la herramienta:

skill({ name: "git-release" })

Controle a qué agentes de habilidades pueden acceder utilizando permisos basados ​​en patrones en opencode.json:

JSON
{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
PermisoComportamiento
allowLa habilidad se carga inmediatamente
denyHabilidad oculta al agente, acceso rechazado
askSe solicita al usuario aprobación antes de cargar

Los patrones admiten comodines: internal-* coincide con internal-docs, internal-tools, etc.


Otorgue a agentes específicos permisos diferentes a los predeterminados globales.

Para agentes personalizados (en el frente del agente):

YAML
---
permission:
  skill:
    "documents-*": "allow"
---

Para agentes integrados (en opencode.json):

JSON
{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

Deshabilite completamente las habilidades para los agentes que no deberían usarlas:

Para agentes personalizados:

YAML
---
tools:
  skill: false
---

Para agentes integrados:

JSON
{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Cuando está deshabilitada, la sección <available_skills> se omite por completo.


Si una habilidad no aparece:

  1. Verifique que SKILL.md esté escrito en mayúsculas.
  2. Verifique que el frontmatter incluya name y description
  3. Asegúrese de que los nombres de las habilidades sean únicos en todas las ubicaciones
  4. Verifique los permisos: las habilidades con deny están ocultas para los agentes