Construindo e Registrando Skills Personalizadas

Intermediário⏱45 min📖5 min de leituraLição 3 de 5

Construindo e Registrando Skills Personalizadas

Domine o sistema de skills: estrutura, manifestos, instruções, ferramentas, recursos, parâmetros, descoberta e registro.

Estrutura da Skill

Uma skill é um diretório contendo um arquivo de manifesto e recursos opcionais:

skills/
  minha-skill-personalizada/
    skill.yaml        # Manifesto (obrigatório)
    instructions.md   # Instruções estendidas (opcional)
    templates/        # Arquivos de recurso (opcional)
       scaffold.py
    references/       # Documentos de referência (opcional)
       api-guide.md

ℹ️Nota

Embora skill.yaml seja o formato convencional, o OpenCode também suporta manifestos JSON (skill.json). YAML é recomendado para legibilidade, especialmente para longos blocos de instruções. JSON é preferível quando você precisa gerar manifestos programaticamente ou validá-los com JSON Schema.

Ciclo de Vida de Carregamento de Skill

Entender como as skills são carregadas ajuda você a projetar skills eficientes que não desperdiçam janela de contexto.

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

💡Dica

Skills com descrições excessivamente amplas podem ser carregadas não intencionalmente, consumindo janela de contexto e tokens. Mantenha descrições específicas e focadas. Use matchPattern para controle preciso sobre quando uma skill ativa.

Manifesto da Skill

O manifesto define a identidade, propósito e componentes da skill.

yaml

# skill.yaml
name: minha-skill-personalizada
description: Guia o agente na realização de geração personalizada de scaffolds
author: Nuniversity
version: 1.0.0
instructions: |
  Quando o usuário pedir para gerar scaffold de um novo projeto Python:
  1. Use os arquivos de template no diretório `templates/`
  2. Pergunte ao usuário o nome do projeto e nome do pacote
  3. Gere a estrutura de diretórios com pyproject.toml, src/, tests/
  4. Inicialize um repositório git
tools:
  - bash
  - write
  - read
  - glob
resources:
  - templates/scaffold.py
  - references/api-guide.md

📌Importante

O campo instructions é a parte mais crítica de uma skill. Ele é injetado diretamente no contexto do agente. Mantenha as instruções concisas e acionáveis: cada token consumido pela skill é um token não disponível para a conversação. Busque no máximo 500-1000 palavras por skill.

Comparação: Formatos de Manifesto YAML vs JSON

Aspecto	YAML (`skill.yaml`)	JSON (`skill.json`)
Legibilidade	Excelente, natural para texto longo	Boa, familiar para devs JS/TS
Comentários	Suportados (`# comment`)	Não suportados
Multi-linha	Nativo (`	`e`>` block scalars)
Validação schema	Ferramentas limitadas	JSON Schema, muitos validadores
Melhor para	Skills escritas manualmente	Skills geradas ou validadas
Tamanho arquivo	Tipicamente menor	Ligeiramente maior (aspas, vírgulas)
Ferramentas	Linters YAML disponíveis	JSON nativo na maioria dos editores

Escrevendo Instruções de Skill

Instruções são o núcleo de uma skill. Elas guiam o agente passo a passo.

markdown

# instructions.md

## Objetivo
Gerar scaffold de um projeto Python pronto para produção.

## Passos
1. Pergunte ao usuário: nome do projeto, nome do pacote, versão Python
2. Crie diretório: `{nome_do_projeto}/`
3. Gere `pyproject.toml` com:
   - Metadados do projeto
   - Dependências (click, pytest, black)
   - Configuração do sistema de build
4. Crie `src/{nome_do_pacote}/__init__.py` com string de versão
5. Crie `tests/test_{nome_do_pacote}.py` com teste placeholder
6. Execute `git init` e `git add -A`

## Restrições
- Não sobrescreva arquivos existentes sem perguntar
- Use os padrões mais recentes de empacotamento Python (PEP 621)

bash

# Instruções podem referenciar scripts bundled como recursos
# Exemplo: executando o template de scaffold
python skills/minha-skill-personalizada/templates/scaffold.py \
  --project-name "$NOME_DO_PROJETO" \
  --package-name "$NOME_DO_PACOTE"

Ferramentas e Recursos de Skill

Skills podem declarar ferramentas necessárias e empacotar arquivos de recurso:

json

{
  "name": "db-migration-skill",
  "description": "Geração e gerenciamento de migrações de banco de dados",
  "version": "2.1.0",
  "instructions": "Ao gerenciar migrações de banco de dados...",
  "tools": ["bash", "read", "write", "grep"],
  "resources": [
    "templates/migration_template.sql",
    "templates/rollback_template.sql",
    "config/migration.config.json"
  ],
  "parameters": {
    "db_type": {
      "type": "string",
      "description": "Tipo de banco (postgres, mysql, sqlite)",
      "required": true
    },
    "migration_name": {
      "type": "string",
      "description": "Nome descritivo para a migração",
      "required": true
    }
  }
}

⚠️Aviso

Cada arquivo de recurso carregado no contexto consome tokens. Empacote apenas arquivos essenciais. Documentos de referência grandes devem ser vinculados em vez de incorporados. Um arquivo de referência de 100KB consome aproximadamente 25.000 tokens da janela de contexto.

Parâmetros de Skill

Parâmetros permitem que skills sejam configuráveis e reutilizáveis:

yaml

name: api-client-generator
description: Gera bibliotecas de cliente API a partir de especificações OpenAPI
version: 1.0.0
instructions: |
  Gere um cliente API baseado na especificação OpenAPI fornecida.
  Use o parâmetro language para determinar o formato de saída.
parameters:
  language:
    type: string
    description: "Linguagem alvo (python, typescript, go)"
    required: true
    default: python
  spec_path:
    type: string
    description: "Caminho para o arquivo de especificação OpenAPI"
    required: true
  output_dir:
    type: string
    description: "Diretório de saída para o cliente gerado"
    required: false
    default: "./generated"

💡Dica

Use required: false com um valor default sensato para parâmetros que têm padrões óbvios. Isso reduz o atrito ao usar a skill enquanto ainda permite personalização. Parâmetros são passados quando a skill é invocada através de instruções do agente.

Fluxo de Execução da Skill

💡 Tip: Use Ctrl + Mouse Wheel to zoom, or click the fullscreen icon

Registrando Skills no Config

Skills devem ser registradas no opencode.json para serem descobertas:

json

{
  "skills": {
    "scaffold-python": {
      "manifest": "skills/scaffold-python/skill.yaml"
    },
    "db-migration": {
      "manifest": "skills/db-migration/skill.json"
    },
    "api-client-gen": {
      "manifest": "skills/api-client-generator/skill.yaml"
    }
  }
}

typescript

// Skills podem ser registradas programaticamente
import { OpenCode } from "opencode";

const opencode = new OpenCode();

opencode.registerSkill({
  name: "react-component",
  manifest: "skills/react-component/skill.yaml",
  autoLoad: true,
  matchPattern: "react component|jsx|tsx"
});

await opencode.run();

Descoberta de Skills

O OpenCode descobre skills através de registro e correspondência de padrões. Quando uma consulta do usuário corresponde à descrição de uma skill, a skill é carregada automaticamente.

⚠️Aviso

Skills com descrições excessivamente amplas podem ser carregadas não intencionalmente, consumindo janela de contexto e tokens. Mantenha descrições específicas e focadas. Uma skill descrita como "ajuda com desenvolvimento" corresponderá a quase todas as requisições.

json

{
  "skills": {
    "react-component": {
      "manifest": "skills/react-component/skill.yaml",
      "autoLoad": true,
      "matchPattern": "react component|jsx|tsx component|react hook"
    }
  }
}

💡Dica

O campo autoLoad combinado com matchPattern dá a você controle preciso. Sem autoLoad, a skill só é carregada quando explicitamente solicitada. Isso é útil para skills de nicho que não devem ativar em toda consulta vagamente relacionada. Use autoLoad: false para skills raramente usadas para economizar contexto.

Comparação: Campos do Manifesto de Skill

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Identificador único da skill
`description`	string	Sim	Descrição curta para correspondência
`version`	string	Sim	Versão semântica (ex.: `1.0.0`)
`instructions`	string	Sim	Guia passo a passo para o agente
`tools`	string[]	Não	Lista de ferramentas necessárias
`resources`	string[]	Não	Caminhos de arquivos relativos ao diretório
`parameters`	object	Não	Parâmetros configuráveis com defaults
`author`	string	Não	Nome do criador para atribuição
`matchPattern`	string	Não	Padrão regex para ativação automática
`autoLoad`	boolean	Não	Se a skill ativa na correspondência

ℹ️Nota

Uma skill pode ter tanto instructions inline no manifesto quanto um arquivo externo instructions.md. Se ambos existirem, o arquivo externo tem precedência. Use instruções inline para skills curtas e arquivos externos para procedimentos complexos de múltiplos passos.