Agent Skills: Guia de Parâmetros · Parte 1

description: o match semântico

A description é o critério de matching semântico. No startup, o Claude carrega só name + description de cada skill. Quando você dá um comando, ele lê as descriptions disponíveis e decide qual ativar.

Sem uma description precisa, a skill não existe para o Claude.

Como escrever uma description que funciona:

# ❌ Genérica demais: nunca ativa
description: Helps with documentation
 
# ✅ Precisa: ativa no contexto certo
description: >
  Writes API documentation in OpenAPI 3.1 format.
  Use when you need to document REST endpoints,
  generate schema specs, or update endpoint descriptions.

Duas perguntas que toda description deve responder:

1. O que essa skill faz?
2. Quando usar essa skill?

Inclua frases-gatilho: os mesmos termos que você digita no chat. São eles que fazem o match acontecer.

Teste antes de publicar: se você digita "documenta essa rota" e a description só diz "Helps with documentation", o match não acontece. O par name + description é o único contato do Claude com a skill antes de ativar. O que não estiver ali fica fora do matching.

allowed-tools: o que o Claude pode fazer

Lista as tools que o Claude pode usar sem precisar da sua confirmação enquanto a skill está ativa.

Se omitir, valem suas permissões normais: edits e comandos pedem aprovação, leituras não. É uma lista de pré-aprovação, não uma trava: o que não está nela continua disponível, só volta a pedir confirmação.

# Skill exploratória: Claude navega mas nunca edita
allowed-tools: Read, Grep, Glob
 
# Skill de deploy: escopo restrito a git
allowed-tools:
  - Read
  - Write
  - Bash(git:*)
 
# Skill de auditoria ampla
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash

Scoping de Bash: use Bash(git:*) ou Bash(npm:*) para um comando inteiro. Dá pra ir mais fino: Bash(git push:*) libera só git push, Bash(git log:*) só consulta de histórico. Pra bloquear uma tool (não só deixar de pré-aprovar), use disallowed-tools na skill, ou deny/hooks no settings.

⚠️ CLI vs SDK: allowed-tools só funciona no CLI. No Agent SDK, o controle é via allowedTools na config da query. Skills portadas do CLI para SDK precisam replicar as restrições manualmente.

O que não está na lista ainda executa, só volta a pedir confirmação. Um allowed-tools: Read, Grep, Glob não impede o Claude de rodar rm ou curl: ele pede aprovação antes de executar. Pra bloquear de fato, use disallowed-tools na skill ou deny nas configurações.

model: override de modelo

Sobrescreve o modelo Claude que a skill usa. Você escolhe entre capacidade, velocidade e custo.

# Recomendado: herda da sessão, preserva cache de prompt
model: inherit
 
# Rápido e barato: ~1/5 do custo de sonnet
model: haiku
 
# Raciocínio padrão: code review, refatoração
model: sonnet
 
# Capacidade máxima: auditoria de segurança, arquitetura
model: opus

Bom senso: use inherit como padrão. Modelo diferente quebra o cache de prompt: cada vez que a skill roda, o cache precisa ser reconstruído. Só troque se a skill realmente exigir mais capacidade. Ex: use haiku pra uma skill de formatação que roda dezenas de vezes por sessão (economia de tokens), e sonnet pra skill de auditoria que roda uma vez.

effort: nível de raciocínio

Controla o nível de raciocínio que a skill usa. Mais effort = mais tokens gastos pensando antes de responder.

effort: low    # formata JSON, traduz texto, renomeia variáveis
effort: medium # code review padrão, geração de testes, refatoração leve
effort: high   # auditoria de segurança, decisões de arquitetura (padrão)
effort: xhigh  # análise profunda de dependências, revisão contratual
effort: max    # auditoria completa, refatoração estrutural crítica

Se omitir o campo, a skill herda o nível da sessão.

ultrathink é uma palavra-chave que você digita no prompt para forçar raciocínio extra naquele turno. Não configura no frontmatter.

Frontmatter completo (exemplo)

name: api-docs
description: >
  Writes API documentation in OpenAPI 3.1 format.
  Use when documenting REST endpoints or generating schema specs.
allowed-tools: Read, Grep, Glob
model: inherit
effort: medium

Bônus: localização das skills

Prioridade em conflito de nome: Enterprise > Personal > Project.

@developer.israel · Agent Skills · Parte 1 de 2