Skills de Agente

Los skills de agente permiten a OpenCode descubrir instrucciones reutilizables desde tu repositorio o directorio home. Los skills se cargan bajo demanda a través de la herramienta nativa skill - los agentes ven los skills disponibles y pueden cargar el contenido completo cuando lo necesiten.

Ubicar Archivos

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

• Configuración del proyecto: .opencode/skills/<name>/SKILL.md
• Configuración global: ~/.config/opencode/skills/<name>/SKILL.md
• Proyecto compatible con Claude: .claude/skills/<name>/SKILL.md
• Global compatible con Claude: ~/.claude/skills/<name>/SKILL.md
• Proyecto compatible con agent: .agents/skills/<name>/SKILL.md
• Global compatible con agent: ~/.agents/skills/<name>/SKILL.md

Entender el Descubrimiento

Para rutas locales del proyecto, OpenCode recorre hacia arriba desde tu directorio de trabajo actual hasta llegar al worktree de git. Carga cualquier skills/*/SKILL.md coincidente en .opencode/ y cualquier .claude/skills/*/SKILL.md o .agents/skills/*/SKILL.md coincidente en el camino.

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

Escribir Frontmatter

Cada SKILL.md debe comenzar con frontmatter YAML. Solo se reconocen estos campos:

• name (requerido)
• description (requerido)
• license (opcional)
• compatibility (opcional)
• metadata (opcional, mapa de string a string)

Los campos de frontmatter desconocidos se ignoran.

Validar Nombres

name debe:

• Tener 1-64 caracteres
• Ser alfanumérico en minúsculas con separadores de guion simple
• No comenzar ni terminar con -
• No contener -- consecutivos
• Coincidir con el nombre del directorio que contiene SKILL.md

Regex equivalente:

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

Seguir Reglas de Longitud

description debe tener 1-1024 caracteres. Mantenlo lo suficientemente específico para que el agente elija correctamente.

Usar 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 Descripción de Herramienta

OpenCode lista los skills disponibles en la descripción de la herramienta skill. Cada entrada incluye el nombre del skill y la descripción:

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

El agente carga un skill llamando a la herramienta:

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

Configurar Permisos

Controla qué skills pueden acceder los agentes usando permisos basados en patrones en opencode.json:

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

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

Sobrescribir Por Agente

Da a agentes específicos 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"
        }
      }
    }
  }
}

Deshabilitar la Herramienta Skill

Deshabilita completamente los skills para agentes que no deberían usarlos:

Para agentes personalizados:

---
tools:
  skill: false
---

Para agentes integrados:

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

Cuando está deshabilitado, la sección <available_skills> se omite completamente.

Solucionar Problemas de Carga

Si un skill no aparece:

• Verifica que SKILL.md esté en mayúsculas
• Comprueba que el frontmatter incluya name y description
• Asegúrate de que los nombres de skills sean únicos en todas las ubicaciones
• Revisa los permisos - los skills con deny están ocultos de los agentes