Use habilidades de agente para ampliar os recursos do ChatGPT e do Codex em tarefas específicas. Cada habilidade reúne instruções, recursos e scripts opcionais para que qualquer um dos dois produtos possa seguir um fluxo de trabalho de forma consistente. As habilidades seguem o padrão aberto de habilidades de agente.
As habilidades são o formato usado para criar fluxos de trabalho reutilizáveis. Os plugins distribuem habilidades reutilizáveis e conectores pelo diretório universal de plugins que o ChatGPT e o Codex compartilham. Os plugins funcionam nos modos Chat e Work do ChatGPT na Web, no computador e em dispositivos móveis. Também funcionam no Codex pelo aplicativo do ChatGPT para computador e pela CLI do Codex. Use uma habilidade para definir o fluxo de trabalho e, quando quiser que outras pessoas possam instalá-la, distribua-a como um plugin.
As habilidades independentes estão disponíveis no aplicativo do ChatGPT para computador, na CLI do Codex e na extensão para IDE. As habilidades incluídas em plugins também estão disponíveis nos modos Chat e Work do ChatGPT na Web, no computador e em dispositivos móveis.
No aplicativo do ChatGPT para computador, abra Habilidades na barra lateral para ver e explorar as habilidades criadas nos seus projetos.
As habilidades usam divulgação progressiva para aproveitar melhor o contexto disponível. O ChatGPT e o Codex começam pelo nome e pela descrição de cada habilidade. Quando decidem usar uma delas, carregam as instruções completas do arquivo SKILL.md.
No Codex, a lista inicial também inclui o caminho do arquivo de cada habilidade. Por padrão, essa lista ocupa no máximo 2% da janela de contexto do modelo. Quando o tamanho da janela é desconhecido, o limite é de 8.000 caracteres. Se houver muitas habilidades instaladas, o Codex primeiro encurta as descrições. Se o conjunto de habilidades for muito grande, o Codex poderá omitir algumas delas da lista inicial e exibir um aviso.
Use skills.max_context_tokens para definir outro limite, de até 10.000 tokens.
Esse limite se aplica apenas à lista inicial de habilidades. Quando o Codex seleciona uma habilidade, ele lê todas as instruções do arquivo SKILL.md correspondente.
Uma habilidade é um diretório que contém um arquivo SKILL.md e, opcionalmente, scripts e referências. O arquivo SKILL.md deve incluir os campos name e description.
-
my-skill/
- SKILL.md Obrigatório: instruções e metadados
- scripts/ Opcional: código executável
- references/ Opcional: documentação
- assets/ Opcional: modelos e recursos
-
agents/
- openai.yaml Opcional: aparência e dependências
-
-
Como o ChatGPT e o Codex usam habilidades
O ChatGPT e o Codex podem ativar habilidades de duas maneiras:
- Invocação explícita: inclua a habilidade diretamente no prompt. No ChatGPT, digite
@para selecionar uma habilidade. Na CLI do Codex ou na extensão para IDE, execute/skillsou digite$para mencionar uma habilidade. - Invocação implícita: o ChatGPT ou o Codex pode escolher uma habilidade quando a tarefa corresponde ao que está descrito no campo
description.
Como a seleção implícita depende de description, escreva descrições concisas que deixem claro o que a habilidade cobre e quais são seus limites. Comece pelo principal caso de uso e pelas palavras que acionam a habilidade. Assim, o host consegue identificar a habilidade adequada mesmo que as descrições sejam encurtadas.
Criar uma habilidade
Se você já conhece o fluxo de trabalho e acha mais fácil demonstrá-lo do que descrevê-lo, use o recurso Gravar e reproduzir. O gravador registra o fluxo, analisa as etapas e cria um rascunho de habilidade reutilizável a partir da demonstração.
Se preferir descrever a habilidade, use o criador integrado. No ChatGPT Work, use @skill-creator para acioná-lo. No Codex, use:
$skill-creatorO criador pergunta o que a habilidade faz, quando ela deve ser acionada e se deve conter apenas instruções ou incluir scripts. Por padrão, ela contém apenas instruções.
Você também pode criar uma habilidade manualmente. Para isso, crie uma pasta com um arquivo SKILL.md:
---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---
Skill instructions for ChatGPT or Codex to follow.O Codex detecta automaticamente as alterações nas habilidades. Se uma atualização não aparecer, reinicie o Codex.
Onde o Codex busca habilidades locais
O Codex lê habilidades nos locais definidos para o repositório, o usuário, o administrador e o sistema. Em um repositório, o Codex procura a pasta .agents/skills em cada diretório, desde o diretório de trabalho atual até a raiz do repositório. Se duas habilidades tiverem o mesmo name, o Codex as mantém separadas. Ambas podem aparecer nos seletores de habilidades.
| Escopo da habilidade | Local | Uso sugerido |
|---|---|---|
REPO |
$CWD/.agents/skills Diretório de trabalho atual, onde você inicia o Codex. |
Em um repositório ou ambiente de desenvolvimento, a equipe pode versionar habilidades específicas de uma pasta de trabalho. Por exemplo, habilidades que só se aplicam a um microsserviço ou módulo. |
REPO |
$CWD/../.agents/skills Pasta um nível acima do diretório de trabalho atual quando você inicia o Codex em um repositório Git. |
Em repositórios com pastas aninhadas, a organização pode versionar na pasta pai as habilidades que se aplicam a uma área compartilhada. |
REPO |
$REPO_ROOT/.agents/skills Pasta raiz do repositório Git em que você inicia o Codex. |
Em repositórios com pastas aninhadas, a organização pode versionar habilidades relevantes para todos que usam o repositório. Essas habilidades da raiz ficam disponíveis em todas as subpastas do repositório. |
USER |
$HOME/.agents/skills Habilidades versionadas na pasta pessoal do usuário. |
Use esse local para reunir habilidades que o usuário pode usar em qualquer repositório em que trabalhar. |
ADMIN |
/etc/codex/skills Habilidades versionadas em um local compartilhado do sistema, na máquina ou no contêiner. |
Use esse local para scripts do SDK, automação e versionamento das habilidades padrão que o administrador disponibiliza para todos os usuários da máquina. |
SYSTEM |
Incluídas pela OpenAI na distribuição do Codex. | As habilidades do sistema incluem skill-creator e skill-installer e vêm ativadas por padrão. |
O Codex aceita links simbólicos para pastas de habilidades e segue esses links ao examinar os locais acima.
Esses locais servem para criar e localizar habilidades no ambiente local. Para distribuir habilidades reutilizáveis além de um único repositório, com ou sem conectores, use plugins.
Distribuir habilidades com plugins
Trabalhar diretamente com as pastas das habilidades é a melhor opção para criar habilidades localmente e definir fluxos de trabalho específicos de um repositório. Para distribuir uma habilidade reutilizável, reunir duas ou mais habilidades ou distribuir uma habilidade junto com um conector, crie um plugin.
Um plugin pode incluir uma ou mais habilidades. Também pode reunir, no mesmo pacote, conexões registradas com servidores MCP, configurações de servidores MCP e recursos de apresentação.
Instalar habilidades selecionadas para uso local
Para adicionar habilidades selecionadas além das que já vêm com o Codex na sua instalação local, use $skill-installer. Por exemplo, para instalar a habilidade $linear, execute:
$skill-installer linearVocê também pode pedir ao instalador que baixe habilidades de outros repositórios. O Codex detecta automaticamente as novas habilidades instaladas. Se alguma não aparecer, reinicie o Codex.
Use o instalador para configurar seu ambiente local e experimentar habilidades. Para distribuir suas próprias habilidades e permitir que outras pessoas as reutilizem, prefira os plugins.
Ativar ou desativar habilidades locais do Codex
Use entradas [[skills.config]] em ~/.codex/config.toml para desativar uma habilidade sem excluí-la:
[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = falseUse exatamente um seletor por entrada. Um caminho absoluto em path seleciona um único arquivo SKILL.md. O seletor name seleciona todas as habilidades com o nome informado. Se mais de uma entrada se aplicar à mesma habilidade, prevalece a última delas.
Para desativar todas as habilidades de sistema incluídas no Codex apenas no projeto atual, adicione esta configuração ao arquivo .codex/config.toml de confiança do projeto:
[skills.bundled]
enabled = falseReinicie o Codex após alterar a configuração.
Metadados opcionais
Adicione agents/openai.yaml para configurar os metadados da interface no aplicativo do ChatGPT para computador, definir a política de invocação e declarar de quais ferramentas a habilidade depende. Essas configurações facilitam o uso da habilidade.
interface:
display_name: "Optional user-facing name"
short_description: "Optional user-facing description"
icon_small: "./assets/small-logo.svg"
icon_large: "./assets/large-logo.png"
brand_color: "#3B82F6"
default_prompt: "Optional surrounding prompt to use the skill with"
policy:
allow_implicit_invocation: false
dependencies:
tools:
- type: "mcp"
value: "openaiDeveloperDocs"
description: "OpenAI Docs MCP server"
transport: "streamable_http"
url: "https://developers.openai.com/mcp"allow_implicit_invocation (padrão: true): quando o valor é false, o Codex não aciona a habilidade implicitamente com base no prompt do usuário. A invocação explícita com $skill continua funcionando.
Boas práticas
- Concentre cada habilidade em uma única tarefa.
- Prefira instruções a scripts, a menos que você precise de comportamento determinístico ou de ferramentas externas.
- Escreva as etapas no imperativo e especifique as entradas e saídas.
- Teste prompts com base na descrição da habilidade para confirmar que ela é acionada nas situações previstas.
Para ver mais exemplos, consulte Correção de falhas de CI no GitHub, PDF, Linear, openai/skills e a especificação de habilidades de agente. Para distribuir habilidades que outras pessoas possam instalar, prefira os plugins.