grahama1970/skill-creator

Skill Creator

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

Sobre Skills

Skills são pastas modulares e autocontidas que estendem as capacidades do Codex, fornecendo conhecimento especializado, fluxos de trabalho e ferramentas. Pense neles como "guias de integração" para domínios específicos ou tarefas — eles 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 os Skills Oferecem

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íficas
3. Expertise de domínio - Conhecimento específico da empresa, esquemas, lógica de negócios
4. Recursos agrupados - Scripts, referências e ativos para tarefas complexas e repetitivas

Princípios Fundamentais

Concisão é Chave

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 outros 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 de token?"

Prefira exemplos concisos a explicações prolixas.

Defina Graus de Liberdade Apropriados

Combine o nível de especificidade com a 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 percorrendo um caminho: uma ponte estreita com penhascos precisa de guarda-corpos específicos (baixa liberdade), enquanto um campo aberto permite muitas rotas (alta liberdade).

Proteja a Integridade da Validação

Você pode usar subagentes durante a iteração para validar se um skill funciona em tarefas realistas ou se um problema suspeito é real. Isso é mais útil quando você deseja uma verificação independente do comportamento, saídas ou modos de falha do skill após uma revisão. Faça isso apenas quando for possível iniciar novos subagentes.

Ao usar subagentes para validação, trate isso como uma superfície de avaliação. O objetivo é aprender se o skill generaliza, não se outro agente pode reconstruir a resposta a partir de contexto vazado.

Prefira artefatos brutos, como prompts de exemplo, saídas, diffs, logs ou rastros. Forneça o mínimo de contexto local da tarefa necessário para realizar a validação. Evite passar a resposta pretendida, o bug suspeito, a correção pretendida ou suas conclusões anteriores, a menos que a validação as exija explicitamente.

Anatomia de um Skill

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

nome-do-skill/
├── SKILL.md (obrigatório)
│   ├── Metadados YAML frontmatter (obrigatório)
│   │   ├── name: (obrigatório)
│   │   └── description: (obrigatório)
│   └── Instruções Markdown (obrigatório)
├── agents/ (recomendado)
│   └── openai.yaml - Metadados de interface para listas e chips de skills
└── Recursos Agrupados (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)

Cada SKILL.md consiste em:

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

Metadados do Agente (recomendado)

• Metadados voltados para a interface do usuário para listas e chips de skills
• Leia references/openai_yaml.md antes de gerar valores e siga suas descrições e restrições
• Crie: display_name, short_description e default_prompt voltados para humanos lendo o skill
• Gere deterministicamente passando os valores como --interface chave=valor para scripts/generate_openai_yaml.py ou scripts/init_skill.py
• Em atualizações: valide se agents/openai.yaml ainda corresponde ao SKILL.md; regenere se estiver desatualizado
• Inclua apenas outros campos de interface opcionais (ícones, cor da marca) se fornecidos explicitamente
• Consulte references/openai_yaml.md para definições de campo e exemplos

Recursos Agrupados (opcional)

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 pelo Codex para correções ou ajustes específicos 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 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 apenas quando o Codex determina que é necessário
• Melhores práticas: Se os arquivos forem grandes (>10k palavras), inclua padrões de pesquisa grep no SKILL.md
• Evite duplicação: As informações devem 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 verdadeiramente centrais para o skill — isso mantém o SKILL.md enxuto enquanto torna as informações descobertíveis sem sobrecarregar a janela de contexto. Mantenha apenas instruções processuais essenciais e orientações de fluxo de trabalho no 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 o Codex produz.

• Quando incluir: Quando o 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 do 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 um Skill

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

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

O 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 que o criou, procedimentos de configuração e teste, documentação voltada para o usuário, etc. Criar arquivos de documentação adicionais apenas adiciona desordem e confusão.

Princípio de Design de Divulgação Progressiva

Os 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 o skill é acionado (<5k palavras)
3. Recursos agrupados - Conforme necessário pelo Codex (Ilimitado porque scripts podem ser executados sem ler na janela de contexto)

Padrões de Divulgação Progressiva

Mantenha o corpo do SKILL.md no 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 no SKILL.md e descrever claramente quando lê-los, para garantir que o leitor do skill saiba que eles existem e quando usá-los.

Princípio chave: Quando um skill suporta múltiplas variações, estruturas ou opções, mantenha apenas o fluxo de trabalho principal e a orientação de seleção no SKILL.md. Mova detalhes específicos da variante (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

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

## Funcionalidades avançadas

- **Preenchimento de formulários**: Consulte [FORMULARIOS.md](FORMULARIOS.md) para o guia completo
- **Referência da API**: Consulte [REFERENCIA.md](REFERENCIA.md) para todos os métodos
- **Exemplos**: Consulte [EXEMPLOS.md](EXEMPLOS.md) para padrões comuns

Codex carrega FORMULARIOS.md, REFERENCIA.md ou EXEMPLOS.md apenas 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 (receita, métricas de cobrança)
    ├── vendas.md (oportunidades, pipeline)
    ├── produto.md (uso da API, funcionalidades)
    └── marketing.md (campanhas, atribuição)

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

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

implantacao-nuvem/
├── 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, Codex lê apenas aws.md.

Padrão 3: Detalhes condicionais

Mostre conteúdo básico, link para conteúdo avançado:

# Processamento de DOCX

## Criando documentos

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

## Editando documentos

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

**Para controle de alterações**: Consulte [CONTROLE_ALTERACOES.md](CONTROLE_ALTERACOES.md)
**Para detalhes OOXML**: Consulte [OOXML.md](OOXML.md)

Codex lê CONTROLE_ALTERACOES.md ou OOXML.md apenas quando o usuário precisa dessas funcionalidades.

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 linkar diretamente do SKILL.md.
• Estruture arquivos de referência mais longos - Para arquivos com mais de 100 linhas, inclua um índice no topo para que o Codex possa ver o escopo completo ao visualizar.

Processo de Criação de Skill

A criação de um skill envolve estas etapas:

1. Entender o skill com exemplos concretos
2. Planejar o conteúdo reutilizável do skill (scripts, referências, assets)
3. Inicializar o skill (executar init_skill.py)
4. Editar o skill (implementar recursos e escrever o SKILL.md)
5. Validar o skill (executar quick_validate.py)
6. Iterar com base no uso real e testar skills complexos com visão de futuro.

Siga essas etapas em ordem, pulando apenas se houver um motivo claro pelo qual 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 hífen-case (ex.: "Modo Plano" -> modo-plano).
• Ao gerar nomes, gere um nome com menos de 64 caracteres (letras, dígitos, hífens).
• Prefira frases curtas lideradas por verbo que descrevam a ação.
• Namespace por ferramenta quando melhorar a clareza ou acionamento (ex.: gh-endereco-comentarios, linear-endereco-issue).
• Nomeie a pasta do skill exatamente como o nome do skill.

Etapa 1: Entendendo o Skill com Exemplos Concretos

Pule esta etapa apenas quando os padrões de uso do skill já estiverem claramente compreendidos. Ela continua sendo valiosa mesmo ao trabalhar com um skill existente.

Para criar um skill eficaz, entenda claramente exemplos concretos de como o skill será usado. Esse entendimento pode vir de exemplos diretos do usuário ou exemplos gerados que são validados com feedback do usuário.

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

• "Qual funcionalidade o skill de editor de imagens deve suportar? Editar, girar, mais alguma coisa?"
• "Você pode dar alguns exemplos de como este skill seria usado?"
• "Eu posso imaginar usuários pedindo coisas como 'Remova o olho vermelho desta imagem' ou 'Gire esta imagem'. Existem outras maneiras que você imagina este skill sendo usado?"
• "O que um usuário diria que deveria acionar este skill?"
• "Onde devo criar este skill? Se você não tiver preferência, colocarei em $CODEX_HOME/skills (ou ~/.codex/skills quando CODEX_HOME não estiver definido) para que o Codex o descubra automaticamente."

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 um senso claro da funcionalidade que o skill deve suportar.

Etapa 2: Planejando o Conteúdo Reutilizável do Skill

Para transformar exemplos concretos em um 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 um skill editor-pdf 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 no skill

Exemplo: Ao projetar um skill construtor-webapp-frontend para consultas como "Crie um aplicativo de tarefas" ou "Crie 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 HTML/React boilerplate seria útil para armazenar no skill

Exemplo: Ao construir um skill big-query para lidar com consultas como "H

…

[truncado para tradução]