ComposioHQ/skill-creator

Skill Creator

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

Sobre Skills

Skills são pacotes modulares e autocontidos que estendem as capacidades do Codex, fornecendo conhecimento especializado, fluxos de trabalho e ferramentas. Pense nelas como 'guias de integração' para domínios ou tarefas específicas — elas transformam o Codex 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 Oferecem

1. Fluxos de trabalho especializados - Procedimentos de múltiplas etapas para domínios específicos
2. Integrações de ferramentas - Instruções para trabalhar com formatos de arquivo ou APIs específicas
3. Expertise de domínio - Conhecimento específico da empresa, esquemas, lógica de negócios
4. Recursos empacotados - Scripts, referências e ativos para tarefas complexas e repetitivas

Princípios Fundamentais

Concisão é Essencial

A janela de contexto é um bem público. Skills compartilham a janela de contexto com tudo o mais que o Codex precisa: prompt do sistema, histórico da conversa, metadados de outras skills e a solicitação real do usuário.

Suposição padrão: Codex já é muito inteligente. Adicione apenas contexto que o Codex ainda não possui. Desafie cada informação: 'O Codex realmente precisa desta explicação?' e 'Este parágrafo justifica seu custo em tokens?'.

Prefira exemplos concisos em vez de explicações verbosas.

Defina o Grau de Liberdade Apropriado

Corresponda o nível de especificidade à fragilidade e variabilidade da tarefa:

Alta liberdade (instruções baseadas em texto): Use quando várias abordagens são válidas, as decisões dependem do contexto ou heurísticas guiam a abordagem.

Liberdade média (pseudocódigo ou scripts com parâmetros): Use quando existe um padrão preferido, alguma variação é aceitável ou a configuração afeta o comportamento.

Baixa liberdade (scripts específicos, poucos parâmetros): Use quando as operações são frágeis e propensas a erros, a consistência é crítica ou uma sequência específica deve ser seguida.

Pense no Codex explorando um caminho: uma ponte estreita com penhascos precisa de guardrails específicos (baixa liberdade), enquanto um campo aberto permite muitas rotas (alta liberdade).

Anatomia de uma Skill

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

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

SKILL.md (obrigatório)

Todo SKILL.md consiste em:

• Frontmatter (YAML): Contém os campos name e description. Estes são os únicos campos que o Codex lê para determinar quando a skill deve ser usada, portanto, é muito importante ser claro e abrangente ao descrever o que é a skill e quando ela deve ser usada.
• Corpo (Markdown): Instruções e orientações para usar a skill. Só é carregado APÓS a skill ser acionada (se for o caso).

Recursos Empacotados (opcional)

Scripts (scripts/)

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

• 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 pelo Codex para correção ou ajustes específicos de 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 raciocínio do Codex.

• Quando incluir: Para documentação que o Codex 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 o SKILL.md enxuto, carregado somente quando o Codex determina que é necessário
• Melhor prática: Se os arquivos forem grandes (>10k palavras), inclua padrões de busca grep no SKILL.md
• Evite duplicação: A informação deve estar no SKILL.md ou nos arquivos de referência, não em ambos. Prefira arquivos de referência para informações detalhadas, a menos que sejam realmente essenciais para a skill — isso mantém o SKILL.md enxuto, tornando a informação descobrível sem monopolizar a janela de contexto. Mantenha apenas instruções processuais essenciais e orientação de fluxo de trabalho no SKILL.md; mova material de referência detalhado, esquemas e exemplos para arquivos de referência.

Assets (assets/)

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

• Quando incluir: Quando a skill precisa de arquivos que serão usados na saída final
• Exemplos: assets/logo.png para ativos de marca, assets/slides.pptx para modelos de PowerPoint, assets/frontend-template/ para boilerplate HTML/React, 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 recursos de saída da documentação, permite que o Codex use arquivos sem carregá-los no contexto

O que Não Incluir em uma Skill

Uma skill deve conter apenas arquivos essenciais que suportam diretamente sua funcionalidade. NÃO crie documentação ou arquivos auxiliares supérfluos, incluindo:

• README.md
• INSTALLATION_GUIDE.md
• QUICK_REFERENCE.md
• CHANGELOG.md
• etc.

A skill deve conter apenas as informações necessárias para um agente de IA realizar o trabalho em questão. Não deve conter contexto auxiliar sobre o processo de criação, procedimentos de configuração e teste, documentação voltada para o usuário, etc. Criar arquivos de documentação adicionais apenas adiciona ruído e confusão.

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 empacotados - Conforme necessário pelo Codex (Ilimitado porque os scripts podem ser executados sem serem lidos na janela de contexto)

Padrões de Divulgação Progressiva

Mantenha o corpo do SKILL.md com o essencial e abaixo de 500 linhas para minimizar o inchaço do contexto. Divida o conteúdo em arquivos separados ao se aproximar desse limite. Ao dividir o conteúdo em outros arquivos, é muito importante referenciá-los a partir do SKILL.md e descrever claramente quando lê-los, para garantir que o leitor da skill saiba que eles existem e quando usá-los.

Princípio chave: Quando uma skill suporta múltiplas variações, frameworks ou opções, mantenha apenas o fluxo de trabalho principal e a orientação de seleção no SKILL.md. Mova detalhes específicos de variantes (padrões, exemplos, configuração) para arquivos de referência separados.

Padrão 1: Guia de alto nível com referências

# Processamento de PDF

## Início rápido

Extrair texto com pdfplumber:
[exemplo de código]

## Recursos avançados

- **Preenchimento de formulários**: Veja [FORMS.md](FORMS.md) para o guia completo
- **Referência de API**: Veja [REFERENCE.md](REFERENCE.md) para todos os métodos
- **Exemplos**: Veja [EXAMPLES.md](EXAMPLES.md) para padrões comuns

O Codex carrega FORMS.md, REFERENCE.md ou EXAMPLES.md somente quando necessário.

Padrão 2: Organização específica de domínio

Para Skills com múltiplos domínios, organize o conteúdo por domínio para evitar carregar contexto irrelevante:

bigquery-skill/
├── SKILL.md (visão geral e navegação)
└── reference/
    ├── finance.md (métricas de receita, faturamento)
    ├── sales.md (oportunidades, pipeline)
    ├── product.md (uso de API, recursos)
    └── marketing.md (campanhas, atribuição)

Quando um usuário pergunta sobre métricas de vendas, o Codex lê apenas sales.md.

Da mesma forma, para skills que suportam múltiplos frameworks ou variantes, organize por variante:

cloud-deploy/
├── SKILL.md (fluxo de trabalho + seleção de provedor)
└── references/
    ├── aws.md (padrões de implantação AWS)
    ├── gcp.md (padrões de implantação GCP)
    └── azure.md (padrões de implantação Azure)

Quando o usuário escolhe AWS, o Codex lê apenas aws.md.

Padrão 3: Detalhes condicionais

Mostre o conteúdo básico, vincule ao conteúdo avançado:

# Processamento de DOCX

## Criando documentos

Use docx-js para novos documentos. Veja [DOCX-JS.md](DOCX-JS.md).

## Editando documentos

Para edições simples, modifique o XML diretamente.

**Para alterações controladas**: Veja [REDLINING.md](REDLINING.md)
**Para detalhes do OOXML**: Veja [OOXML.md](OOXML.md)

O Codex lê REDLINING.md ou OOXML.md somente quando o usuário precisa desses recursos.

Diretrizes importantes:

• Evite referências profundamente aninhadas - Mantenha as referências a um nível de profundidade a partir do SKILL.md. Todos os arquivos de referência devem estar diretamente vinculados ao SKILL.md.
• Estruture arquivos de referência mais longos - Para arquivos com mais de 100 linhas, inclua um índice no início para que o Codex possa ver o escopo completo ao visualizar.

Processo de Criação de Skills

A criação de skills envolve estas etapas:

1. Entender a skill com exemplos concretos
2. Planejar o conteúdo reutilizável da skill (scripts, referências, assets)
3. Inicializar a skill (executar init_skill.py)
4. Editar a skill (implementar recursos e escrever o SKILL.md)
5. Empacotar a skill (executar package_skill.py)
6. Iterar com base no uso real

Siga essas etapas em ordem, pulando apenas se houver um motivo claro pelo qual elas não são aplicáveis.

Nomenclatura de Skills

• Use apenas letras minúsculas, dígitos e hífens; normalize títulos fornecidos pelo usuário para hifenização (ex.: "Plan Mode" -> plan-mode).
• Ao gerar nomes, gere um nome com menos de 64 caracteres (letras, dígitos, hífens).
• Prefira nomes curtos, liderados por verbos, que descrevam a ação.
• Namespace pela ferramenta quando melhorar a clareza ou o acionamento (ex.: gh-address-comments, linear-address-issue).
• Nomeie a pasta da skill exatamente com o nome da skill.

Etapa 1: Entendendo a 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, entenda claramente exemplos concretos de como a skill será usada. Esse entendimento pode vir de exemplos diretos do usuário ou de 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? Editar, girar, algo mais?"
• "Você pode dar alguns exemplos de como essa skill seria usada?"
• "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 deveria acionar esta skill?"

Para evitar sobrecarregar os usuários, evite fazer muitas perguntas em uma única mensagem. Comece com as perguntas mais importantes e faça o acompanhamento 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: Planejando o 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 assets seriam úteis ao executar esses fluxos de trabalho repetidamente

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

1. Girar um PDF requer 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 de frontend-webapp-builder para consultas como "Construa-me um aplicativo de tarefas" ou "Construa-me um painel para rastrear meus passos", a análise mostra:

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

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

1. Consultar o BigQuery requer redescobrir os esquemas de tabela e relacionamentos cada vez
2. Um arquivo references/schema.md documentando os esquemas de tabela 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 assets.

Etapa 3: Inicializando a Skill

Agora é hora de realmente criar a skill.

Pule esta etapa apenas se a skill que está sendo desenvolvida já existir e for 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 automaticamente inclui tudo o que uma skill requer, tornando o processo de criação da skill muito mais eficiente e confiável.

Uso:

scripts/init_skill.py <nome-da-skill> --path <diretório-de-saída> [--resources scripts,referências,assets] [--examples]

Exemplos:

scripts/init_skill.py my-skill --path skills/public
scripts/init_skill.py my-skill --path skills/public --resources scripts,referencias
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples

O script:

• Cria o diretório da skill no caminho especificado
• Gera um modelo de SKILL.md com frontmatter adequado e placeholders TODO
• Opcionalmente cria diretórios de recursos com base em --resources
• Opcionalmente adiciona arquivos de exemplo quando --examples está definido

Após a inicialização, personalize o SKILL.md e adicione recursos conforme necessário. Se você usou --examples, substitua ou exclua os arquivos placeholder.

Etapa 4: Editar a Skill

Ao editar a skill (recém-gerada ou existente), lembre-se de que a skill está sendo criada para outro Codex — a skill deve ser escrita de uma forma que o Codex entend...

[truncado para tradução, mas mantendo a estrutura conforme o original cortado]