Melhores Práticas de Uso do Agent Skills

O Que Você Poderá Fazer Após Este Curso

Após completar esta lição, você será capaz de:

✅ Selecionar com precisão palavras-chave de acivação, deixando a IA acivar habilidades no momento certo
✅ Otimizar gerenciamento de contexto, reduzindo consumo de Tokens e melhorando velocidade de resposta
✅ Tratar cenários de colaboração multi-habilidades, evitando conflitos e confusões
✅ Dominar padrões de uso comuns, melhorando eficiência de trabalho

Seu Desafio Atual

Você pode ter encontrado estes cenários:

✗ Ao inserir "deploy my app", a IA não ativou a habilidade Vercel Deploy
✗ Uma única tarefa acivou múltiplas habilidades, a IA não sabe qual usar
✗ Habilidades ocupam muito contexto, fazendo a IA "esquecer" suas necessidades
✗ Cada vez você precisa explicar a tarefa novamente, não sabe como fazer a IA lembrar seus hábitos

Quando Usar Esta Abordagem

Quando você usar o Agent Skills encontrar:

🎯 Acivação imprecisa: Habilidade não foi ativada ou habilidade incorreta foi ativada
💾 Pressão de Contexto: Habilidades ocupam muitos Tokens, afetando outras conversas
🔄 Conflito de Habilidades: Múltiplas habilidades ativadas simultaneamente, a IA executa de forma confusa
⚡ Declínio de Desempenho: Resposta da IA fica mais lenta, precisa otimizar método de uso

Ideia Central

Filosofia de Design do Agent Skills:

O Agent Skills usa um mecanismo de carregamento sob demanda — o Claude ao iniciar apenas carrega o nome e a descrição das habilidades (aproximadamente 1-2 linhas), quando detecta palavras-chave relevantes, então lê o conteúdo completo do SKILL.md. Este design pode minimizar ao máximo o consumo de contexto, mantendo acivação precisa de habilidades.

Três Dimensões Chave de Eficiência de Uso:

Precisão de Acivação: Escolha palavras-chave de acivação apropriadas, deixe habilidades ativarem no momento certo
Eficiência de Contexto: Controle o comprimento do conteúdo de habilidades, evite ocupar muitos Tokens
Clareza de Colaboração: Defina limites claros de habilidades, evite conflitos de múltiplas habilidades

Melhor Prática 1: Escolher Precisamente Palavras-Chave de Acivação

O que são Palavras-Chave de Acivação?

Palavras-chave de acivação são definidas no campo description do SKILL.md, usadas para informar à IA quando essa habilidade deve ser ativada.

Princípio Chave: A descrição deve ser específica, a acivação deve ser clara

Como Escrever Descrições Eficazes?

❌ Exemplo Incorreto: Descrição Muito Vaga

yaml

---
name: my-deploy-tool
description: A deployment tool for applications  # Muito vaga, não consegue acivar
---

Problemas:

Sem cenário de uso claro
Não contém palavras que usuários podem dizer
A IA não consegue julgar quando acivar

✅ Exemplo Correto: Descrição Específica com Palavras-Chave

yaml

---
name: vercel-deploy
description: Deploy applications and websites to Vercel. Use this skill when user requests deployment actions such as "Deploy my app", "Deploy this to production", "Create a preview deployment", "Deploy and give me link", or "Push this live". No authentication required.
---

Vantagens:

Cenários claros de uso (Deploy applications)
Lista frases de acivação específicas ("Deploy my app", "Deploy this to production")
Explica valor único (No authentication required)

Guia de Escolha de Palavras-Chave

Cenário de Escrita	Palavras-Chave Recomendadas	Evitar Usar
Operação de Deploy	"deploy", "production", "push", "publish"	"send", "move"
Auditoria de Código	"review", "check", "audit", "optimize"	"look at", "see"
Auditoria de Design	"accessibility", "a11y", "UX check", "design audit"	"design", "style"
Otimização de Desempenho	"optimize", "performance", "improve speed"	"faster", "better"

Armadilhas: Erros Comuns

Evite Estes Erros

❌ Apenas Palavras Genéricas

yaml

description: A tool for code review  # "code review" muito genérico

✅ Cenário Específico + Palavras-Chave

yaml

description: Review React components for performance issues. Use when user says "review performance", "check optimization", or "find bottlenecks".

❌ Muitas Poucas Palavras-Chave

yaml

description: Deploy to Vercel  # Apenas um cenário

✅ Cobertura de Múltiplas Expressões

yaml

description: Deploy to Vercel. Use when user says "deploy", "push live", "create preview", or "publish".

Melhor Prática 2: Técnicas de Gerenciamento de Contexto

Por que o Gerenciamento de Contexto é Importante?

Tokens são recursos limitados. Se o arquivo SKILL.md for muito longo, ocupará muito contexto, fazendo a IA "esquecer" suas necessidades ou resposta ficar mais lenta.

Princípio Fundamental: Mantenha SKILL.md Breve

Regra de Ouro

Mantenha o arquivo SKILL.md abaixo de 500 linhas

Segundo a documentação oficial, estas estratégias podem minimizar o uso de contexto:

Estratégia	Descrição	Efeito
Mantenha SKILL.md conciso	Coloque materiais de referência detalhados em arquivos separados	Reduz carregamento inicial
Escreva descrições específicas	Ajuda a IA a julgar com precisão quando acivar	Evita ativação incorreta
Divulgação Progressiva	Apenas lê arquivos de suporte quando necessário	Controla consumo real de Tokens
Priorize Execução de Scripts	A saída do script não consome contexto, apenas o resultado de saída consome	Reduza significativamente uso de Tokens
Referência de Arquivo Única	Aponte de SKILL.md diretamente para arquivos de suporte	Evite aninhamento de múltiplos níveis

Como Fazer Divulgação Progressiva?

Cenário: Sua habilidade precisa documentação de API, exemplos de configuração e outros materiais de referência detalhados.

❌ Maneira Incorreta: Escrever Tudo em SKILL.md

markdown

---
name: my-api-skill
---

# API Skill

## API Reference

(Aqui estão escritos 2000 linhas de documentação de API)

## Configuration Examples

(Aqui estão escritos outras 500 linhas de exemplos)

## Usage Guide

(200 linhas de instruções de uso)

Problemas:

Arquivo excede 500 linhas
Todo o conteúdo é carregado a cada ativação
A maior parte do conteúdo pode nunca ser usada

✅ Maneira Correta: Separar em Arquivos de Suporte

markdown

---
name: my-api-skill
description: Integrate with My API. Use when user says "call API", "send request", or "fetch data".
---

# API Skill

Quick start guide for My API integration.

## Quick Setup

1. Get API key from https://api.example.com/keys
2. Add to environment: `export MY_API_KEY="your-key"`
3. Run: `bash scripts/api-client.sh`

## Common Operations

### Fetch user data
```bash
bash scripts/api-client.sh get /users/123

Create new resource

bash

bash scripts/api-client.sh post /users '{"name":"John"}'

Reference Documentation

For complete API reference, see:


**Vantagens**:
- `SKILL.md` tem apenas 30 linhas
- A IA apenas lê documentação detalhada quando necessário
- A maior parte do consumo de Tokens vem da saída do script, não do carregamento de documentação

### Exemplo Prático: Vercel Deploy vs React Best Practices

| Habilidade           | Linhas SKILL.md | Conteúdo Carregado       | Estratégia de Otimização            |
|--- | --- | --- | ---|
| Vercel Deploy        | ~60 linhas       | Uso breve + formato de saída | Scripts tratam lógica complexa        |
| React Best Practices | ~300 linhas      | Índice de regras + classificação  | Regras detalhadas em AGENTS.md      |
| Web Design Guidelines | ~50 linhas       | Fluxo de auditoria         | Busca regras dinamicamente do GitHub |

**Inspiração**: Não encha tudo no `SKILL.md`, deixe-o ser "guia de entrada", não "manual completo".

---

## Melhor Prática 3: Cenários de Colaboração Multi-Habilidades

### Cenário 1: Habilidade A e Habilidade B Têm Condições de Acivação Sobrepostas

**Problema**: Ao dizer "review my code", simultaneamente ativou React Best Practices e Web Design Guidelines.

#### ✅ Solução: Distinguir Claramente Palavras-Chave de Acivação

```yaml
# React Best Practices
name: react-performance
description: Review React components for performance issues. Use when user says "review performance", "optimize React", "check bottlenecks".

# Web Design Guidelines
name: web-design-audit
description: Audit UI for accessibility and UX issues. Use when user says "check accessibility", "review UX", "audit interface".

Resultado:

"review performance" → Apenas ativa habilidade React
"check accessibility" → Apenas ativa habilidade Web
"review my code" → Ambas não são ativadas, deixando a IA julgar

Cenário 2: Precisa Usar Simultaneamente Múltiplas Habilidades

Melhor Prática: Diga explicitamente à IA quais habilidades precisar

Recomendado Forma de Conversação:

Eu preciso completar duas tarefas:
1. Deploy no Vercel (usar habilidade vercel-deploy)
2. Verificar problemas de desempenho do React (usar habilidade react-best-practices)

Razões:

Define limites claros de habilidades, evitando confusão da IA
Deixa a IA executar em ordem, evitando conflitos de recursos
Melhora eficiência de execução

Cenário 3: Chamada em Cadeia de Habilidades (Saída de uma é Entrada de Outra)

Exemplo: Otimizar desempenho antes do deploy

bash

# Passo 1: Otimizar código usando React Best Practices
"Review src/components/Header.tsx for performance issues using react-best-practices skill"

# Passo 2: Deploy usando Vercel Deploy
"Deploy código otimizado para Vercel"

Melhores Práticas:

Defina ordem de passos claramente
Confirme conclusão de cada passo
Evite processamento paralelo de tarefas com dependências

Melhor Prática 4: Sugestões de Otimização de Desempenho

1. Simplifique o Contexto da Conversa

Problema: Após conversa longa, o contexto fica muito longo, resposta fica mais lenta.

✅ Solução: Inicie Nova Conversa ou Use "Clear Context"

bash

# Claude Code
/clear  # Limpa contexto, mantém habilidades

2. Evite Carregamento Repetitivo de Habilidades

Problema: Mesma tarefa aciva habilidade múltiplas vezes, desperdiçando Tokens.

❌ Maneira Incorreta

Usuário: Deploy my app
IA: (carrega vercel-deploy, executa)
Usuário: Deploy to production
IA: (carrega novamente vercel-deploy, executa)

✅ Maneira Correta

Usuário: Deploy to production
IA: (carrega vercel-deploy uma vez, executa)

3. Use Scripts em Vez de Código Inline

Comparação: Para completar a mesma tarefa, qual consome menos?

Maneira	Consumo de Tokens	Cenário Recomendado
Código inline (escrever lógica em SKILL.md)	Alto (carregado a cada ativação)	Tarefas simples (<10 linhas)
Script Bash	Baixo (apenas carrega caminho do script, não carrega conteúdo)	Tarefas complexas (>10 linhas)

Exemplo:

markdown

## ❌ Inline (não recomendado)

```bash
# Este código é carregado ao contexto a cada ativação
tar -czf package.tar.gz \
  --exclude='node_modules' \
  --exclude='.git' \
  --exclude='dist' \
  && curl -X POST $API_URL \
  -F "[email protected]"

✅ Script (recomendado)

bash

bash scripts/deploy.sh

(O conteúdo do script está no arquivo, não é carregado para o contexto)


### 4. Monitore Uso de Tokens

**Comandos Úteis do Claude Code**:

```bash
# Ver uso atual de Tokens
/token

# Ver carregamento de habilidades
/skills

Padrões de Uso Comuns e Exemplos

Padrão 1: Fluxo de Trabalho de Iteração Rápida

bash

# 1. Escrever código
vim src/App.tsx

# 2. Imediatamente auditar desempenho
"Review this for performance issues"

# 3. Modificar código com base nas sugestões
(modificar)

# 4. Auditar novamente
"Review again"

# 5. Deploy
"Deploy to production"

Pontos Chave:

Use instruções curtas, pois a IA já sabe o contexto
Repetir instruções pode rapidamente acivar a mesma habilidade

Padrão 2: Lista de Verificação para Início de Novo Projeto

bash

# Criar projeto Next.js
npx create-next-app@latest my-app

# Instalar Agent Skills
npx add-skill vercel-labs/agent-skills

# Auditoria inicial
"Check accessibility for all UI files"
"Review performance for all components"

# Deploy de teste
"Deploy to production"

Padrão 3: Modelo de Colaboração de Equipe

bash

# Clonar projeto da equipe
git clone team-project
cd team-project

1. "Review performance for all new changes"
2. "Check accessibility of modified files"
3. "Deploy to staging"

Padrão da Equipe: Defina palavras-chave de acivação unificadas, deixando todos os membros usar o mesmo padrão de eficiência.

Armadilhas: Erros Comuns

Armadilha 1: Habilidade Ativada Mas Sem Efeito

Sintoma: Ao dizer "Deploy my app", a IA diz "usará habilidade vercel-deploy", mas nada acontece.

Causas:

Caminho do script de habilidade está incorreto
Script não tem permissão de execução
Arquivo não está no local correto

Solução:

bash

# Verificar diretório de habilidades
ls -la ~/.claude/skills/vercel-deploy/

# Verificar permissões do script
chmod +x ~/.claude/skills/vercel-deploy/scripts/deploy.sh

# Testar script manualmente
bash ~/.claude/skills/vercel-deploy/scripts/deploy.sh .

Armadilha 2: Acivação de Habilidade Incorreta

Sintoma: Ao dizer "check code", aciva Web Design em vez de React Best Practices.

Causa: Palavras-chave de descrição de habilidade entram em conflito.

Solução: Modifique palavras-chave, torne mais específicas:

yaml

# ❌ Antes
description: "Check code for issues"

# ✅ Depois
description: "Review React code for accessibility and UX"

Armadilha 3: IA "Esquece" Habilidade

Sintoma: Funciona na primeira rodada de conversa, mas não funciona na segunda rodada.

Causa: Contexto muito longo, informações de habilidade são descartadas.

Solução:

bash

/clear  # Limpa contexto, mantém habilidades

Resumo da Lição

Pontos Principais:

Palavras-Chave de Acivação: Descrição deve ser específica, conter múltiplas expressões que usuários podem dizer
Gerenciamento de Contexto: Mantenha SKILL.md < 500 linhas, use divulgação progressiva, priorize scripts
Colaboração Multi-Habilidades: Distingua palavras-chave de acivação, processe múltiplas tarefas em ordem clara
Otimização de Desempenho: Simplifique contexto de conversa, evite carregamento repetitivo, monitore uso de Tokens

Fórmula de Melhores Práticas:

Descrição específica, acivação clara Arquivos não muito longos, scripts ocupam espaço Multi-habilidades definem limites, ordem de tarefas clara Contexto deve ser conciso, limpeza periódica evita travamentos

Próxima Lição

Na próxima lição, vamos aprofundar em Arquitetura Técnica e Detalhes de Implementação do Agent Skills.
Você aprenderá:
Detalhamento do fluxo de build (parse → validate → group → sort → generate)
Como funciona o analisador de regras
Sistema de tipos e modelo de dados
Mecanismo de extração de casos de teste
Algoritmos de detecção de frameworks do script de deploy

Apêndice: Referência de Código Fonte

Clique para expandir localizações do código fonte

Atualizado em: 2026-01-25

Funcionalidade	Caminho do Arquivo	Número de Linha
Melhores práticas de gerenciamento de contexto	`AGENTS.md:70-78`	70-78
Exemplos de acivação de habilidades	`README.md:88-102`	88-102
---	---	---
---	---	---

Princípios Chave:

Keep SKILL.md under 500 lines: Mantenha arquivo de habilidade curto
Write specific descriptions: Escreva descrições específicas ajudando a IA a julgar
Use progressive disclosure: Use divulgação progressiva de conteúdo detalhado
Prefer scripts over inline code: Priorize execução de scripts para reduzir consumo de Tokens

Melhores Práticas de Uso do Agent Skills ​

O Que Você Poderá Fazer Após Este Curso ​

Seu Desafio Atual ​

Quando Usar Esta Abordagem ​

Ideia Central ​

Melhor Prática 1: Escolher Precisamente Palavras-Chave de Acivação ​

O que são Palavras-Chave de Acivação? ​

Como Escrever Descrições Eficazes? ​

❌ Exemplo Incorreto: Descrição Muito Vaga ​

✅ Exemplo Correto: Descrição Específica com Palavras-Chave ​

Guia de Escolha de Palavras-Chave ​

Armadilhas: Erros Comuns ​

Melhor Prática 2: Técnicas de Gerenciamento de Contexto ​

Por que o Gerenciamento de Contexto é Importante? ​

Princípio Fundamental: Mantenha SKILL.md Breve ​

Como Fazer Divulgação Progressiva? ​

❌ Maneira Incorreta: Escrever Tudo em SKILL.md ​

✅ Maneira Correta: Separar em Arquivos de Suporte ​

Create new resource ​

Reference Documentation ​

Cenário 2: Precisa Usar Simultaneamente Múltiplas Habilidades ​

Cenário 3: Chamada em Cadeia de Habilidades (Saída de uma é Entrada de Outra) ​

Melhor Prática 4: Sugestões de Otimização de Desempenho ​

1. Simplifique o Contexto da Conversa ​

✅ Solução: Inicie Nova Conversa ou Use "Clear Context" ​

2. Evite Carregamento Repetitivo de Habilidades ​

❌ Maneira Incorreta ​

✅ Maneira Correta ​

3. Use Scripts em Vez de Código Inline ​

✅ Script (recomendado) ​

Padrões de Uso Comuns e Exemplos ​

Padrão 1: Fluxo de Trabalho de Iteração Rápida ​

Padrão 2: Lista de Verificação para Início de Novo Projeto ​

Padrão 3: Modelo de Colaboração de Equipe ​

Armadilhas: Erros Comuns ​

Armadilha 1: Habilidade Ativada Mas Sem Efeito ​

Armadilha 2: Acivação de Habilidade Incorreta ​

Armadilha 3: IA "Esquece" Habilidade ​

Resumo da Lição ​

Próxima Lição ​

Apêndice: Referência de Código Fonte ​

Melhores Práticas de Uso do Agent Skills

O Que Você Poderá Fazer Após Este Curso

Seu Desafio Atual

Quando Usar Esta Abordagem

Ideia Central

Melhor Prática 1: Escolher Precisamente Palavras-Chave de Acivação

O que são Palavras-Chave de Acivação?

Como Escrever Descrições Eficazes?

❌ Exemplo Incorreto: Descrição Muito Vaga

✅ Exemplo Correto: Descrição Específica com Palavras-Chave

Guia de Escolha de Palavras-Chave

Armadilhas: Erros Comuns

Melhor Prática 2: Técnicas de Gerenciamento de Contexto

Por que o Gerenciamento de Contexto é Importante?

Princípio Fundamental: Mantenha SKILL.md Breve

Como Fazer Divulgação Progressiva?

❌ Maneira Incorreta: Escrever Tudo em SKILL.md

✅ Maneira Correta: Separar em Arquivos de Suporte

Create new resource

Reference Documentation

Cenário 2: Precisa Usar Simultaneamente Múltiplas Habilidades

Cenário 3: Chamada em Cadeia de Habilidades (Saída de uma é Entrada de Outra)

Melhor Prática 4: Sugestões de Otimização de Desempenho

1. Simplifique o Contexto da Conversa

✅ Solução: Inicie Nova Conversa ou Use "Clear Context"

2. Evite Carregamento Repetitivo de Habilidades

❌ Maneira Incorreta

✅ Maneira Correta

3. Use Scripts em Vez de Código Inline

✅ Script (recomendado)

Padrões de Uso Comuns e Exemplos

Padrão 1: Fluxo de Trabalho de Iteração Rápida

Padrão 2: Lista de Verificação para Início de Novo Projeto

Padrão 3: Modelo de Colaboração de Equipe

Armadilhas: Erros Comuns

Armadilha 1: Habilidade Ativada Mas Sem Efeito

Armadilha 2: Acivação de Habilidade Incorreta

Armadilha 3: IA "Esquece" Habilidade

Resumo da Lição

Próxima Lição

Apêndice: Referência de Código Fonte