Criar competências

Utilize competências de agentes para alargar o Codex com capacidades específicas para cada tarefa. Uma competência agrupa instruções, recursos e scripts opcionais, para que o Codex possa seguir um fluxo de trabalho de forma fiável. As competências baseiam-se na norma aberta de competências de agentes.

As competências são o formato de criação de fluxos de trabalho reutilizáveis. Os plugins distribuem competências e conectores reutilizáveis para o ChatGPT Work na Web e para o ChatGPT Work e o Codex na aplicação de ambiente de trabalho. O Codex CLI também pode instalar plugins. Utilize competências para conceber o fluxo de trabalho propriamente dito e, quando quiser que outras pessoas da sua área de trabalho o possam instalar, empacote-o como um plugin.

As competências estão disponíveis na aplicação de ambiente de trabalho ChatGPT, no Codex CLI e na extensão do IDE.

Na aplicação de ambiente de trabalho ChatGPT, abra Competências na barra lateral para ver e explorar as competências criadas nos seus projetos.

As competências utilizam divulgação progressiva para gerir o contexto de forma eficiente: o Codex começa com o nome, a descrição e o caminho do ficheiro de cada competência. O Codex só carrega as instruções SKILL.md completas quando decide utilizar uma competência.

O Codex inclui no contexto uma lista inicial de competências disponíveis, para poder escolher a competência adequada para uma tarefa. Para evitar ocupar o resto do pedido, esta lista utiliza, no máximo, 2% da janela de contexto do modelo ou 8 000 caracteres quando a janela de contexto é desconhecida. Se estiverem instaladas muitas competências, o Codex encurta primeiro as respetivas descrições. No caso de grandes conjuntos de competências, o Codex poderá omitir algumas da lista inicial e apresentar um aviso.

Este orçamento aplica-se apenas à lista inicial de competências. Quando o Codex seleciona uma competência, continua a ler todas as instruções do SKILL.md dessa competência.

Uma competência é um diretório com um ficheiro SKILL.md, além de scripts e referências opcionais. O ficheiro SKILL.md tem de incluir name e description.

my-skill/
├── SKILL.md          # Required: instructions and metadata
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates and resources
└── agents/
    └── openai.yaml   # Optional: appearance and dependency declarations

Como o Codex utiliza competências

O Codex pode ativar competências de duas formas:

1. Invocação explícita: inclua a competência diretamente no seu pedido. Na CLI/IDE, execute /skills ou escreva $ para mencionar uma competência.
2. Invocação implícita: o Codex pode escolher uma competência quando a sua tarefa corresponder ao description da competência.

Uma vez que a correspondência implícita depende de description, escreva descrições concisas com âmbito e limites claros. Coloque o principal caso de utilização e as palavras acionadoras no início, para que o Codex ainda consiga encontrar a competência caso as descrições sejam encurtadas.

Criar uma competência

Se já conhecer o fluxo de trabalho e for mais fácil mostrá-lo do que descrevê-lo, utilize Gravar e reproduzir. O Codex grava o fluxo de trabalho, inspeciona os passos e cria o rascunho de uma competência reutilizável a partir da demonstração.

Se preferir descrever a competência, utilize o criador incorporado:

$skill-creator

O criador pergunta o que faz a competência, quando deve ser acionada e se deve conter apenas instruções ou incluir scripts. A predefinição é conter apenas instruções.

Também pode criar manualmente uma competência, criando uma pasta com um ficheiro SKILL.md:

---
name: skill-name
description: Explain exactly when this skill should and should not trigger.
---

Skill instructions for Codex to follow.

O Codex deteta automaticamente alterações às competências. Se uma atualização não aparecer, reinicie o Codex.

Onde guardar competências

O Codex lê competências de localizações do repositório, do utilizador, do administrador e do sistema. Nos repositórios, o Codex procura .agents/skills em todos os diretórios, desde o diretório de trabalho atual até à raiz do repositório. Se duas competências partilharem o mesmo name, o Codex não as combina; ambas podem aparecer nos seletores de competências.

O Codex suporta pastas de competências com ligações simbólicas e segue o destino da ligação simbólica ao pesquisar estas localizações.

Estas localizações destinam-se à criação e descoberta local. Quando quiser distribuir competências reutilizáveis para além de um único repositório ou agrupá-las opcionalmente com conectores, utilize plugins.

Distribuir competências com plugins

As pastas de competências diretas são mais adequadas para criação local e fluxos de trabalho limitados ao repositório. Se pretender distribuir uma competência reutilizável, agrupar duas ou mais competências ou fornecer uma competência juntamente com um conector, empacote-as como um plugin.

Os plugins podem incluir uma ou mais competências. Também podem, opcionalmente, agrupar mapeamentos de aplicações, configuração de servidores MCP e recursos de apresentação num único pacote.

Instalar competências selecionadas para utilização local

Para adicionar à sua configuração local do Codex competências selecionadas para além das incorporadas, utilize $skill-installer. Por exemplo, para instalar a competência $linear:

$skill-installer linear

Também pode pedir ao instalador que transfira competências de outros repositórios. O Codex deteta automaticamente as competências recém-instaladas; se alguma não aparecer, reinicie o Codex.

Utilize esta opção para configuração e experimentação locais. Para distribuir de forma reutilizável as suas próprias competências, dê preferência aos plugins.

Ativar ou desativar competências

Utilize entradas [[skills.config]] em ~/.codex/config.toml para desativar uma competência sem a eliminar:

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Reinicie o Codex depois de alterar ~/.codex/config.toml.

Metadados opcionais

Adicione agents/openai.yaml para configurar os metadados da IU na aplicação de ambiente de trabalho ChatGPT, definir a política de invocação e declarar dependências de ferramentas, proporcionando uma experiência mais fluida na utilização da competência.

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 (predefinição: true): quando false, o Codex não invoca implicitamente a competência com base no pedido do utilizador; a invocação explícita $skill continua a funcionar.

Boas práticas

• Mantenha cada competência centrada numa tarefa.
• Prefira instruções a scripts, exceto quando precisar de um comportamento determinístico ou ferramentas externas.
• Escreva passos no imperativo com entradas e saídas explícitas.
• Teste pedidos com a descrição da competência para confirmar o comportamento de acionamento correto.

Para ver mais exemplos, consulte reparação de CI do GitHub, PDF, Linear, openai/skills e a especificação de competências de agentes. Para uma distribuição instalável, prefira plugins.