Navegacao Rapida
🎯 Introducao a Agent Skills
O que sao Skills, como se diferenciam de Tools e Prompts, e o ecossistema atual.
Capacidades modulares e reutilizaveis que estendem a funcionalidade de agentes de IA atraves de arquivos Markdown.
Skills transformam agentes generalistas em especialistas sem precisar repetir instrucoes a cada sessao.
Modularidade, descoberta dinamica, reutilizacao, arquivos SKILL.md
Distincao entre o que agentes SABEM (skills), o que PODEM FAZER (tools) e instrucoes unicas (prompts).
Entender quando usar cada abordagem maximiza eficiencia e evita confusao.
Skills = conhecimento persistente, Tools = acoes executaveis, Prompts = instrucoes de sessao
Estrutura basica de uma skill: pasta contendo SKILL.md mais recursos opcionais.
Saber a estrutura minima permite criar skills validas desde o inicio.
SKILL.md, frontmatter YAML, corpo Markdown, pasta de skill
Panorama dos principais players: Anthropic (Claude), Google (Gemini), e comunidade open-source.
Conhecer as opcoes permite escolher a plataforma certa para cada caso de uso.
agentskills.io, repositorios oficiais, marketplaces, especificacao aberta
Exemplos de skills em producao: documentos Office, TDD, debugging, branding, analytics.
Inspiracao para criar skills proprias baseadas em necessidades do mundo real.
Document skills, Development skills, Enterprise skills, Analytics skills
Roadmap para comecar: instalar skills existentes vs criar do zero.
Ter um caminho claro acelera o aprendizado e evita frustracoes.
~/.claude/skills/ (global), .claude/skills/ (projeto), instalacao, ativacao
📄 Estrutura do Arquivo SKILL.md
O arquivo principal que define a skill: frontmatter YAML e corpo Markdown.
Arquivo principal e OBRIGATORIO que define a skill - funciona como "controle de missao".
E o unico arquivo obrigatorio - sem ele, nao existe skill.
Markdown, frontmatter YAML, instrucoes, metadados
Campo obrigatorio que identifica a skill (max 64 caracteres, lowercase com hyphens).
Nome mal formatado impede a skill de ser descoberta pelo agente.
lowercase, hyphens, sem espacos, sem "claude"/"anthropic"
Campo obrigatorio que define QUANDO usar a skill (max 1024 chars).
O agente usa a description para decidir se invoca a skill automaticamente.
Terceira pessoa, triggers especificos, keywords, contexto de uso
Campo opcional que especifica quais ferramentas a skill pode usar.
Controle de seguranca - limita o que a skill pode executar.
Bash, Read, Write, patterns com wildcard, principio do minimo privilegio
Instrucoes em Markdown que o agente segue quando a skill e invocada.
Instrucoes claras e bem estruturadas geram resultados previsiveis.
Sections, headings, bullet points, code blocks, exemplos
Skill funcional completa com cada linha explicada.
Ver exemplo real consolida o aprendizado e serve de template.
Template replicavel, boas praticas em acao, anti-patterns evitados
📁 Estrutura de Diretorios
Organizacao de pastas: skills globais, de projeto, scripts e recursos.
Estrutura de pastas recomendada: SKILL.md + scripts/, examples/, resources/.
Organizacao correta facilita manutencao e compartilhamento.
SKILL.md obrigatorio, subpastas opcionais, convencoes de nome
Skills disponiveis em TODOS os projetos do usuario.
Ideal para skills de uso geral como code review, TDD, formatacao.
Diretorio home, persistencia entre sessoes, compartilhamento pessoal
Skills especificas de um projeto ou repositorio.
Perfeito para convencoes de time, workflows especificos do projeto.
Raiz do projeto, versionamento com git, compartilhamento de time
Scripts auxiliares em Python, Bash ou Node chamados pela skill.
Automatiza tarefas complexas mantendo SKILL.md limpo e legivel.
Executaveis, validacao, automacao, black box scripts
Templates, JSON de configuracao, assets estaticos referenciados pela skill.
Centraliza dados que a skill usa como referencia.
design-tokens.json, templates Markdown, checklists, assets
Implementacoes de referencia, casos de uso documentados.
Exemplos ajudam o agente a entender o padrao esperado.
Golden examples, patterns, anti-patterns, few-shot learning
✍️ Escrevendo Instrucoes Eficazes
Best practices para instrucoes que agentes entendem: concisao, clareza, graus de liberdade.
Best practices para escrever instrucoes que agentes entendem.
Instrucoes ruins geram resultados imprevisiveis.
Concisao, clareza, especificidade, exemplos concretos
SKILL.md deve ter menos de 500 linhas para evitar sobrecarga de contexto.
Previne perda de informacao e comportamento erratico.
Progressive disclosure, arquivos secundarios, links
Bullets (alta liberdade), code blocks (media), comandos exatos (baixa).
Controle fino sobre comportamento do agente.
Heuristicas vs templates vs comandos deterministicos
Revelar informacao gradualmente atraves de links para arquivos secundarios.
Mantem SKILL.md enxuto, detalhes em arquivos separados.
Links para ADVANCED.md, apenas 1 nivel de profundidade
Listas de verificacao que o agente pode copiar e atualizar.
Permite tracking de estado em tarefas complexas.
Markdown checkboxes, estado mutavel, progresso visivel
Como instruir o agente a lidar com falhas graciosamente.
Skills robustas precisam de fallbacks e mensagens de erro claras.
Black box scripts, --help, mensagens informativas
🎯 Descriptions que Ativam
O campo description como gatilho: erros comuns e padrao eficaz.
O campo que decide se a skill sera invocada automaticamente.
Description ruim = skill nunca ativada.
Matching semantico, relevancia, triggers
Descriptions vagas, genericas ou que nao dizem QUANDO usar.
Evitar erros comuns economiza tempo de debug.
"Helps with code" (ruim), "A tool for" (ruim)
Formula: O QUE faz + QUANDO usar + KEYWORDS especificas.
Descriptions bem estruturadas ativam consistentemente.
Terceira pessoa, verbos de acao, contexto de uso
Palavras especificas que usuarios usam e que devem estar na description.
Keywords certas aumentam taxa de ativacao.
Sinonimos, jargao da area, verbos de acao
Como testar se a description esta ativando a skill corretamente.
Validacao antes de distribuir evita frustracoes.
Prompts de teste, falsos positivos, falsos negativos
Colecao de descriptions reais: boas e ruins, com explicacao.
Aprender com exemplos acelera a curva de aprendizado.
Patterns, anti-patterns, iteracao
📦 Recursos e Scripts
Como usar scripts auxiliares, templates e assets em suas skills.
Scripts Python para processamento de dados, APIs, automacoes complexas.
Python permite tarefas que seriam dificeis em Markdown puro.
pandas, requests, argparse, stdin/stdout
Scripts shell para operacoes de arquivo, git, deploy.
Bash e universal em sistemas Unix/Linux/Mac.
chmod +x, shebang, exit codes, pipes
Templates .md que a skill usa como base para gerar conteudo.
Garante consistencia no output da skill.
Placeholders, variaveis, estrutura fixa
Arquivos JSON com configuracoes: cores, fontes, espacamentos.
Centraliza configuracoes que podem mudar.
design-tokens.json, brand colors, typography
Arquivos que fornecem contexto: voice-tone.md, tech-stack.md.
Permite que a skill acesse conhecimento especifico.
Progressive disclosure, links internos, modularidade
Como referenciar scripts e recursos no corpo do SKILL.md.
Recursos so funcionam se forem corretamente referenciados.
Caminhos relativos, instrucoes de execucao, allowed-tools
🔒 Boas Praticas e Seguranca
Principio do minimo privilegio, allowed-tools, e seguranca em skills.
Dar a skill apenas as permissoes necessarias para funcionar.
Previne acoes nao autorizadas e limita danos em caso de erro.
allowed-tools, wildcards restritos, auditoria
Sintaxe completa do campo allowed-tools: Bash(cmd:*), Read, Write.
Controle granular sobre o que a skill pode executar.
Patterns, wildcards, combinacoes, negacoes
Riscos: Bash sem restricao, Write em qualquer lugar, secrets em texto.
Conhecer riscos permite mitiga-los proativamente.
Command injection, path traversal, data leakage
Lista de verificacao para revisar antes de compartilhar uma skill.
Checklist previne publicar skills inseguras.
Review de permissoes, teste de abuso, documentacao
Como revisar skills de terceiros antes de instalar.
Protege seu sistema de skills maliciosas.
Code review, allowed-tools check, fonte confiavel
Convencoes de codigo, documentacao, versionamento.
Skills bem escritas sao mais faceis de manter e compartilhar.
README, CHANGELOG, semantic versioning
📋 Especificacao Oficial
AgentSkills.io: especificacao aberta, campos, validacao e compatibilidade.
Especificacao aberta para skills de agentes de IA, mantida pela comunidade.
Padrao oficial garante compatibilidade entre plataformas.
Open standard, multi-platform, community-driven
Detalhes da especificacao para name (64 chars) e description (1024 chars).
Campos fora da especificacao podem ser ignorados.
Limites de caracteres, formato obrigatorio, validacao
Campos opcionais: allowed-tools, version, author, tags.
Campos opcionais adicionam funcionalidades extras.
Extensibilidade, metadados, discovery
Ferramentas para validar se uma skill segue a especificacao.
Validacao previne erros antes de distribuir.
Linters, validators, CI/CD integration
Como criar skills que funcionam em multiplas plataformas.
Maximiza alcance e reutilizacao das suas skills.
Campos universais, extensoes especificas, fallbacks
Proximos passos da especificacao: versioning, dependencies, registries.
Preparar-se para evolucoes futuras do ecossistema.
Semantic versioning, skill registries, dependency management