💡 Fase 1: Ideacao e Planejamento
Toda skill comeca com uma necessidade real. Esta fase define o escopo, publico e objetivos da skill antes de escrever qualquer codigo.
🎯 Perguntas Essenciais
- 1. Qual problema resolve? Defina claramente a dor ou necessidade
- 2. Quem vai usar? Desenvolvedores, analistas, designers?
- 3. Ja existe solucao? Pesquise antes de reinventar a roda
- 4. Quais tools precisa? Bash, Read, Write, MCP?
- 5. Escopo e limite? O que a skill NAO deve fazer?
Template de Planejamento
# Skill Planning Document
## Problema
[Descreva o problema que a skill resolve]
## Solucao
[Como a skill resolve o problema]
## Publico-Alvo
[Quem vai usar a skill]
## Tools Necessarias
- [ ] Bash
- [ ] Read/Write
- [ ] MCP: _____
## Fora de Escopo
[O que a skill NAO faz]
## Metricas de Sucesso
[Como saber se a skill funciona bem]💡 Dica de Ouro
Comece pequeno. Uma skill que faz uma coisa muito bem e melhor que uma que tenta fazer tudo. Voce pode sempre expandir depois.
✍️ Fase 2: Desenvolvimento
Com o planejamento feito, e hora de escrever a skill. Siga uma estrutura consistente para facilitar manutencao e uso.
Criar Estrutura de Pastas
mkdir -p ~/.claude/skills/minha-skill
cd ~/.claude/skills/minha-skillEscrever Frontmatter
Metadados essenciais no topo do SKILL.md
---
name: minha-skill
description: Descricao clara com palavras-chave
allowed-tools: Bash(comando:*), Read, Write
---Escrever Corpo da Skill
Secoes recomendadas: Quando Usar, Instrucoes, Exemplos, Restricoes
Adicionar Recursos (Opcional)
Scripts em /scripts, templates em /resources, exemplos em /examples
✓ Boas Praticas
- ✓ Use nomes em kebab-case
- ✓ Descricao com 2-3 frases claras
- ✓ Inclua exemplos de uso
- ✓ Documente restricoes
✗ Evitar
- ✗ Nomes com espacos ou maiusculas
- ✗ Descricoes vagas ou genericas
- ✗ Instrucoes ambiguas
- ✗ Codigo inline muito longo
🧪 Fase 3: Teste e Validacao
Antes de usar em producao, teste exaustivamente. Uma skill mal testada pode causar mais problemas do que resolve.
🧪 Checklist de Testes
Funcionais
- ☐ Skill e descoberta corretamente
- ☐ Instrucoes sao seguidas
- ☐ Tools funcionam como esperado
- ☐ Output e consistente
Edge Cases
- ☐ Input invalido/vazio
- ☐ Arquivos inexistentes
- ☐ Permissoes negadas
- ☐ Timeout de comandos
🔍 Teste Manual
Interaja diretamente com o agente
- • Abra nova sessao Claude Code
- • Peca tarefas que ativem a skill
- • Verifique se carregou
- • Analise resultados
📝 Teste de Cenarios
Crie scripts de teste
- • Liste cenarios de uso
- • Defina input esperado
- • Defina output esperado
- • Execute e compare
👥 Teste com Usuarios
Feedback de usuarios reais
- • Compartilhe com colegas
- • Colete feedback
- • Observe padroes de uso
- • Itere baseado em dados
Verificar se Skill Foi Carregada
Use o comando /skills no Claude Code para listar skills ativas:
/skillsOu pergunte diretamente: "Quais skills voce tem carregadas?"
🚀 Fase 4: Deploy e Distribuicao
Com a skill testada, e hora de disponibilizar para uso. Existem diferentes estrategias dependendo do publico.
Uso Pessoal
Apenas para voce
~/.claude/skills/minha-skill/SKILL.mdDisponivel em todas as suas sessoes Claude Code
Por Projeto
Especifica para um repositorio
/seu-projeto/.claude/skills/skill-especifica/SKILL.mdVersione junto com o projeto no Git
Time/Organizacao
Compartilhar via repositorio
git clone org/skills-repo ~/.claude/skillsMantenha um repo central com skills do time
Comunidade/Publico
Open source para todos
Publique no GitHub, adicione a awesome-claude-skills, ou contribua para anthropics/skills
🔧 Fase 5: Manutencao e Evolucao
Skills nao sao estaticas. Elas precisam evoluir com mudancas em tools, modelos e necessidades do usuario.
🔄 Quando Atualizar
- • Nova versao do agente: Adapte para novas tools ou comportamentos
- • Feedback de usuarios: Corrija problemas reportados
- • Novos casos de uso: Expanda funcionalidades
- • Problemas de performance: Otimize instrucoes
- • Mudancas no workflow: Atualize processos obsoletos
📋 Versionamento
- • Use Git para historico de mudancas
- • Tags para versoes estaveis
- • Changelog documentado
- • Branches para experimentos
📊 Monitoramento
- • Colete metricas de uso
- • Monitore erros comuns
- • Analise padroes de falha
- • Feedback qualitativo
⚠️ Cuidado com Breaking Changes
Se outros dependem da sua skill, comunique mudancas que podem quebrar workflows existentes. Mantenha retrocompatibilidade quando possivel.
📊 Fase 6: Deprecacao e Arquivamento
Skills tem um ciclo de vida finito. Saber quando e como descontinuar uma skill e tao importante quanto cria-la.
Sinais de que uma Skill Deve Ser Deprecada
- ⚠️ Funcionalidade agora e nativa
- ⚠️ Tool que usa foi removida
- ⚠️ Ninguem mais usa
- ⚠️ Existe alternativa melhor
- ⚠️ Manutencao se tornou custosa
- ⚠️ Problemas de seguranca
📋 Processo de Deprecacao
- 1. Anuncie: Comunique a deprecacao com antecedencia
- 2. Documente alternativas: Indique o que usar no lugar
- 3. Periodo de transicao: De tempo para migrar
- 4. Arquive: Mova para pasta /archived ou renomeie
- 5. Remova: Apos periodo, remova completamente
🚀 Proximo Passo
Com o ciclo de vida dominado, o proximo modulo explora Padroes de Comunicacao - como skills interagem com usuarios e sistemas de forma eficaz.
📚 Resumo do Modulo
Proximo Modulo:
1.4 - Padroes de Comunicacao