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.

---

Colocar archivos

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

---

Entender el descubrimiento

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.

---

Escribe la introducción

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.

---

Validar nombres

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]+)*$

---

Siga las reglas de longitud

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

---

Usa un ejemplo

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

---
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.

---

Reconocer la descripción de la herramienta

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" })

---

Configurar permisos

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

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

Permiso	Comportamiento
allow	La habilidad se carga inmediatamente
deny	Habilidad oculta al agente, acceso rechazado
ask	Se solicita al usuario aprobación antes de cargar

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

---

Anulación por agente

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

Para agentes personalizados (en el frente del agente):

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

Para agentes integrados (en opencode.json):

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

---

Deshabilitar la herramienta de habilidades

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

Para agentes personalizados:

---
tools:
  skill: false
---

Para agentes integrados:

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

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

---

Solucionar problemas de carga

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