Criar habilidades

Uma habilidade complementa seu servidor MCP ao ensinar o ChatGPT e o Codex a usar suas ferramentas em um fluxo de trabalho repetível. Use o servidor para dados em tempo real, autenticação, autorização e ações controladas. Use a habilidade para sequências de uso de ferramentas, pontos de decisão, requisitos de saída, exemplos, modelos e outras orientações reutilizáveis.

Um plug-in pode conter uma habilidade ou um grupo de habilidades relacionadas. Mantenha cada habilidade focada em um objetivo claro do usuário presente no seu inventário de casos de uso. Uma habilidade também pode funcionar sem um servidor MCP quando o fluxo de trabalho precisa apenas das instruções e dos recursos incluídos no pacote.

Crie uma habilidade

A maneira mais rápida de começar é usar o criador de habilidades integrado. Descreva o objetivo do usuário e as ferramentas MCP que ajudam a alcançá-lo:

@skill-creator Create a skill named tabletop-dice that understands dice
notation such as 3d6, calls roll_dice once for each die, and reports every
roll and the total.

No Codex, invoque o mesmo criador usando $skill-creator.

Você também pode criar os arquivos manualmente. Cada habilidade fica em seu próprio diretório e exige um arquivo SKILL.md:

Escreva o SKILL.md

Comece o arquivo com um nome e uma descrição, seguidos das instruções:

---
name: tabletop-dice
description: Roll one or more dice for tabletop games and report each result and the total.
---

Use this skill when the user asks to roll dice.

1. Parse requests written as `NdS` as N dice with S sides. For example, `3d6`
   means three six-sided dice.
2. Call `roll_dice` once for each requested die and pass S as `sides`.
3. Report each tool result in order.
4. When the user requests multiple dice, add the results and report the total.

Do not invent, replace, or reroll a result unless the user asks you to.

A descrição determina quando o modelo considera usar a habilidade. Descreva o fluxo de trabalho e as condições que devem acioná-lo. Coloque no corpo as instruções detalhadas sobre procedimentos, formato e segurança.

Defina o escopo do fluxo de trabalho

Associe cada habilidade a um ou mais casos de uso. As instruções devem deixar claro:

• Quais dados de entrada o fluxo de trabalho espera.
• Quais etapas o modelo deve seguir.
• Qual resultado o usuário deve receber.
• Quais fatos o modelo não deve inferir.
• Quando o fluxo de trabalho deve fazer uma pergunta, parar ou recusar uma solicitação.
• Quais arquivos de apoio o modelo deve consultar.

Prefira uma habilidade focada a uma grande coleção de instruções com pouca relação entre si. Separe os fluxos de trabalho quando eles tiverem diferentes condições de acionamento, dados de entrada ou critérios de sucesso.

Revise como as instruções são seguidas

Ao criar ou importar habilidades para o GPT-6 Astra, consulte as orientações sobre como seguir instruções. Verifique se há instruções pouco claras ou conflitantes nas habilidades e nos arquivos de apoio e deixe claro que as instruções explícitas do usuário têm prioridade sobre as diretrizes das habilidades.

Adicione recursos de apoio

Mantenha o SKILL.md conciso e coloque o material detalhado em arquivos junto dele:

• Use references/ para políticas, esquemas, exemplos e material de contextualização.
• Use assets/ para modelos ou arquivos que o fluxo de trabalho deve copiar ou transformar.
• Use scripts/ quando o fluxo de trabalho precisar de computação determinística ou processamento de arquivos.

Referencie os arquivos de apoio no SKILL.md e explique quando carregá-los ou executá-los. Não adicione um script quando as instruções e as ferramentas existentes puderem concluir a tarefa de forma confiável.

Conecte habilidades a ferramentas MCP

Uma habilidade pode orientar o modelo no uso das ferramentas disponibilizadas pelo servidor MCP do plug-in. Use a habilidade para instruções do fluxo de trabalho e o servidor para dados em tempo real, autorização e ações controladas.

Se uma habilidade exigir um servidor MCP, declare a dependência em agents/openai.yaml:

dependencies:
  tools:
    - type: "mcp"
      value: "dice-roller"
      description: "Roll an N-sided die"
      transport: "streamable_http"
      url: "https://tinymcp.dev/api/moldy-aloof-zettabyte/mcp"

Importe uma habilidade via MCP

Você pode fazer upload de uma habilidade empacotada durante a submissão ou importá-la do servidor MCP do plug-in. A opção via MCP mantém as instruções e os arquivos de apoio da habilidade junto com a implantação do servidor.

A OpenAI importa habilidades via MCP quando você seleciona Verificar ferramentas no portal de submissão de plug-ins. Os arquivos importados ficam salvos como uma cópia estática no rascunho; o ChatGPT e o Codex não os buscam no seu servidor MCP em tempo de execução. Após alterar a habilidade, implante o servidor e faça a verificação novamente antes de submeter uma nova versão do plug-in.

Para saber mais sobre a declaração de capacidades, os métodos de descoberta, o manifesto de recursos e os limites de importação, consulte Importar habilidades do servidor MCP.

Teste a habilidade

Teste com solicitações representativas do inventário de casos de uso:

1. Solicitações diretas que devem ativar a habilidade.
2. Solicitações indiretas que expressam o mesmo objetivo.
3. Dados de entrada incompletos que devem levar a uma pergunta de esclarecimento.
4. Solicitações que não devem ativar a habilidade.
5. Casos extremos em que a habilidade deve evitar inventar informações ou realizar uma ação não suportada.

Avalie tanto a ativação quanto a qualidade dos resultados. Ajuste a descrição quando a habilidade for ativada no momento errado. Ajuste as instruções quando ela escolher o fluxo de trabalho correto, mas produzir um resultado inconsistente.

Empacote a habilidade

Aponte o manifesto do plug-in para o diretório de habilidades:

{
  "name": "dice-roller",
  "version": "1.0.0",
  "description": "Roll dice for tabletop games",
  "skills": "./skills/",
  "apps": "./.app.json"
}

Consulte Empacotar seu plug-in para ver o manifesto completo, o mapeamento do servidor MCP, os testes locais e o fluxo de distribuição.