Empacotar o plugin
Nesta página
Lição reescrita em 3 de novembro de 2026 com base na página Package your plugin da documentação de Plugins da OpenAI. A lição anterior descrevia a criação de um “pacote” para uma “Loja do ChatGPT” inexistente, utilizando um manifesto ausente. Um plugin é empacotado com um manifesto
plugin.jsonque segue o esquema de Agent Plugins. Fonte: Package your plugin.
Por que empacotar
Depois de escrever as suas competências (skills) e, se necessário, construir o servidor MCP, o passo final consiste em reuni-las numa unidade instalável. O empacotamento confere ao seu plugin uma identidade estável e informa o ChatGPT e o Codex sobre quais competências, ligações a servidores MCP e recursos pertencem ao mesmo conjunto. A lógica da interface de utilizador e de autenticação permanece dentro do servidor MCP; o manifesto limita-se a ligar essa integração ao restante pacote.
Estrutura de um pacote portátil
Um plugin portátil possui um manifesto plugin.json na sua raiz, declarando o esquema de Agent Plugins. A pasta pode também conter um diretório skills/, um ficheiro mcp.json para servidores MCP distribuídos com o plugin e recursos visuais em assets/.
mon-plugin/
├── plugin.json
├── mcp.json
├── skills/
│ └── compte-rendu/
│ └── SKILL.md
└── assets/
├── icon.png
└── logo.png
O manifesto mínimo cabe em apenas algumas linhas. O nome, estável e em kebab-case, serve simultaneamente como identificador e espaço de nomes para os componentes; as competências são descobertas automaticamente em skills/ sem necessidade de declaração explícita.
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "notes-equipe",
"version": "0.1.0",
"description": "Team notes and meeting minutes"
}
Cada competência reside em skills/<nome>/SKILL.md, com um cabeçalho que fornece o seu nome e descrição, seguido das instruções:
---
name: compte-rendu
description: Drafts meeting minutes from team notes.
---
Retrieve meeting notes using list_notes, group them by topic,
then draft a summary: decisions, action items with owners, and open points.
Declarar o servidor MCP
Os servidores MCP distribuídos com o plugin são declarados em mcp.json na raiz, utilizando o esquema correspondente e especificando um tipo de transporte para cada servidor:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
"mcpServers": {
"notes": {
"type": "streamable-http",
"url": "https://notes.example.com/mcp"
}
}
}
A autenticação do servidor é declarada neste mesmo ficheiro, sob extensions["com.openai"].auth para cada servidor — pertence ao servidor, não ao manifesto. Para submissão pública, submete o endpoint HTTPS remoto; os servidores locais seguem um caminho separado, reservado a plugins de ambiente de trabalho.
Metadados específicos da OpenAI
A apresentação do diretório, os mapeamentos para servidores MCP já registados e os ganchos (hooks) são declarados no objeto extensions.com.openai do ficheiro plugin.json da raiz, enquanto a identidade portátil (name, version, description) permanece na raiz:
{
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
"name": "notes-equipe",
"version": "0.1.0",
"description": "Team notes and meeting minutes",
"extensions": {
"com.openai": {
"interface": {
"displayName": "Team Notes",
"shortDescription": "Notes and meeting minutes",
"developerName": "Your Team",
"category": "Productivity",
"capabilities": ["Read", "Write"],
"websiteURL": "https://example.com",
"privacyPolicyURL": "https://example.com/privacy",
"termsOfServiceURL": "https://example.com/terms",
"defaultPrompt": ["Use Team Notes to draft Monday's meeting minutes."],
"composerIcon": "./assets/icon.png",
"logo": "./assets/logo.png"
}
}
}
}
Os caminhos neste objeto são relativos à raiz do plugin e começam por ./. Os recursos visuais (composerIcon, logo, screenshots) devem preferencialmente ficar em ./assets/. O campo apps utiliza-se apenas para apontar para um ficheiro .app.json contendo mapeamentos para servidores MCP já registados no ChatGPT.
Pode também declarar uma competência de integração (onboarding skill) através de extensions.com.openai.onboardingSkill (por exemplo, ./skills/setup/SKILL.md): esta guia o utilizador após a instalação para escolher um espaço de trabalho ou definir preferências. Teste-a numa nova conversa e durante uma instalação em curso.
Um formato mais antigo, com um manifesto em .codex-plugin/plugin.json, ainda é aceite para compatibilidade: só é utilizado se o objeto extensions.com.openai estiver ausente, pois os dois não se fundem. Os novos pacotes devem utilizar o plugin.json da raiz.
A via rápida: @plugin-creator
O ChatGPT e o Codex incluem uma competência, @plugin-creator, que gera a estrutura para si — atualmente no formato de compatibilidade .codex-plugin/. Para ligar um servidor MCP ao mesmo, ligue primeiro esse servidor no ChatGPT (Add custom MCP server, depois Create as a plugin), anote o ID técnico da ligação a partir do URL do navegador — começa por plugin_asdk_app — e forneça-o ao @plugin-creator no modo Work (ou ao $plugin-creator no Codex). A competência pode também criar uma entrada de mercado pessoal, permitindo-lhe instalar e testar o plugin a partir da sua origem de diretório local.
Mercados locais
Um mercado é um catálogo JSON de plugins. Serve para escrita, testes e distribuição em equipa, paralelamente ao diretório público: no modo Work ou no Codex, cada mercado aparece como uma fonte selecionável no diretório de plugins. É assim que testará o plugin completo antes de o submeter (Lição 9).
Ganchos: apenas para ambiente de trabalho
Os ganchos de ciclo de vida (lifecycle hooks) são suportados apenas para plugins instalados manualmente na aplicação de ambiente de trabalho Codex, e um plugin que os contenha não é elegível para o diretório público. Se o seu plugin tiver como alvo a publicação, omita-os.
Pontos-chave
- Um pacote portátil:
plugin.json(esquema Agent Plugins),skills/,mcp.json,assets/ - O servidor MCP é declarado em
mcp.jsoncom o seu tipo de transporte; a autenticação também vai para lá - A apresentação, os mapeamentos e a competência de integração vão para
extensions.com.openai @plugin-creatorgera a estrutura; um mercado local serve para testes- Um plugin com ganchos não é elegível para o diretório público