Crie habilidades

Uma habilidade complementa seu servidor MCP ao ensinar o ChatGPT e o Codex a usar as ferramentas do servidor em um fluxo de trabalho repetível. Use o servidor para acessar dados em tempo real, autenticar usuários, verificar autorizações e executar ações controladas. Use a habilidade para definir a sequência de uso das ferramentas, os pontos de decisão e os requisitos de saída, além de fornecer exemplos, modelos e outras orientações reutilizáveis.

Um plugin pode conter uma habilidade ou um conjunto de habilidades relacionadas. Cada habilidade deve atender a um objetivo claro do usuário, identificado no seu inventário de casos de uso. Uma habilidade também pode funcionar sem um servidor MCP quando o fluxo de trabalho exige apenas as instruções e os 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 Crie uma habilidade chamada tabletop-dice que interprete notações
de lançamento de dados, como 3d6, chame roll_dice uma vez por dado e informe
o resultado de cada lançamento e o total.

No Codex, use $skill-creator para chamar o mesmo criador.

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

Escreva o arquivo SKILL.md

Comece o arquivo com um nome e uma descrição. Em seguida, escreva as instruções.

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

Use esta habilidade quando o usuário pedir para lançar dados.

1. Interprete a notação `NdS` como um pedido para lançar N dados de S faces cada.
   Por exemplo, `3d6` significa três dados de seis faces.
2. Chame `roll_dice` uma vez para cada dado solicitado e passe S como valor de `sides`.
3. Informe os resultados na ordem em que a ferramenta os retornar.
4. Quando o usuário pedir mais de um dado, some os resultados e informe o total.

Não invente nem substitua resultados e não repita um lançamento, a menos que o usuário peça.

A descrição determina quando o modelo considera usar a habilidade. Descreva o fluxo de trabalho e as condições que devem acioná-lo. No corpo do arquivo, detalhe o procedimento, o formato e as instruções de segurança.

Delimite o escopo do fluxo de trabalho

Associe cada habilidade a um ou mais casos de uso. Responda às seguintes perguntas nas instruções.

• 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 pode inferir?
• Quando o fluxo de trabalho deve fazer uma pergunta, parar ou recusar a solicitação?
• Quais arquivos de apoio o modelo deve consultar?

Prefira uma habilidade com um objetivo específico a uma coleção extensa de instruções com pouca relação entre si. Separe os fluxos de trabalho quando eles tiverem condições de ativação, entradas ou critérios de sucesso diferentes.

Revise as orientações sobre como o modelo segue instruções

Ao escrever ou importar habilidades para o GPT-6 Astra, consulte as orientações sobre como o modelo segue instruções. Revise as habilidades e os arquivos de apoio para identificar instruções pouco claras ou conflitantes. Deixe claro que as instruções explícitas do usuário têm prioridade sobre as diretrizes da habilidade.

Adicione recursos de apoio

Mantenha o arquivo SKILL.md conciso e organize o material detalhado em subdiretórios ao lado dele.

• Use references/ para políticas, schemas, 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 exigir cálculos determinísticos ou processamento de arquivos.

Indique os arquivos de apoio em SKILL.md e explique quando carregá-los ou executá-los. Não adicione um script se as instruções e as ferramentas existentes já permitirem 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 plugin. Use a habilidade para definir as instruções do fluxo de trabalho e o servidor para acessar dados em tempo real, verificar autorizações e executar 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"

Teste a habilidade

Teste a habilidade 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. Entradas incompletas que devem levar o modelo a pedir esclarecimentos.
4. Solicitações que não devem ativar a habilidade.
5. Casos extremos em que a habilidade deve evitar inventar informações ou executar uma ação sem suporte.

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

Empacote a habilidade

Indique o diretório de habilidades no manifesto do plugin.

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

Consulte Empacote seu plugin para ver o manifesto completo, o mapeamento do servidor MCP, as instruções para testes locais e o processo de distribuição.