skill-creator

Skill Creator

Esta skill fornece orientação para criar skills eficazes.

Sobre Skills

Skills são pacotes modulares e auto-contidos que estendem as capacidades de Claude, fornecendo conhecimento especializado, fluxos de trabalho e ferramentas. Pense nelas como "guias de integração" para domínios ou tarefas específicas — elas transformam Claude de um agente de propósito geral em um agente especializado, equipado com conhecimento processual que nenhum modelo pode possuir completamente.

O Que as Skills Fornecem

1. Fluxos de trabalho especializados - Procedimentos de várias etapas para domínios específicos
2. Integrações de ferramentas - Instruções para trabalhar com formatos de arquivo ou APIs específicos
3. Conhecimento de domínio - Esquemas, lógica de negócios e conhecimento específico da empresa
4. Recursos agrupados - Scripts, referências e ativos para tarefas complexas e repetitivas

Anatomia de uma Skill

Toda skill consiste em um arquivo SKILL.md obrigatório e recursos opcionais agrupados:

nome-da-skill/
├── SKILL.md (obrigatório)
│   ├── Metadados YAML frontmatter (obrigatório)
│   │   ├── name: (obrigatório)
│   │   └── description: (obrigatório)
│   └── Instruções Markdown (obrigatório)
└── Recursos Agrupados (opcionais)
    ├── scripts/          - Código executável (Python/Bash/etc.)
    ├── references/       - Documentação para carregar no contexto conforme necessário
    └── assets/           - Arquivos usados na saída (modelos, ícones, fontes, etc.)

SKILL.md (obrigatório)

Qualidade dos Metadados: O name e description no YAML frontmatter determinam quando Claude usará a skill. Seja específico sobre o que a skill faz e quando usá-la. Use a terceira pessoa (ex.: "Esta skill deve ser usada quando..." em vez de "Use esta skill quando...").

Recursos Agrupados (opcionais)

Scripts (scripts/)

Código executável (Python/Bash/etc.) para tarefas que exigem confiabilidade determinística ou são reescritas repetidamente.

• Quando incluir: Quando o mesmo código está sendo reescrito repetidamente ou é necessária confiabilidade determinística
• Exemplo: scripts/rotate_pdf.py para tarefas de rotação de PDF
• Benefícios: Eficiente em tokens, determinístico, pode ser executado sem carregar no contexto
• Nota: Scripts ainda podem precisar ser lidos por Claude para ajustes ou adaptações específicas do ambiente

Referências (references/)

Documentação e material de referência destinados a serem carregados conforme necessário no contexto para informar o processo e o pensamento de Claude.

• Quando incluir: Para documentação que Claude deve consultar enquanto trabalha
• Exemplos: references/finance.md para esquemas financeiros, references/mnda.md para modelo de NDA da empresa, references/policies.md para políticas da empresa, references/api_docs.md para especificações de API
• Casos de uso: Esquemas de banco de dados, documentação de API, conhecimento de domínio, políticas da empresa, guias de fluxo de trabalho detalhados
• Benefícios: Mantém SKILL.md enxuto, carregado apenas quando Claude determina que é necessário
• Melhor prática: Se os arquivos forem grandes (>10k palavras), inclua padrões de pesquisa grep em SKILL.md
• Evite duplicação: As informações devem estar em SKILL.md ou em arquivos de referência, não em ambos. Prefira arquivos de referência para informações detalhadas, a menos que sejam verdadeiramente essenciais para a skill — isso mantém SKILL.md enxuto enquanto torna as informações descobertíveis sem ocupar a janela de contexto. Mantenha apenas instruções processuais essenciais e orientações de fluxo de trabalho em SKILL.md; mova material de referência detalhado, esquemas e exemplos para arquivos de referência.

Ativos (assets/)

Arquivos não destinados a serem carregados no contexto, mas sim usados na saída que Claude produz.

• Quando incluir: Quando a skill precisar de arquivos que serão usados na saída final
• Exemplos: assets/logo.png para ativos de marca, assets/slides.pptx para modelos PowerPoint, assets/frontend-template/ para HTML/React boilerplate, assets/font.ttf para tipografia
• Casos de uso: Modelos, imagens, ícones, código boilerplate, fontes, documentos de amostra que são copiados ou modificados
• Benefícios: Separa os recursos de saída da documentação, permite que Claude use arquivos sem carregá-los no contexto

Princípio de Design de Divulgação Progressiva

As skills usam um sistema de carregamento de três níveis para gerenciar o contexto de forma eficiente:

1. Metadados (nome + descrição) - Sempre no contexto (~100 palavras)
2. Corpo do SKILL.md - Quando a skill é acionada (<5k palavras)
3. Recursos agrupados - Conforme necessário por Claude (Ilimitado*)

*Ilimitado porque scripts podem ser executados sem serem lidos na janela de contexto.

Processo de Criação de Skill

Para criar uma skill, siga o "Processo de Criação de Skill" em ordem, pulando etapas apenas se houver uma razão clara para não serem aplicáveis.

Etapa 1: Compreensão da Skill com Exemplos Concretos

Pule esta etapa apenas quando os padrões de uso da skill já estiverem claramente compreendidos. Ela permanece valiosa mesmo ao trabalhar com uma skill existente.

Para criar uma skill eficaz, compreenda claramente exemplos concretos de como a skill será usada. Essa compreensão pode vir de exemplos diretos do usuário ou exemplos gerados que são validados com feedback do usuário.

Por exemplo, ao construir uma skill de editor de imagens, perguntas relevantes incluem:

• "Qual funcionalidade a skill de editor de imagens deve suportar? Edição, rotação, algo mais?"
• "Você pode dar alguns exemplos de como essa skill seria usada?"
• "Eu posso imaginar usuários pedindo coisas como 'Remova o olho vermelho desta imagem' ou 'Gire esta imagem'. Existem outras maneiras que você imagina essa skill sendo usada?"
• "O que um usuário diria que deve acionar esta skill?"

Para evitar sobrecarregar os usuários, evite fazer muitas perguntas em uma única mensagem. Comece com as perguntas mais importantes e acompanhe conforme necessário para melhor eficácia.

Conclua esta etapa quando houver uma noção clara da funcionalidade que a skill deve suportar.

Etapa 2: Planejamento do Conteúdo Reutilizável da Skill

Para transformar exemplos concretos em uma skill eficaz, analise cada exemplo:

1. Considerando como executar o exemplo do zero
2. Identificando quais scripts, referências e ativos seriam úteis ao executar esses fluxos de trabalho repetidamente

Exemplo: Ao construir uma skill pdf-editor para lidar com consultas como "Ajude-me a girar este PDF", a análise mostra:

1. Girar um PDF exige reescrever o mesmo código cada vez
2. Um script scripts/rotate_pdf.py seria útil para armazenar na skill

Exemplo: Ao projetar uma skill frontend-webapp-builder para consultas como "Construa um app de tarefas" ou "Construa um dashboard para acompanhar meus passos", a análise mostra:

1. Escrever um webapp frontend exige o mesmo boilerplate HTML/React cada vez
2. Um modelo assets/hello-world/ contendo os arquivos do projeto HTML/React boilerplate seria útil para armazenar na skill

Exemplo: Ao construir uma skill big-query para lidar com consultas como "Quantos usuários fizeram login hoje?", a análise mostra:

1. Consultar o BigQuery exige redescobrir os esquemas e relações das tabelas cada vez
2. Um arquivo references/schema.md documentando os esquemas das tabelas seria útil para armazenar na skill

Para estabelecer o conteúdo da skill, analise cada exemplo concreto para criar uma lista dos recursos reutilizáveis a incluir: scripts, referências e ativos.

Etapa 3: Inicialização da Skill

Neste ponto, é hora de realmente criar a skill.

Pule esta etapa apenas se a skill que está sendo desenvolvida já existe e é necessária iteração ou empacotamento. Nesse caso, continue para a próxima etapa.

Ao criar uma nova skill do zero, sempre execute o script init_skill.py. O script gera convenientemente um novo diretório de modelo de skill que inclui automaticamente tudo que uma skill requer, tornando o processo de criação muito mais eficiente e confiável.

Uso:

scripts/init_skill.py <nome-da-skill> --path <diretório-de-saída>

O script:

• Cria o diretório da skill no caminho especificado
• Gera um modelo SKILL.md com frontmatter adequado e placeholders TODO
• Cria diretórios de recursos de exemplo: scripts/, references/ e assets/
• Adiciona arquivos de exemplo em cada diretório que podem ser personalizados ou excluídos

Após a inicialização, personalize ou remova o SKILL.md gerado e os arquivos de exemplo conforme necessário.

Etapa 4: Edição da Skill

Ao editar a skill (recém-gerada ou existente), lembre-se de que a skill está sendo criada para outra instância de Claude usar. Concentre-se em incluir informações que seriam benéficas e não óbvias para Claude. Considere qual conhecimento processual, detalhes específicos do domínio ou ativos reutilizáveis ajudariam outra instância de Claude a executar essas tarefas de forma mais eficaz.

Comece com o Conteúdo Reutilizável da Skill

Para iniciar a implementação, comece com os recursos reutilizáveis identificados acima: arquivos scripts/, references/ e assets/. Observe que esta etapa pode exigir entrada do usuário. Por exemplo, ao implementar uma skill de diretrizes-de-marca, o usuário pode precisar fornecer ativos de marca ou modelos para armazenar em assets/, ou documentação para armazenar em references/.

Além disso, exclua quaisquer arquivos e diretórios de exemplo que não sejam necessários para a skill. O script de inicialização cria arquivos de exemplo em scripts/, references/ e assets/ para demonstrar a estrutura, mas a maioria das skills não precisará de todos eles.

Atualize SKILL.md

Estilo de Escrita: Escreva toda a skill usando forma imperativa/infinitiva (instruções começando com verbo), não em segunda pessoa. Use linguagem objetiva e instrucional (ex.: "Para realizar X, faça Y" em vez de "Você deve fazer X" ou "Se você precisar fazer X"). Isso mantém consistência e clareza para consumo por IA.

Para completar SKILL.md, responda às seguintes perguntas:

1. Qual é o propósito da skill, em poucas frases?
2. Quando a skill deve ser usada?
3. Na prática, como Claude deve usar a skill? Todos os conteúdos reutilizáveis da skill desenvolvidos acima devem ser referenciados para que Claude saiba como usá-los.

Etapa 5: Empacotamento de uma Skill

Assim que a skill estiver pronta, ela deve ser empacotada em um arquivo zip distribuível que será compartilhado com o usuário. O processo de empacotamento valida automaticamente a skill primeiro para garantir que atenda a todos os requisitos:

scripts/package_skill.py <caminho/para/pasta-da-skill>

Especificação opcional do diretório de saída:

scripts/package_skill.py <caminho/para/pasta-da-skill> ./dist

O script de empacotamento irá:

1. Validar a skill automaticamente, verificando:

   • Formato YAML frontmatter e campos obrigatórios
   • Convenções de nomenclatura da skill e estrutura de diretórios
   • Completude e qualidade da descrição
   • Organização de arquivos e referências de recursos

2. Empacotar a skill se a validação passar, criando um arquivo zip nomeado após a skill (ex.: minha-skill.zip) que inclui todos os arquivos e mantém a estrutura de diretórios adequada para distribuição.

Se a validação falhar, o script relatará os erros e sairá sem criar um pacote. Corrija os erros de validação e execute o comando de empacotamento novamente.

Etapa 6: Iterar

Após testar a skill, os usuários podem solicitar melhorias. Isso geralmente acontece logo após usar a skill, com contexto novo de como a skill se saiu.

Fluxo de trabalho de iteração:

1. Use a skill em tarefas reais
2. Observe dificuldades ou ineficiências
3. Identifique como SKILL.md ou os recursos agrupados devem ser atualizados
4. Implemente as mudanças e teste novamente