Habilidades de agente

Las habilidades de agente permiten que OpenCode descubra instrucciones reutilizables desde tu repositorio o directorio personal. Las habilidades se cargan bajo demanda a traves de la herramienta nativa skill — los agentes ven las habilidades disponibles y pueden cargar el contenido completo cuando sea necesario.

---

Colocar archivos

Crea una carpeta por nombre de habilidad y coloca un SKILL.md dentro. OpenCode busca en estas ubicaciones:

• Configuracion del proyecto: .opencode/skill/<name>/SKILL.md
• Configuracion global: ~/.config/opencode/skill/<name>/SKILL.md
• Compatible con Claude del proyecto: .claude/skills/<name>/SKILL.md
• Compatible con Claude global: ~/.claude/skills/<name>/SKILL.md

---

Entender el descubrimiento

Para rutas locales del proyecto, OpenCode camina hacia arriba desde tu directorio de trabajo actual hasta que alcanza el arbol de trabajo git. Carga cualquier skill/*/SKILL.md coincidente en .opencode/ y cualquier .claude/skills/*/SKILL.md coincidente en el camino.

Las definiciones globales tambien se cargan desde ~/.config/opencode/skill/*/SKILL.md y ~/.claude/skills/*/SKILL.md.

---

Escribir frontmatter

Cada SKILL.md debe comenzar con YAML frontmatter. Solo estos campos son reconocidos:

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

Los campos de frontmatter desconocidos se ignoran.

---

Validar nombres

name debe:

• Tener 1–64 caracteres
• Ser alfanumerico en minusculas con separadores de guion unico
• No comenzar o terminar con -
• No contener -- consecutivos
• Coincidir con el nombre del directorio que contiene SKILL.md

Expresion regular equivalente:

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

---

Seguir reglas de longitud

description debe tener 1-1024 caracteres. Mantelo lo suficientemente especifico para que el agente pueda elegir correctamente.

---

Usar un ejemplo

Crea .opencode/skill/git-release/SKILL.md asi:

---
name: git-release
description: Crear versiones consistentes y changelogs
license: MIT
compatibility: opencode
metadata:
  audience: mantenedores
  workflow: github
---

## Lo que hago

- Redactar notas de version a partir de PRs fusionados
- Proponer un incremento de version
- Proporcionar un comando `gh release create` copiable

## Cuando usarme

Usa esto cuando estes preparando una version etiquetada.
Haz preguntas de aclaracion si el esquema de versionamiento objetivo no esta claro.

---

Reconocer descripcion de herramienta

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

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Crear versiones consistentes y changelogs</description>
  </skill>
</available_skills>

El agente carga una habilidad llamando a la herramienta:

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

---

Configurar permisos

Controla a que habilidades pueden acceder los agentes usando permisos basados en patrones en opencode.json:

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

Permission	Comportamiento
allow	La habilidad se carga inmediatamente
deny	Habilidad oculta del agente, acceso rechazado
ask	Se solicita aprobacion del usuario antes de cargar

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

---

Anular por agente

Da a agentes especificos permisos diferentes a los valores predeterminados globales.

Para agentes personalizados (en el frontmatter del agente):

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

Para agentes integrados (en opencode.json):

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

---

Desactivar la herramienta skill

Desactiva completamente las habilidades para agentes que no deberian usarlas:

Para agentes personalizados:

---
tools:
  skill: false
---

Para agentes integrados:

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

Cuando se desactiva, la seccion <available_skills> se omite por completo.

---

Solucionar problemas de carga

Si una habilidad no aparece:

1. Verifica que SKILL.md este escrito en mayusculas
2. Verifica que el frontmatter incluya name y description
3. Asegurate de que los nombres de habilidades sean unicos en todas las ubicaciones
4. Verifica los permisos — las habilidades con deny estan ocultas para los agentes