aiskillstore/marketplace

Criador de Skills

Crie skills que forneçam ao Codex orientações úteis e não óbvias, sem restringir trabalhos não relacionados.

Princípios Fundamentais

Presuma que o Codex já é capaz. Inclua apenas informações que alterem suas decisões ou melhorem seu trabalho. Remova conselhos genéricos, instruções repetidas, casos extremos especulativos e exemplos que não esclareçam materialmente a tarefa.

Preserve a intenção e o escopo do usuário. Uma skill deve apoiar a tarefa solicitada, não substituir o produto escolhido pelo usuário, expandir a atribuição, modificar configurações não relacionadas ou implicar permissão para ações externas adicionais. Não transforme um exemplo particular, falha passada ou preferência pessoal em um requisito universal.

A aprovação para concluir uma tarefa não expande seu escopo ou permissões de execução. Para fluxos de repetição ou mutação externa, defina uma condição de parada proporcional ao risco.

Combine a especificidade ao risco. Dê ao modelo espaço para escolher uma abordagem apropriada quando várias abordagens forem razoáveis. Use etapas detalhadas, scripts determinísticos ou linguagem absoluta apenas quando correção, segurança, permissões ou um fluxo genuinamente frágil os exigirem.

Para trabalhos abertos, descreva o resultado e os critérios de decisão relevantes. Para fluxos com uma forma preferida, ofereça exemplos úteis ou scripts configuráveis. Reserve sequências fixas e parâmetros restritos para operações onde desvios causariam um problema concreto. Preserve invariantes operacionais não óbvios, distinga requisitos reais de recomendações opcionais ou convenções locais e evite reafirmar políticas já aplicadas em outro lugar.

Mantenha a descoberta barata e precisa. Nomes e descrições de skills estão disponíveis antes de uma skill ser carregada. Descreva a capacidade real e quando ela se aplica, adicionando exclusões apenas quando evitarem um possível direcionamento incorreto. Evite listas exaustivas de capacidades e abrangências que atraiam solicitações não relacionadas.

Mantenha as skills autocontidas; refira-se a outra skill ou ferramenta apenas quando o fluxo solicitado genuinamente o exigir e ela estiver disponível no ambiente alvo. Fluxos especializados de revisão, fortalecimento ou auditoria devem ser aplicados quando solicitados ou genuinamente necessários, não meramente porque o trabalho comum toca no mesmo assunto.

Divulgue detalhes progressivamente. Mantenha propósito compartilhado, restrições essenciais e roteamento útil em SKILL.md. Coloque orientações substanciais específicas de modo, esquemas, exemplos ou procedimentos em referências de suporte e leia apenas as referências relevantes para a tarefa atual. Uma skill simples e autocontida não precisa de um roteador ou arquivos extras.

Anatomia de uma Skill

Toda skill é uma pasta contendo um arquivo SKILL.md obrigatório e quaisquer recursos opcionais que seu fluxo real necessite:

skill-name/
|-- SKILL.md                 Instruções obrigatórias da skill
|   |-- Frontmatter YAML     Nome e descrição obrigatórios
|   `-- Corpo Markdown        Instruções carregadas quando a skill é usada
|-- agents/                  Metadados opcionais de interface e política de invocação
|   `-- openai.yaml
|-- scripts/                 Ajudantes executáveis opcionais
|-- references/              Documentação opcional carregada conforme necessário
`-- assets/                  Arquivos opcionais usados na saída gerada

Escolha a estrutura que se encaixa na tarefa real. Algumas skills são curtas e autocontidas; outras roteiam entre modos de operação ou delegam mecânicas complexas a scripts. Evite criar diretórios, placeholders, exemplos ou documentação auxiliar sem um uso claro.

SKILL.md

O frontmatter YAML identifica a skill e determina quando ela deve ser considerada. Inclua o name e description obrigatórios e preserve campos opcionais suportados, como metadata existente, quando apropriado.

O corpo Markdown é carregado apenas quando a skill é usada. Coloque lá o propósito, fluxo essencial, restrições reais e links úteis. Mantenha procedimentos detalhados e exemplos em referências de suporte quando forem relevantes apenas para modos particulares.

As informações da skill são divulgadas em três estágios:

1. Nome e descrição: Disponíveis durante a seleção da skill, então mantenha-os concisos e discriminativos.
2. Corpo do SKILL.md: Carregado quando a skill se aplica, então mantenha suas instruções relevantes para essa tarefa.
3. Recursos de suporte: Lidos ou executados apenas quando a tarefa atual realmente precisar deles.

O ponto de entrada deve ser tão curto quanto a tarefa permitir, mantendo restrições importantes. Um limite superior grande não é um alvo: mova detalhes condicionais para referências quando isso melhorar a clareza ou o uso de contexto, em vez de esperar que o arquivo se torne difícil de manusear.

Scripts

Use scripts/ para código executável quando a mesma lógica seria reescrita repetidamente ou a execução determinística melhora materialmente a confiabilidade.

• Exemplo: scripts/rotate_pdf.py para uma operação de PDF que exigiria recriar o mesmo código.
• Útil para: Transformações repetidas, operações confiáveis de API, processamento de dados e outras automações concretas.
• Validação: Execute scripts novos ou alterados para verificar seu comportamento. Scripts geralmente podem ser executados sem carregar sua implementação completa no contexto, embora um agente possa precisar inspecioná-los ao corrigi-los ou adaptá-los.

Referências

Use references/ para documentação necessária apenas em contextos particulares.

• Exemplos: references/schema.md para tabelas de banco de dados, references/policies.md para regras de domínio, references/api_docs.md para uma API, ou guias de escrita separados para diferentes entregáveis.
• Útil para: Esquemas, documentação de API, políticas da empresa, procedimentos específicos de formato, fluxos detalhados e exemplos substanciais.
• Roteamento: Vincule cada referência a partir de SKILL.md ou de outro recurso relevante e explique quando ela deve ser lida. Mantenha as informações em um único lugar, em vez de duplicá-las entre o ponto de entrada e as referências.

Mantenha as referências focadas em informações mantidas e específicas da tarefa que alteram as decisões do agente. Evite manuais copiados, catálogos exaustivos e tutoriais genéricos já disponíveis em fontes autorizadas. Antes de remover recursos existentes, inspecione seus chamadores e propósito.

Para referências grandes, inclua termos de pesquisa úteis ou uma seção curta de conteúdo quando isso facilitar a localização do material necessário.

Assets

Use assets/ para arquivos que pertencem à saída gerada, em vez de às instruções do modelo.

• Exemplos: assets/logo.png, assets/slides.pptx, assets/font.ttf ou assets/frontend-template/.
• Útil para: Modelos, imagens, fontes, ícones, projetos boilerplate e outros arquivos copiados ou adaptados no resultado.
• Contexto: Não carregue assets como instruções, a menos que a tarefa exija inspecioná-los.

Metadados de Interface e Política de Invocação

agents/openai.yaml pode fornecer metadados voltados para a interface, como display_name, short_description e default_prompt, juntamente com a política de invocação. Ao criar ou atualizar essas configurações, leia references/openai_yaml.md e mantenha os valores consistentes com a skill.

A seleção automática de skills é permitida por padrão. Altere esse padrão apenas quando o usuário solicitar explicitamente uma skill apenas explícita:

policy:
  allow_implicit_invocation: false

Isso mantém a skill disponível quando invocada explicitamente como $skill-name sem adicioná-la automaticamente ao contexto do modelo. Preserve campos existentes não relacionados de interface, política e dependências ao atualizar agents/openai.yaml.

O inicializador cria este arquivo automaticamente. Para metadados novos ou apenas de interface, gere-o com:

scripts/generate_openai_yaml.py <caminho/para/pasta-da-skill> --interface chave=valor

O gerador substitui o arquivo inteiro. Se um arquivo existente contiver policy ou dependencies, atualize apenas os campos pretendidos no local em vez de regenerá-lo.

Inclua campos opcionais de interface apenas quando o usuário os fornecer ou solicitar.

O Que Não Incluir

Inclua arquivos que suportam diretamente o trabalho da skill. Evite adicionar README.md, guia de instalação, changelog, referência rápida duplicada ou outra documentação auxiliar, a menos que uma tarefa específica ou requisito de empacotamento os exija.

Divulgação Progressiva na Prática

Para uma skill com vários modos substanciais, mantenha a orientação compartilhada e os critérios de seleção de modo em SKILL.md. Vincule cada referência de suporte onde seu uso se torna relevante. Não carregue toda referência por padrão, duplique o conteúdo da referência no ponto de entrada ou adicione uma camada de roteamento quando não houver nada significativo para rotear.

Por exemplo, uma skill de implantação pode manter a seleção de provedor em SKILL.md e separar detalhes de provedor:

cloud-deploy/
|-- SKILL.md
`-- references/
    |-- aws.md
    |-- gcp.md
    `-- azure.md

Quando o usuário escolher AWS, leia references/aws.md; não carregue também os guias GCP e Azure. O mesmo padrão pode separar domínios de negócios, tipos de entregáveis ou outros modos de operação genuinamente distintos.

Uma skill curta pode, em vez disso, rotear para detalhes apenas quando uma operação avançada precisar deles:

## Documentos

Lide com edições comuns diretamente.

- Para alterações controladas, leia [references/redlining.md](references/redlining.md).
- Para detalhes internos de documentos, leia [references/ooxml.md](references/ooxml.md).

Esses exemplos ilustram opções, não uma estrutura obrigatória. Escolha a organização que torna a skill mais fácil de usar sem carregar material irrelevante.

Criar ou Atualizar uma Skill

Adapte o trabalho à solicitação. Criar uma skill nova complexa pode envolver entender casos de uso realistas, escolher recursos de suporte, inicializar arquivos, escrever instruções e validar o resultado. Uma atualização restrita em uma skill existente pode exigir apenas uma edição focada e validação.

Faça perguntas esclarecedoras apenas quando a informação faltante for importante e não puder ser razoavelmente inferida. Respeite um local especificado pelo usuário; caso contrário, crie skills detectáveis em $CODEX_HOME/skills, ou ~/.codex/skills quando CODEX_HOME não estiver definido.

Mantenha a seleção automática de skills ativada, a menos que o usuário solicite explicitamente uma skill apenas explícita. Quando o modo de invocação pretendido for genuinamente incerto e importante para o fluxo solicitado, pergunte se o usuário deseja descoberta automática normal ou invocação apenas explícita; caso contrário, preserve o padrão. Não infira invocação apenas explícita de operações sensíveis ou aprovações necessárias: mantenha a skill detectável e exija autorização imediatamente antes da mutação real. Preserve a política de invocação de uma skill existente, a menos que o usuário peça para alterá-la.

Para uma skill nova ou substancialmente revisada, considere as solicitações reais que ela deve tratar e quais recursos reutilizáveis melhorariam essas tarefas:

• Uma transformação repetida de PDF pode justificar um auxiliar scripts/rotate_pdf.py.
• Um fluxo de construção de aplicativo pode se beneficiar de um iniciador assets/frontend-template/.
• Uma skill de análise de dados pode precisar de um guia references/schema.md para evitar redescobrir relações de tabelas.

Crie esses recursos apenas quando seu benefício concreto os justificar. Se o usuário já explicou a tarefa claramente, prossiga sem solicitar exemplos adicionais.

Nomenclatura

• Use letras minúsculas, dígitos e hífens.
• Mantenha nomes com menos de 64 caracteres e prefira nomes curtos e orientados à ação.
• Namespace por ferramenta ou domínio quando isso melhorar a descoberta.
• Nomeie a pasta da skill conforme o nome da skill.

Inicializar uma Nova Skill

Para uma skill nova, use o inicializador integrado quando ele ajudar a criar os arquivos necessários de forma consistente:

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

Por exemplo:

scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills"
scripts/init_skill.py my-skill --path "${CODEX_HOME:-$HOME/.codex}/skills" --resources references

Solicite apenas os diretórios de recursos que a skill precisa. Use --examples apenas quando placeholders concretos ajudarem, e substitua ou remova-os antes de finalizar. Não inicialize uma skill existente novamente.

O inicializador cria o diretório da skill, um iniciador conciso de SKILL.md e agents/openai.yaml. Ele cria diretórios de recursos e arquivos de exemplo apenas quando solicitado. Passe valores de interface gerados como --interface chave=valor quando necessário.

Escrever as Instruções

A description do frontmatter deve explicar brevemente o que a skill faz e quando se aplica. Inclua um limite significativo quando solicitações semelhantes não devem ativar a skill.

Por exemplo:

description: Criar ou editar documentos do Word quando formatação, alterações controladas ou comentários exigirem tratamento específico do documento.

Coloque fluxos detalhados, escolhas de ferramentas, exemplos e modos de operação no corpo ou em referências relevantes, em vez de listá-los todos na descrição. Preserve frontmatter opcional suportado, como metadata existente, quando apropriado.

Escreva apenas as instruções necessárias para que outra instância do Codex execute bem a tarefa. Indique o resultado desejado, contexto não óbvio, restrições reais e referências ou ferramentas relevantes. Preserve as escolhas explícitas do usuário e os limites de autorização existentes. Evite prescrever uma estrutura fixa, processo ou número de etapas quando a tarefa não exigir um.

Validar e Iterar

Valide a skill concluída com:

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

O validador verifica frontmatter, nomenclatura e placeholders de esqueleto não finalizados; ele não prova que a skill toma boas decisões. Verifique também se as descrições permanecem discriminativas, as instruções preservam a intenção do usuário, as referências são detectáveis e quaisquer scripts adicionados realmente funcionam.

Quando os testes forem justificados, verifique o comportamento observável ou invariantes significativos. Evite testes que apenas correspondam a redação gerada, cabeçalhos ou padrões de regex.

Melhore a skill com base no uso real ou falhas demonstradas. Prefira uma correção restrita a acumular regras universais para sempre.