Documentação do ChatGPT
Português
Contacto goolvyouyou@gmail.com

Criar competências

Criar competências

Dê novas capacidades e conhecimentos especializados ao Codex

Utilize competências de agente para ampliar o ChatGPT e o Codex com capacidades específicas de cada tarefa. Uma competência reúne instruções, recursos e scripts opcionais para que qualquer um dos produtos 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 através do diretório universal de plugins partilhado pelo ChatGPT e pelo Codex. Os plugins funcionam no Chat e no Work no ChatGPT na Web, no computador e em dispositivos móveis, no Codex na aplicação ChatGPT para computador e através da Codex CLI. Utilize competências para conceber o próprio fluxo de trabalho e, em seguida, empacote-o como um plugin quando pretender que outras pessoas o instalem.

As competências autónomas estão disponíveis na aplicação ChatGPT para computador, na Codex CLI e na extensão do IDE. As competências incluídas em plugins também estão disponíveis no Chat e no Work no ChatGPT na Web, no computador e em dispositivos móveis.

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

Seletor de Skills que mostra as competências disponíveis na aplicação ChatGPT para computador (modo claro)
As competências utilizam **divulgação progressiva** para gerir o contexto de forma eficiente. O ChatGPT e o Codex começam pelo nome e pela descrição de cada competência e, em seguida, carregam as instruções completas de `SKILL.md` quando decidem utilizar essa competência.

No Codex, a lista inicial também inclui o caminho do ficheiro de cada competência. Para evitar ocupar o espaço destinado ao resto do pedido, esta lista utiliza, no máximo, 2% da janela de contexto do modelo ou 8 000 carateres quando a janela de contexto é desconhecida. Se estiverem instaladas muitas competências, o Codex começa por abreviar as descrições das competências. Em conjuntos grandes de competências, o Codex pode 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.

Como o ChatGPT e o Codex utilizam competências

O ChatGPT e o Codex podem ativar competências de duas formas:

  1. Invocação explícita: Inclua a competência diretamente no seu pedido. No ChatGPT, escreva @ para selecionar uma competência. Na Codex CLI ou na extensão do IDE, execute /skills ou escreva $ para mencionar uma competência.
  2. Invocação implícita: O ChatGPT ou o Codex podem escolher uma competência quando a sua tarefa corresponde à description da competência.

Como a correspondência implícita depende de description, escreva descrições concisas com um âmbito e limites claros. Coloque primeiro o principal caso de utilização e as palavras acionadoras para que um anfitrião consiga ainda fazer corresponder a competência caso as descrições sejam abreviadas.

Criar uma competência

Se já conhece o fluxo de trabalho e é mais fácil mostrá-lo do que descrevê-lo, utilize Gravar e reproduzir. O gravador captura o fluxo de trabalho, inspeciona os passos e elabora uma competência reutilizável a partir da demonstração.

Se preferir descrever a competência, utilize o criador integrado. No ChatGPT Work, invoque-o como @skill-creator. No Codex, invoque-o assim:

$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 ChatGPT or Codex to follow.

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

Onde o Codex carrega as competências locais

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.

Âmbito da competência Localização Utilização sugerida
REPO $CWD/.agents/skills
Diretório de trabalho atual: onde inicia o Codex.		 Se estiver num repositório ou ambiente de código, as equipas podem arquivar competências relevantes para uma pasta de trabalho. Por exemplo, competências relevantes apenas para um microsserviço ou módulo.
REPO $CWD/../.agents/skills
Uma pasta acima de CWD quando inicia o Codex dentro de um repositório Git.		 Se estiver num repositório com pastas aninhadas, as organizações podem arquivar competências relevantes para uma área partilhada numa pasta principal.
REPO $REPO_ROOT/.agents/skills
A pasta raiz superior quando inicia o Codex dentro de um repositório Git.		 Se estiver num repositório com pastas aninhadas, as organizações podem arquivar competências relevantes para todos os utilizadores do repositório. Estas funcionam como competências de raiz disponíveis em qualquer subpasta do repositório.
USER $HOME/.agents/skills
Quaisquer competências arquivadas na pasta pessoal do utilizador.		 Utilize esta localização para selecionar competências relevantes para um utilizador e aplicáveis a qualquer repositório em que este possa trabalhar.
ADMIN /etc/codex/skills
Quaisquer competências arquivadas na máquina ou no contentor, numa localização partilhada do sistema.		 Utilize-a para scripts do SDK, automatização e para arquivar competências administrativas predefinidas disponíveis para todos os utilizadores da máquina.
SYSTEM Incluídas com o Codex pela OpenAI. Competências úteis para um público abrangente, como as competências skill-creator e plan. Disponíveis para todos quando iniciam o Codex.

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 pretender distribuir competências reutilizáveis para além de um único repositório ou, opcionalmente, agrupá-las com conectores, utilize plugins.

Distribuir competências com plugins

As pastas de competências diretas são mais adequadas para a criação local e para fluxos de trabalho específicos de um repositório. Se pretender distribuir uma competência reutilizável, agrupar duas ou mais competências ou disponibilizar 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 ligações registadas a servidores MCP, a configuração de servidores MCP incluídos 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 locais do Codex

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 obter mais exemplos, consulte reparação da CI do GitHub, PDF, Linear, openai/skills e a especificação de competências de agentes. Para uma distribuição instalável, dê preferência a plugins.