skill-creator

Skill Creator

Esta 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 nelas como "guias de integração" para domínios específicos ou tarefas — elas transformam o Codex de um agente de propósito geral em um agente especializado equipado com conhecimento procedural 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í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 Centrais

Conciso é Essencial

A janela de contexto é um bem público. As 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: O Codex já é muito inteligente. Adicione apenas contexto que o Codex ainda não possui. Questione 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 verbosas.

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 múltiplas abordagens são válidas, as decisões dependem do contexto ou heurísticas guiam a abordagem.

Média liberdade (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 como explorando um caminho: uma ponte estreita com penhascos precisa de guardrails 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 uma skill funciona em tarefas realistas ou se um problema suspeito é real. Isso é mais útil quando você deseja uma avaliação independente do comportamento, saídas ou modos de falha da 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 a 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 traces. 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 os exija explicitamente.

Anatomia de uma Skill

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

nome-da-skill/
├── SKILL.md (obrigatório)
│   ├── metadados frontmatter YAML (obrigatório)
│   │   ├── name: (obrigatório)
│   │   └── description: (obrigatório)
│   └── instruções Markdown (obrigatório)
├── agents/ (recomendado)
│   └── openai.yaml - metadados de UI 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. Estes são os únicos campos que o Codex lê para determinar quando a skill será usada, portanto, é muito importante ser claro e abrangente ao descrever o que a skill é e quando deve ser usada.
• Corpo (Markdown): Instruções e orientações para usar a skill. É carregado SOMENTE depois que a skill é acionada (se for o caso).

Metadados de Agents (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 a 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 outros campos de interface opcionais (ícones, cor da marca) apenas se fornecidos explicitamente
• Consulte references/openai_yaml.md para definições de campos 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 ser carregado no contexto
• Nota: Os 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 o pensamento do Codex.

• Quando incluir: Para documentação que o Codex deve consultar durante o trabalho
• 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 busca grep no SKILL.md
• Evite duplicação: A informação deve residir 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 a skill — isso mantém o SKILL.md enxuto enquanto torna as informações encontráveis sem consumir 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 que não se destinam a ser 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 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 os 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 auxiliar ou arquivos extras, incluindo:

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

A skill deve conter apenas as informações necessárias para que um agente de IA execute o trabalho em questão. Não deve conter contexto auxiliar sobre o processo que envolveu sua criação, 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

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

1. Metadados (name + description) - Sempre no contexto (~100 palavras)
2. Corpo do SKILL.md - Quando a skill é acionada (<5k palavras)
3. Recursos agrupados - Conforme necessário pelo Codex (Ilimitado porque scripts podem ser executados sem serem lidos 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 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 central e a orientação de seleção no SKILL.md. Mova detalhes específicos de variações (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](https://raw.githubusercontent.com/openai/codex/main/FORMS.md) para o guia completo
- **Referência de API**: Veja [REFERENCE.md](https://raw.githubusercontent.com/openai/codex/main/REFERENCE.md) para todos os métodos
- **Exemplos**: Veja [EXAMPLES.md](https://raw.githubusercontent.com/openai/codex/main/EXAMPLES.md) para padrões comuns

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

Padrão 2: Organização por 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 faturamento)
    ├── sales.md (oportunidades, pipeline)
    ├── product.md (uso da 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 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](https://raw.githubusercontent.com/openai/codex/main/DOCX-JS.md).

## Editando documentos

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

**Para alterações controladas**: Veja [REDLINING.md](https://raw.githubusercontent.com/openai/codex/main/REDLINING.md)
**Para detalhes do OOXML**: Veja [OOXML.md](https://raw.githubusercontent.com/openai/codex/main/OOXML.md)

O Codex lê REDLINING.md ou OOXML.md apenas 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 vincular 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 skill envolve estas etapas:

1. Entenda a skill com exemplos concretos
2. Planeje o conteúdo reutilizável da skill (scripts, referências, assets)
3. Inicialize a skill (execute init_skill.py)
4. Edite a skill (implemente recursos e escreva o SKILL.md)
5. Valide a skill (execute quick_validate.py)
6. Itere com base no uso real e teste skills complexas com antecedência.

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 hífen-case (ex.: "Plan Mode" -> plan-mode).
• Ao gerar nomes, gere um nome com menos de 64 caracteres (letras, dígitos, hífens).
• Prefira frases curtas lideradas por verbos que descrevam a ação.
• Namespace por 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:

• "Que funcionalidade a skill de editor de imagens deve suportar? Editar, rotacionar, 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 'Rotacione esta imagem'. Existem outras maneiras que você imagina essa skill sendo usada?"
• "O que um usuário diria que deveria acionar esta skill?"
• "Onde devo criar esta skill? Se você não tiver preferência, vou colocá-la em $CODEX_HOME/skills (ou ~/.codex/skills quando CODEX_HOME não estiver definido) para que o Codex possa descobri-la automaticamente."

Para não 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: 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 pdf-editor para lidar com consultas como "Ajude-me a rotacionar este PDF", a análise mostra:

1. Rotacionar 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-me um aplicativo de tarefas" ou "Construa-me um dashboard para monitorar..."

[...truncado para tradução]