✍️ Criando Skills

O agente compara o contexto da conversa com a description de cada skill instalada. Matching semântico determina se a skill é ativada.

Para escrever descriptions eficazes, pense como o agente: qual situação na conversa dispararia esta instrução?

matching semântico · ativação contextual · intent detection · descrição como seletor

Instruções eficazes usam verbos imperativos (Use, Verifique, Evite), são específicas e têm exemplos quando possível.

Instruções vagas (seja profissional) são inúteis. Instruções específicas (use TypeScript strict mode) são acionáveis.

verbos imperativos · especificidade · exemplos · critérios mensuráveis

A seção When to Use lista cenários concretos em que a skill deve ser ativada. Reforça a description com exemplos reais.

Mesmo que o agente use a description para ativar, When to Use ajuda a confirmar que está no contexto certo.

cenários de ativação · triggers · exemplos concretos · confirmação de contexto

Steps contém passos numerados que o agente executa na ordem indicada. Ideal para processos: code review, geração de componentes, deploy.

Steps bem escritos são como uma receita. Use números quando a ordem importa; bullets quando os itens são independentes.

passos numerados · sequência · checklist · procedimentos

Os 5 erros mais comuns: description vaga, instruções contraditórias, skill muito grande, sem When to Use, jargão opaco.

Conhecer os antipatterns evita criar skills que nunca são ativadas ou que confundem mais do que ajudam.

description vaga · skill monolítica · jargão opaco · contradição · sem contexto

A skill find-skills tem description precisa, When to Use com triggers naturais e Steps acionáveis. O modelo oficial.

Estudar a find-skills garante que suas skills seguem as melhores práticas da especificação oficial do agentskills.io.

modelo oficial · estrutura ideal · triggers naturais · boas práticas

Um repositório bem organizado tem skills/ na raiz com subpastas por categoria: frontend/, devops/, testing/. O CLI faz descoberta recursiva.

Organização por categoria facilita manutenção e permite instalar categorias específicas.

pasta skills/ · subpastas · descoberta recursiva · organização

O CLI busca em: skills/, .claude/skills/, .agents/skills/, .cursor/skills/ e skills/.curated/.

Conhecer as pastas permite colocar skills no lugar certo: skills/ para público, .claude/skills/ para Claude-específico.

skills/ · .claude/skills/ · .agents/skills/ · .curated/ · prioridade

O arquivo .claude-plugin/marketplace.json define metadados: nome, descrição, categorias, autor. Usado pelo skills.sh.

Um marketplace.json preenchido melhora a descoberta no skills.sh e no npx skills find.

marketplace.json · metadados · categorias · skills.sh listing

O CLI percorre recursivamente as pastas, encontrando todos os .md. Arquivos em subpastas como skills/frontend/react.md são incluídos.

A recursividade permite hierarquias profundas sem configuração adicional.

recursividade · profundidade · sem configuração · hierarquia · auto-discovery

Use branches Git: main para estável, develop para experimental. Usuários instalam de um branch via URL com /tree/branch-name.

Versionamento por branch permite desenvolvimento seguro sem afetar usuários em produção.

branches · main · develop · URL com tree/ · fixar versão

Subpastas especiais: skills/.curated/ para skills estáveis, skills/.experimental/ para skills em desenvolvimento.

Separar por maturidade ajuda usuários a escolher: .curated/ para produção, .experimental/ para testes.

.curated · .experimental · maturidade · produção · teste

metadata.internal: true oculta a skill de npx skills find e do skills.sh. Requer INSTALL_INTERNAL_SKILLS=1 para instalar.

Times corporativos têm skills com informações sensíveis que não devem aparecer no diretório público.

internal:true · INSTALL_INTERNAL_SKILLS · visibilidade · confidencialidade

O campo allowed-tools lista ferramentas que o agente pode usar com esta skill ativa. Funciona em quase todos os agentes.

Restringir ferramentas é essencial para segurança: skills de review não devem executar código.

allowed-tools · permissões · segurança · Read · Write · Bash · restrição

context: fork cria subconversa isolada para a skill. Mudanças não afetam a conversa principal. Feature exclusiva Claude Code.

context: fork é ideal para transformações de código — opera em contexto isolado e retorna apenas o resultado.

context:fork · isolamento · subconversa · Claude Code exclusivo · resultados limpos

Hooks executam código em eventos específicos: pre-tool (antes de usar ferramenta), post-tool (depois), pre-compact.

Hooks são a feature mais poderosa. Use pre-tool para validar, post-tool para registrar, pre-compact para salvar estado.

pre-tool · post-tool · pre-compact · Claude Code · Cline · automação

Features básicas funcionam em todos. allowed-tools em quase todos. context:fork apenas Claude Code. Hooks: Claude Code e Cline.

Escrever com graceful degradation — avançado para Claude Code, funcional para todos — é a melhor prática.

matrix de compatibilidade · graceful degradation · Claude Code exclusivo · portabilidade

Use allowed-tools para suporte universal. context:fork e hooks em skills .claude/skills/. Skills em skills/ compatíveis com todos.

Organização comunica compatibilidade: .claude/skills/ = Claude features; skills/ = universal.

organização por compatibilidade · .claude/skills/ · skills universais · requisitos