Skills de Agente

Skills de agente permitem que OpenCode descubra instruções reutilizáveis do seu repositório ou diretório home. Skills são carregados sob demanda através da ferramenta nativa skill - agentes veem skills disponíveis e podem carregar o conteúdo completo quando necessário.

Posicionar Arquivos

Crie uma pasta por nome de skill e coloque um SKILL.md dentro. OpenCode busca nestas localizações:

• Configuração do projeto: .opencode/skills/<name>/SKILL.md
• Configuração global: ~/.config/opencode/skills/<name>/SKILL.md
• Projeto compatível com Claude: .claude/skills/<name>/SKILL.md
• Global compatível com Claude: ~/.claude/skills/<name>/SKILL.md
• Projeto compatível com agent: .agents/skills/<name>/SKILL.md
• Global compatível com agent: ~/.agents/skills/<name>/SKILL.md

Entender a Descoberta

Para caminhos locais do projeto, OpenCode percorre para cima do seu diretório de trabalho atual até chegar ao worktree do git. Ele carrega qualquer skills/*/SKILL.md correspondente em .opencode/ e qualquer .claude/skills/*/SKILL.md ou .agents/skills/*/SKILL.md correspondente no caminho.

Definições globais também são carregadas de ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md e ~/.agents/skills/*/SKILL.md.

Escrever Frontmatter

Cada SKILL.md deve começar com frontmatter YAML. Apenas estes campos são reconhecidos:

• name (obrigatório)
• description (obrigatório)
• license (opcional)
• compatibility (opcional)
• metadata (opcional, mapa de string para string)

Campos de frontmatter desconhecidos são ignorados.

Validar Nomes

name deve:

• Ter 1-64 caracteres
• Ser alfanumérico em minúsculas com separadores de hífen simples
• Não começar ou terminar com -
• Não conter -- consecutivos
• Corresponder ao nome do diretório que contém SKILL.md

Regex equivalente:

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

Seguir Regras de Comprimento

description deve ter 1-1024 caracteres. Mantenha específico o suficiente para o agente escolher corretamente.

Usar um Exemplo

Crie .opencode/skills/git-release/SKILL.md assim:

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

Reconhecer Descrição da Ferramenta

OpenCode lista skills disponíveis na descrição da ferramenta skill. Cada entrada inclui o nome do skill e descrição:

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

O agente carrega um skill chamando a ferramenta:

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

Configurar Permissões

Controle quais skills os agentes podem acessar usando permissões baseadas em padrões em opencode.json:

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

Padrões suportam curingas: internal-* corresponde a internal-docs, internal-tools, etc.

Sobrescrever Por Agente

Dê a agentes específicos permissões diferentes dos padrões globais.

Para agentes personalizados (no frontmatter do agente):

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

Para agentes integrados (em opencode.json):

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

Desabilitar a Ferramenta Skill

Desabilite completamente skills para agentes que não devem usá-los:

Para agentes personalizados:

---
tools:
  skill: false
---

Para agentes integrados:

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

Quando desabilitado, a seção <available_skills> é omitida completamente.

Solucionar Problemas de Carregamento

Se um skill não aparecer:

• Verifique se SKILL.md está em maiúsculas
• Confirme que o frontmatter inclui name e description
• Garanta que nomes de skills sejam únicos em todas as localizações
• Verifique permissões - skills com deny estão ocultos dos agentes