Agent Skills: Guia de Contexto e Ecossistema · Parte 2

Invocation control: quem chama a skill

Por padrão, tanto você quanto o Claude podem ativar a skill. Dois parâmetros no frontmatter mudam isso. Dá pra combinar os dois para desativar completamente a skill (só ativável por outra skill).

# Padrão: ambos podem chamar
# (usuário ✅ · Claude ✅)
 
# Só o usuário chama: ideal para deploy, commit, side effects
disable-model-invocation: true
# (usuário ✅ · Claude ❌)
 
# Só o Claude ativa por contexto: útil para conhecimento de fundo
user-invocable: false
# (usuário ❌ · Claude ✅)
 
# Ambos bloqueados: skill desativada, só ativa por outra skill
disable-model-invocation: true
user-invocable: false
# (usuário ❌ · Claude ❌)

Use disable-model-invocation para skills com side effects. Você não quer o Claude fazendo deploy porque seu código parece pronto.

Subagentes + skills: pré-carregamento no contexto

No chat principal, só name + description de cada skill entra no startup. Quando o Claude cria um subagente via Agent tool e passa skills no setup, o SKILL.md inteiro é carregado no contexto de startup do subagente.

# Skill de deploy: bloquear pré-carregamento em subagentes
name: deploy-prod
disable-model-invocation: true  # não entra em subagente
user-invocable: true            # só você ativa

Pré-carregamento:

• O corpo completo da skill vai pro startup do subagente. O chat só carrega o resumo.
• Skills com user-invocable: false ficam ocultas no chat, mas continuam disponíveis no subagente se pré-carregadas.

⚠️ Risco: side effects. Sem disable-model-invocation: true, um subagente que decide que o código está pronto vai acionar o deploy sozinho.

Progressive disclosure: 3 níveis de carga

Skills seguem loading em camadas. Nada entra no contexto sem necessidade.

Nível 1: SEMPRE em contexto:
  metadata (name + description de cada skill, carregado no startup)
 
Nível 2: NO TRIGGER:
  SKILL.md completo (mantenha abaixo de 500 linhas)
 
Nível 3: SOB DEMANDA:
  references/, scripts/, assets/ (Claude lê ou executa só se precisar)

Dica: SKILL.md vira índice. Conteúdo detalhado vai em arquivos separados. O script roda e só o output consome tokens.

Orçamento de descrições

O conjunto de descriptions de todas as skills cabe em ~1% do context window. Cada description é cortada em 1.536 caracteres. Exemplo prático: com uma janela de 200K tokens, o orçamento de descriptions é ~2K tokens. Se estourar, as descriptions das skills menos usadas são encurtadas primeiro. Coloque o caso de uso principal logo no começo: é a primeira coisa que o Claude lê na varredura de matching.

Ecossistema: onde as skills vivem

Plugins têm namespace próprio, nunca conflitam com skills locais.

Subagentes e skills: um subagente pode ter skills pré-carregadas. O corpo inteiro entra no startup dele. disable-model-invocation: true impede uma skill de ser pré-carregada em subagentes.

Troubleshooting: skill não funciona?

Frontmatter completo (exemplo)

name: security-audit
description: >
  Audits project dependencies and git history for vulnerabilities.
  Use before release or when reviewing third-party contributions.
allowed-tools:
  - Read
  - Grep
  - Bash(git:*)
  - Bash(npm:*)
model: inherit
effort: high
disable-model-invocation: true

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