Modulo 1.4: Padroes de Comunicacao | Agent Skills Mastery

📥 Comunicacao de Entrada (Input)

Como a skill recebe informacoes do usuario e do sistema. Definir padroes claros de entrada evita ambiguidade e erros.

🎯 Fontes de Input

• Mensagem do usuario: Texto livre ou comandos estruturados
• Contexto do projeto: Arquivos, estrutura, configs
• Resultado de tools: Output de Bash, Read, APIs
• Outras skills: Em workflows compostos

📝 Input Natural

Usuario fala naturalmente

"Cria um arquivo README
para este projeto"

Skill interpreta a intencao

⚡ Input Estruturado

Formato especifico esperado

/criar-readme
  --tipo=tecnico
  --idioma=pt-BR

Skill processa parametros

💡 Dica de Design

Prefira input natural sempre que possivel. Usuarios nao querem memorizar comandos. Skill bem escrita entende "faz um PDF" e "gera documento PDF" igualmente.

📤 Comunicacao de Saida (Output)

Como a skill responde ao usuario. Output bem estruturado facilita o uso e gera confianca.

✅

Confirmacao de Acao

Sempre confirme o que foi feito

✓ Arquivo criado: /projeto/README.md
✓ 45 linhas escritas
✓ Secoes: Intro, Instalacao, Uso, Licenca

📊

Sumario de Resultados

Para operacoes que geram dados

Analise completa:
- Arquivos analisados: 23
- Problemas encontrados: 5
- Sugestoes geradas: 12
- Tempo: 2.3s

⚠️

Alertas e Avisos

Quando algo requer atencao

⚠️ Atencao: 3 dependencias desatualizadas
   - lodash: 4.17.0 → 4.17.21 (seguranca)
   - axios: 0.21.0 → 1.6.0 (major)
   - jest: 27.0.0 → 29.7.0 (major)

❌

Erros Claros

Explique o que deu errado e como resolver

❌ Erro: Arquivo nao encontrado
   Caminho: /projeto/config.yaml

   Sugestao: Verifique se o arquivo existe
   ou crie com: touch config.yaml

🔄 Padroes de Dialogo

Skills podem ter diferentes estilos de interacao. Escolher o padrao certo depende do caso de uso.

⚡

Fire & Forget

Usuario pede, skill executa

• Sem perguntas intermediarias
• Execucao imediata
• Bom para tarefas simples
• Ex: formatacao, linting

💬

Interativo

Dialogo para coletar info

• Perguntas de esclarecimento
• Confirmacoes antes de agir
• Bom para tarefas complexas
• Ex: setup de projeto

🔁

Iterativo

Refinamento continuo

• Mostra resultado parcial
• Usuario da feedback
• Skill ajusta e repete
• Ex: geracao de conteudo

💬 Exemplo: Padrao Interativo

Usuario: Cria uma API REST

Skill: Qual framework? (Express, Fastify, Hono)

Usuario: Fastify

Skill: Precisa de autenticacao? (JWT, OAuth, nenhuma)

Usuario: JWT

Skill: Criando API Fastify com JWT...

🔌 Comunicacao com Sistemas

Skills se comunicam com sistemas externos atraves de tools padronizadas. Entender os protocolos garante integracao robusta.

🔧 Protocolos de Comunicacao

Tools Nativas

• Bash: stdin/stdout/stderr
• Read: conteudo de arquivo
• Write: confirmacao de escrita
• WebFetch: HTTP response

MCP (Externas)

• JSON-RPC sobre stdio
• Schema de request/response
• Erro tipados
• Timeouts configurados

Fluxo: Skill → Tool → Sistema

// 1. Skill instrui o agente
"Para verificar status do Git, use Bash com 'git status'"

// 2. Agente chama tool
Bash(command: "git status", description: "Check git status")

// 3. Tool executa e retorna
{
  "output": "On branch main\nnothing to commit",
  "exit_code": 0
}

// 4. Agente interpreta e responde
"O repositorio esta limpo, sem alteracoes pendentes."

✓ Boas Praticas

✓ Trate erros de tools explicitamente
✓ Valide output antes de usar
✓ Use timeouts para operacoes longas

✗ Evitar

✗ Ignorar codigos de erro
✗ Assumir que tool sempre funciona
✗ Comandos sem tratamento de falha

📝 Tom de Voz e Estilo

Skills podem definir um tom de voz especifico para suas respostas. Isso cria consistencia e personalidade.

💼 Profissional

Para contextos corporativos

"A analise foi concluida. Foram identificadas 3 oportunidades de otimizacao no codigo, conforme detalhado abaixo."

😊 Casual

Para uso pessoal/times

"Pronto! Achei 3 coisas que da pra melhorar no codigo. Olha so o que encontrei:"

📚 Didatico

Para ensinar/explicar

"Vamos analisar o codigo juntos. Primeiro, note que na linha 15 ha um padrao que pode ser melhorado..."

🎯 Direto

Minimo de palavras

"3 issues encontradas: L15 (performance), L42 (seguranca), L78 (estilo)"

✍️ Definindo Tom na Skill

## Estilo de Comunicacao

Ao responder, siga estas diretrizes:
- Tom: Profissional mas acessivel
- Formato: Bullet points para listas
- Comprimento: Conciso, maximo 3 paragrafos
- Evitar: Jargao tecnico desnecessario
- Incluir: Exemplos praticos quando relevante

🚨 Tratamento de Erros

Erros sao inevitaveis. Skills bem projetadas tem estrategias claras para lidar com falhas de forma util.

📋 Hierarquia de Erros

⚠️ Warning: Algo inesperado mas nao bloqueante
❌ Error: Falha que impede conclusao da tarefa
🛑 Fatal: Problema critico que requer intervencao

Identificar o Erro

Capture a mensagem de erro original e contexto

Traduzir para Usuario

Converta jargao tecnico em linguagem compreensivel

Sugerir Solucao

Ofereca passos concretos para resolver o problema

Oferecer Alternativa

Se possivel, sugira abordagem diferente

Exemplo: Erro Bem Tratado

❌ Nao foi possivel criar o arquivo

Motivo: Permissao negada em /etc/config.yaml
Causa provavel: O diretorio requer privilegios root

Solucoes:
1. Execute com sudo: sudo claude ...
2. Escolha outro local: ~/config.yaml
3. Ajuste permissoes: sudo chmod 777 /etc

Quer que eu tente criar em ~/config.yaml?

🚀 Proximo Passo

Com padroes de comunicacao dominados, o proximo modulo aborda Seguranca e Permissoes - como proteger skills e usuarios de riscos.

📚 Resumo do Modulo

✓

Input - Natural ou estruturado, prefira natural

✓

Output - Confirmacoes, sumarios, alertas, erros claros

✓

Padroes de Dialogo - Fire & Forget, Interativo, Iterativo

✓

Comunicacao com Sistemas - Tools nativas e MCP para integracao

✓

Tom de Voz - Profissional, casual, didatico, direto

✓

Tratamento de Erros - Identificar, traduzir, sugerir, oferecer alternativas

Proximo Modulo:

1.5 - Seguranca e Permissoes

← Modulo Anterior Proximo Modulo →