Os requisitos para plugins enviados ao diretório público são mais rigorosos do que os aplicáveis a plugins instalados em um espaço de trabalho. Para entrar no diretório, o plugin precisa passar pelas verificações comuns a todos os pacotes e por verificações adicionais dos campos da página do plugin, dos materiais para revisão, das ferramentas MCP, das habilidades, dos recursos e das imagens. Esta referência também aborda verificações comuns a todos os pacotes, como as de referências a servidores MCP, que podem ocorrer fora do portal de envio.
Use o código de erro retornado durante o envio para localizar o requisito correspondente. Os erros impedem o envio. Os avisos permitem prosseguir, mas você deve revisá-los antes de continuar.
Um valor que precisa ser preenchido não pode conter apenas espaços em branco. O texto aceito não pode conter caracteres de controle, separadores Unicode de linha ou de parágrafo nem caracteres invisíveis de formatação incompatíveis. As URLs HTTPS devem incluir um host e não podem conter credenciais embutidas nem caracteres incompatíveis.
Envio final ao diretório
Um pacote pode passar na validação do upload e ainda assim falhar no envio final ao diretório. Nessa etapa, os campos da página do plugin têm limites mais rigorosos. O portal também verifica a configuração do MCP, os resultados das varreduras das habilidades, os casos de teste e as declarações de conformidade com as políticas.
| Campo | Regra para o envio final |
|---|---|
| Nome do pacote | Obrigatório. Use até 64 caracteres. Comece com uma letra ou um dígito ASCII e use apenas letras e dígitos ASCII, _ e -. |
| Versão | Obrigatória. Use uma versão semântica de até 64 caracteres. |
| Nome de exibição | Obrigatório. Use uma única linha de até 30 caracteres. |
| Descrição curta | Obrigatória. Use uma única linha de até 30 caracteres. |
| Descrição longa | Obrigatória. Use até 4.000 caracteres. São permitidas quebras de linha. |
| Nome do desenvolvedor | Obrigatório. Use uma única linha de até 80 caracteres. |
| Categoria | Obrigatória. Escolha uma das categorias aceitas na seção Erros na página do plugin e na interface. |
| Funcionalidades | No máximo 20. Descreva cada funcionalidade em uma única linha não vazia de até 120 caracteres. |
| Prompts iniciais | No máximo 3. Cada prompt deve ter conteúdo, ocupar uma única linha de até 128 caracteres e ser único após a normalização Unicode e a normalização dos espaços em branco. Não pode conter @mention de servidor MCP. |
| URLs | Obrigatórias para o envio de servidores MCP remotos e opcionais para uploads de ZIP de plugins que contêm apenas habilidades. As URLs do site, do suporte, da política de privacidade e dos termos devem usar HTTPS e ter até 1.024 caracteres cada. |
| Cores da marca | Opcionais. Use cores em formato hexadecimal de seis dígitos. A cor clara deve ter contraste mínimo de 2:1 com o branco, e a escura, de 2:1 com #212121. |
Para enviar qualquer plugin, você também precisa atender aos seguintes requisitos:
- Cada habilidade incluída no pacote deve passar nas varreduras de segurança de uso e de segurança da informação. As varreduras podem levar até 2 horas.
- A identidade do desenvolvedor ou da empresa deve estar verificada, e você deve fornecer todas as declarações obrigatórias de conformidade com as políticas.
Para o envio final de um plugin com MCP remoto, você também precisa fornecer:
- URLs do site, do suporte, da política de privacidade e dos termos que atendam às regras acima.
- Uma URL para a gravação de uma demonstração dos principais casos de uso e ferramentas nas plataformas compatíveis.
- Exatamente cinco casos de teste positivos, três casos de teste negativos e as notas da versão.
- Uma URL HTTPS do servidor MCP de produção, um desafio de verificação de domínio concluído e uma varredura atual das ferramentas concluída com sucesso.
- Valores explícitos para
readOnlyHint,openWorldHintedestructiveHintem cada ferramenta MCP, com uma justificativa para cada valor. - Credenciais de demonstração prontas para uso pela equipe de revisão, caso o servidor use OAuth.
Erros nos metadados do envio final
Nos nomes desses erros, subtitle corresponde à descrição curta e description à descrição longa.
| Nome | Requisito |
|---|---|
submission_display_name_required |
O nome de exibição é obrigatório e deve ser preenchido em uma única linha. |
submission_display_name_too_long |
O nome de exibição deve ter até 30 caracteres. |
submission_display_name_character_unsupported |
O nome de exibição deve conter apenas texto aceito e ocupar uma única linha. |
submission_subtitle_required |
A descrição curta é obrigatória e deve ser preenchida em uma única linha. |
submission_subtitle_too_long |
A descrição curta deve ter até 30 caracteres. |
submission_subtitle_character_unsupported |
A descrição curta deve conter apenas texto aceito e ocupar uma única linha. |
submission_description_required |
A descrição longa é obrigatória e não pode ficar vazia. São permitidas quebras de linha. |
submission_description_too_long |
A descrição longa deve ter até 4.000 caracteres. |
submission_description_character_unsupported |
A descrição longa deve conter apenas texto aceito. São permitidas quebras de linha. |
submission_developer_name_required |
O nome do desenvolvedor é obrigatório e deve ser preenchido em uma única linha. |
submission_developer_name_too_long |
O nome do desenvolvedor deve ter até 80 caracteres. |
submission_developer_name_character_unsupported |
O nome do desenvolvedor deve conter apenas texto aceito e ocupar uma única linha. |
plugin_capability_invalid |
A descrição de cada funcionalidade deve ter conteúdo, usar apenas texto aceito e ocupar uma única linha de até 120 caracteres. |
plugin_default_prompt_mention |
Os prompts iniciais não podem conter @mentions de servidores MCP. |
plugin_default_prompt_duplicate |
Os prompts iniciais devem ser únicos após a normalização Unicode e a normalização dos espaços em branco. |
Erros de MCP e de revisão
Esses erros se aplicam ao envio de servidores MCP remotos.
| Nome | Requisito |
|---|---|
annotations_required |
Cada ferramenta MCP deve definir readOnlyHint, openWorldHint e destructiveHint de acordo com seu comportamento. |
justification_required |
Cada anotação de uma ferramenta MCP deve justificar o valor que indica se a ferramenta é somente leitura, interage com o mundo externo ou realiza ações destrutivas. |
scan_required |
As ferramentas MCP devem ter passado por uma varredura atual e bem-sucedida no servidor MCP de produção. |
domain_verification_required |
Hospede o token de verificação exato na URL /.well-known/openai-apps-challenge gerada no host do MCP ou em um host pai permitido. A etapa Verificar domínio deve ser concluída com sucesso. |
frame_domain_explanation_required |
Para cada domínio externo de frame identificado pela varredura das ferramentas MCP, explique por que a interface precisa dele e que conteúdo ele fornece. |
Erros no arquivo compactado
Erros e avisos no upload de ZIP
A opção Somente habilidades do portal aceita pacotes ZIP de habilidades e plugins MCP locais aprovados. Os plugins MCP locais aprovados não precisam incluir habilidades. Os erros impedem o upload. Os avisos exigem confirmação.
| Nome | Requisito |
|---|---|
plugin_name_mismatch |
Em uma atualização, o nome do pacote deve corresponder ao nome do plugin existente. |
plugin_version_unchanged |
Para uma nova versão, altere o valor de version no manifesto. Reutilizar a versão publicada exige confirmação. |
mcp_configuration_excluded |
O portal exclui a configuração do MCP, a menos que sua organização tenha aprovação para enviar plugins MCP locais. Para enviar um plugin MCP local, peça ao seu representante da OpenAI que confirme se a organização responsável pelo envio está na lista de organizações autorizadas. Envie servidores MCP remotos pela opção Com MCP. |
app_configuration_excluded |
Os arquivos ZIP enviados não podem incluir apps nem .app.json. Envie servidores MCP remotos pela opção Com MCP. Para servidores MCP locais, siga as instruções de envio exclusivo para desktop. |
claude_format_normalized |
O portal converte .claude-plugin/plugin.json em .codex-plugin/plugin.json, preenche os valores padrão ausentes da interface e adiciona os campos de texto normalizados. |
manifest_normalized |
O portal salva o manifesto normalizado como .codex-plugin/plugin.json. As alterações nos campos exigem confirmação. |
developer_name_defaulted |
O portal define automaticamente o nome do desenvolvedor na página do plugin com base na identidade de desenvolvedor verificada que você selecionou, independentemente do nome no ZIP. |
Erros de estrutura e limites do ZIP
| Nome | Requisito |
|---|---|
archive_empty |
O arquivo compactado não pode estar vazio. |
archive_too_large |
O ZIP compactado deve ter até 100 MB. |
archive_format_not_zip |
O arquivo deve ser um ZIP válido e íntegro. |
archive_member_path_empty |
O caminho de cada entrada do ZIP não pode estar vazio. |
archive_member_path_has_outer_whitespace |
O caminho de uma entrada do ZIP não pode começar nem terminar com espaços em branco. |
archive_member_path_has_backslash |
O caminho de uma entrada do ZIP deve usar / em vez de barras invertidas. |
archive_member_path_absolute |
O caminho de cada entrada deve ser relativo à raiz do ZIP. |
archive_member_path_has_empty_segment |
O caminho de uma entrada do ZIP não pode conter segmentos vazios. |
archive_member_path_has_parent_segment |
O caminho de uma entrada do ZIP não pode conter segmentos ... |
archive_member_path_too_deep |
O caminho de cada entrada do ZIP deve ter no máximo 20 segmentos, incluindo o nome do arquivo. |
archive_member_path_too_long |
O comprimento do caminho de cada entrada do ZIP deve respeitar o limite aceito. |
archive_member_path_normalization_collision |
Os caminhos das entradas do ZIP devem continuar distintos após a normalização de maiúsculas e minúsculas e a normalização Unicode. |
archive_member_type_unsupported |
As entradas do ZIP devem ser arquivos regulares ou diretórios. |
archive_member_too_large |
Cada entrada do ZIP deve ter no máximo 100 MiB. |
archive_member_path_duplicate |
Cada entrada do ZIP deve ter um caminho único. |
archive_member_path_type_conflict |
O caminho de um arquivo não pode também identificar um diretório nem conter outra entrada do ZIP. |
archive_too_many_entries |
O ZIP deve conter no máximo 5.000 entradas. |
archive_uncompressed_too_large |
O conteúdo extraído do ZIP deve ter no máximo 512 MiB. |
archive_member_unreadable |
Cada entrada do ZIP deve ser legível, estar sem criptografia e usar um método de compactação aceito. |
Erros na raiz do plugin
| Nome | Requisito |
|---|---|
plugin_root_missing |
O caminho selecionado deve existir e apontar para um diretório que contenha um plugin. |
archive_plugin_files_missing |
O ZIP deve conter um manifesto de plugin compatível e pelo menos uma habilidade válida (ou um servidor MCP local aprovado). |
plugin_root_ambiguous |
O ZIP deve conter exatamente uma raiz de plugin, na própria raiz do ZIP ou em um único diretório de primeiro nível. |
plugin_root_has_siblings |
Se o ZIP tiver um diretório de plugin no primeiro nível, não pode haver arquivos ao lado desse diretório. |
Erros no manifesto do plugin
| Nome | Requisito |
|---|---|
plugin_manifest_missing |
Na raiz do ZIP ou em seu único diretório de primeiro nível, deve haver um dos seguintes manifestos: plugin.json com um schema aceito de Agent Plugins, .codex-plugin/plugin.json, .agent-plugin/plugin.json ou .claude-plugin/plugin.json. |
plugin_manifest_not_file |
O manifesto do plugin deve ser um arquivo JSON regular. |
plugin_manifest_unreadable |
O manifesto do plugin deve conter texto legível em UTF-8. |
plugin_manifest_json_malformed |
O manifesto do plugin deve conter JSON válido. Em caso de erro de sintaxe, a mensagem indica o número da linha. |
plugin_manifest_root_not_object |
O manifesto do plugin deve conter um objeto JSON no nível superior. |
codex_manifest_parent_not_directory |
.codex-plugin deve ser um diretório. |
codex_manifest_path_not_file |
.codex-plugin/plugin.json deve ser um arquivo JSON regular. |
plugin_id_wrong_type |
Se informado, id deve ser uma string. |
plugin_id_empty |
Se informado, id não pode estar vazio. |
plugin_name_missing |
name é obrigatório. |
plugin_name_wrong_type |
name deve ser uma string. |
plugin_name_empty |
name não pode estar vazio. |
plugin_name_too_long |
name deve ter até 64 caracteres. |
plugin_name_format |
name deve começar com uma letra ou um dígito ASCII e conter apenas letras e dígitos ASCII, _ ou -. |
plugin_version_missing |
version é obrigatório. |
plugin_version_wrong_type |
version deve ser uma string. |
plugin_version_empty |
version deve ser uma string não vazia que indique uma versão semântica, como 1.0.0. |
plugin_version_not_semver |
version deve seguir o versionamento semântico, como 1.0.0. |
plugin_version_too_long |
version deve ter até 64 caracteres. |
plugin_description_missing |
description é obrigatório. |
plugin_description_wrong_type |
description deve ser uma string. |
plugin_description_empty |
description não pode estar vazio. |
plugin_description_too_long |
description deve ter até 1.024 caracteres. |
plugin_description_character_unsupported |
description deve conter apenas texto aceito. São permitidas quebras de linha. |
plugin_developer_missing |
author.name é obrigatório. interface.developerName também é obrigatório e tem um erro próprio. |
plugin_author_wrong_type |
author deve ser um objeto. |
plugin_author_name_wrong_type |
author.name deve ser uma string. |
plugin_author_name_empty |
author.name não pode estar vazio. |
plugin_author_name_too_long |
author.name deve ter até 120 caracteres. |
plugin_author_name_character_unsupported |
author.name deve conter apenas texto aceito. |
plugin_author_email_wrong_type |
Se informado, author.email deve ser uma string. |
plugin_author_email_empty |
Se informado, author.email não pode estar vazio. |
plugin_author_email_too_long |
author.email deve ter até 320 caracteres. |
plugin_author_email_character_unsupported |
author.email deve conter apenas texto aceito. |
plugin_author_url_wrong_type |
Se informado, author.url deve ser uma string. |
plugin_author_url_empty |
Se informado, author.url não pode estar vazio. |
plugin_author_url_not_https |
author.url deve ser uma URL HTTPS. |
plugin_author_url_has_credentials |
author.url não pode conter credenciais. |
plugin_author_url_too_long |
author.url deve ter até 2.048 caracteres. |
plugin_author_url_character_unsupported |
author.url deve conter apenas texto aceito. |
Erros na página do plugin e na interface
O objeto interface do manifesto do plugin define o conteúdo da página pública que os usuários veem no diretório. Ele fica em .codex-plugin/plugin.json e usa campos como displayName e shortDescription:
{
"interface": {
"displayName": "Example Plugin",
"shortDescription": "Summarize documents",
"longDescription": "Summarize and organize documents.",
"developerName": "Example",
"category": "Productivity",
"capabilities": ["Summarize documents"]
}
}As quatro URLs da página do plugin (site, política de privacidade, termos e suporte) são opcionais para uploads de ZIP de plugins que contêm apenas habilidades. Elas são obrigatórias para o envio de servidores MCP remotos. Cada URL pode ter até 2.048 caracteres na validação do pacote e até 1.024 no envio final ao diretório.
| Nome | Requisito |
|---|---|
plugin_interface_wrong_type |
O campo interface do manifesto do plugin deve ser um objeto JSON. |
plugin_display_name_wrong_type |
interface.displayName deve ser uma string. |
plugin_display_name_empty |
interface.displayName é obrigatório e não pode estar vazio. |
plugin_display_name_too_long |
interface.displayName deve ter até 80 caracteres na validação do pacote e até 30 no envio final ao diretório. |
plugin_display_name_character_unsupported |
interface.displayName deve conter apenas texto aceito. |
plugin_short_description_missing |
interface.shortDescription é obrigatório e deve ocupar uma única linha, com até 240 caracteres na validação do pacote e até 30 no envio final ao diretório. |
plugin_short_description_wrong_type |
interface.shortDescription deve ser uma string. |
plugin_short_description_empty |
interface.shortDescription não pode estar vazio. |
plugin_short_description_too_long |
interface.shortDescription deve ter até 240 caracteres na validação do pacote e até 30 no envio final ao diretório. |
plugin_short_description_character_unsupported |
interface.shortDescription deve conter apenas texto aceito. |
plugin_long_description_wrong_type |
interface.longDescription deve ser uma string. |
plugin_long_description_empty |
interface.longDescription é obrigatório e não pode estar vazio. |
plugin_long_description_too_long |
interface.longDescription deve ter até 4.000 caracteres. |
plugin_long_description_character_unsupported |
interface.longDescription deve conter apenas texto aceito. São permitidas quebras de linha. |
plugin_developer_name_wrong_type |
interface.developerName deve ser uma string. |
plugin_developer_name_empty |
interface.developerName é obrigatório e não pode estar vazio. |
plugin_developer_name_too_long |
interface.developerName deve ter até 120 caracteres na validação do pacote e até 80 no envio final ao diretório. |
plugin_developer_name_character_unsupported |
interface.developerName deve conter apenas texto aceito. |
plugin_category_wrong_type |
interface.category deve ser uma string. |
plugin_category_empty |
Se informado, interface.category não pode estar vazio. Omita o campo para usar Other. |
plugin_category_unknown |
interface.category deve ter um dos seguintes valores: Productivity, Creativity, Developer Tools, Business & Operations, Data & Analytics, Communication, Education & Research, Security, Finance, Healthcare, Travel, Entertainment ou Other. |
plugin_category_character_unsupported |
interface.category deve conter apenas texto aceito. |
plugin_capabilities_wrong_type |
interface.capabilities deve ser uma lista de strings. |
plugin_capabilities_too_many |
interface.capabilities deve conter no máximo 20 itens. |
plugin_capability_wrong_type |
Cada item de interface.capabilities deve ser uma string. |
plugin_capability_empty |
Nenhum item informado em interface.capabilities pode estar vazio. |
plugin_capability_too_long |
Cada item de interface.capabilities deve ter até 120 caracteres. |
plugin_capability_character_unsupported |
Cada item de interface.capabilities deve conter apenas texto aceito. |
plugin_website_url_wrong_type |
Se informado, interface.websiteURL deve ser uma string. |
plugin_website_url_empty |
Se informado, interface.websiteURL não pode estar vazio. |
plugin_website_url_format |
interface.websiteURL deve ser uma URL HTTPS. |
plugin_website_url_too_long |
interface.websiteURL deve respeitar os limites de comprimento das URLs da página do plugin. |
plugin_privacy_policy_url_wrong_type |
Se informado, interface.privacyPolicyURL deve ser uma string. |
plugin_privacy_policy_url_empty |
Se informado, interface.privacyPolicyURL não pode estar vazio. |
plugin_privacy_policy_url_format |
interface.privacyPolicyURL deve ser uma URL HTTPS. |
plugin_privacy_policy_url_too_long |
interface.privacyPolicyURL deve respeitar os limites de comprimento das URLs da página do plugin. |
plugin_terms_of_service_url_wrong_type |
Se informado, interface.termsOfServiceURL deve ser uma string. |
plugin_terms_of_service_url_empty |
Se informado, interface.termsOfServiceURL não pode estar vazio. |
plugin_terms_of_service_url_format |
interface.termsOfServiceURL deve ser uma URL HTTPS. |
plugin_terms_of_service_url_too_long |
interface.termsOfServiceURL deve respeitar os limites de comprimento das URLs da página do plugin. |
plugin_support_url_wrong_type |
Se informado, interface.supportURL deve ser uma string. |
plugin_support_url_empty |
Se informado, interface.supportURL não pode estar vazio. |
plugin_support_url_format |
interface.supportURL deve ser uma URL HTTPS. |
plugin_support_url_too_long |
interface.supportURL deve respeitar os limites de comprimento das URLs da página do plugin. |
plugin_homepage_wrong_type |
Se informado, homepage deve ser uma string. |
plugin_homepage_empty |
Se informado, homepage não pode estar vazio. |
plugin_homepage_format |
homepage deve ser uma URL HTTPS. |
plugin_homepage_too_long |
homepage deve ter até 2.048 caracteres. |
plugin_brand_color_wrong_type |
Se informado, interface.brandColor deve ser uma string. |
plugin_brand_color_empty |
Se informado, interface.brandColor não pode estar vazio. |
plugin_brand_color_format |
interface.brandColor deve indicar uma cor em formato hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_dark_wrong_type |
Se informado, interface.brandColorDark deve ser uma string. |
plugin_brand_color_dark_empty |
Se informado, interface.brandColorDark não pode estar vazio. |
plugin_brand_color_dark_format |
interface.brandColorDark deve indicar uma cor em formato hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_contrast |
interface.brandColor deve ter contraste mínimo de 2:1 com o branco. |
plugin_brand_color_dark_contrast |
interface.brandColorDark deve ter contraste mínimo de 2:1 com #212121. |
plugin_default_prompt_wrong_type |
interface.defaultPrompt deve ser uma string ou uma lista de strings. |
plugin_default_prompt_too_many |
interface.defaultPrompt deve conter no máximo três prompts. |
plugin_default_prompt_entry_wrong_type |
Cada item de interface.defaultPrompt deve ser uma string. |
plugin_default_prompt_empty |
Nenhum item informado em interface.defaultPrompt pode estar vazio. |
plugin_default_prompt_too_long |
Cada item de interface.defaultPrompt deve ter até 512 caracteres na validação do pacote e até 128 no envio final ao diretório. |
plugin_default_prompt_character_unsupported |
Cada item de interface.defaultPrompt deve conter apenas texto aceito e ocupar uma única linha. |
Erros no conteúdo do plugin
| Nome | Requisito |
|---|---|
plugin_skills_path_wrong_type |
skills deve ser uma string com o caminho do diretório skills/ na raiz. |
plugin_skills_path_empty |
Se informado, skills deve conter um caminho não vazio para o diretório skills/ na raiz. |
plugin_skills_path_unsupported |
skills deve apontar para o diretório skills/ na raiz. |
plugin_skills_directory_missing |
Se declarado, o diretório skills/ deve existir na raiz. |
plugin_skills_path_not_directory |
Se declarado, skills/ na raiz deve ser um diretório. |
plugin_apps_path_wrong_type |
apps deve ser uma string com o caminho de .app.json na raiz. |
plugin_apps_path_empty |
Se informado, apps deve conter um caminho não vazio para .app.json na raiz. |
plugin_apps_path_unsupported |
apps deve apontar para .app.json na raiz. |
plugin_apps_file_missing |
Se declarado, o arquivo .app.json deve existir na raiz. |
plugin_apps_path_not_file |
Se declarado, .app.json na raiz deve ser um arquivo regular. |
plugin_mcp_path_wrong_type |
mcpServers deve ser uma string com o caminho de .mcp.json na raiz. |
plugin_mcp_path_empty |
mcpServers deve conter um caminho não vazio. Defina o valor como ./.mcp.json ou remova o campo. |
plugin_mcp_path_unsupported |
mcpServers deve apontar para .mcp.json na raiz. |
plugin_mcp_file_missing |
mcpServers declara .mcp.json na raiz, mas o arquivo não existe. |
plugin_mcp_path_not_file |
.mcp.json na raiz deve ser um arquivo regular. |
plugin_runtime_surface_missing |
Um ZIP enviado ao diretório público deve conter pelo menos uma habilidade válida (ou um servidor MCP local aprovado). Pacotes locais e de espaços de trabalho também podem fazer referência a um servidor MCP elegível. |
Erros no manifesto MCP
Esses erros se aplicam ao arquivo de compatibilidade .mcp.json. Ao importar pacotes portáteis, o sistema gera esse arquivo e .codex-plugin/plugin.json a partir de plugin.json e mcp.json na raiz. Os erros de caminho dos componentes descritos acima também podem se referir aos arquivos gerados. Corrija a configuração de origem do pacote portátil. Não renomeie mcp.json para .mcp.json apenas porque o diagnóstico de compatibilidade menciona esse nome.
| Nome | Requisito |
|---|---|
mcp_manifest_unreadable |
.mcp.json deve conter texto legível em UTF-8. |
mcp_manifest_json_malformed |
.mcp.json deve conter JSON válido. Em caso de erro de sintaxe, a mensagem indica o número da linha. |
mcp_manifest_wrong_type |
.mcp.json deve conter um objeto JSON no nível superior. |
mcp_servers_missing |
.mcp.json deve conter o campo mcpServers no nível superior. |
mcp_servers_wrong_type |
mcpServers deve ser um objeto. |
mcp_server_name_empty |
O nome de cada servidor MCP deve conter pelo menos um caractere que não seja espaço em branco. |
mcp_server_wrong_type |
Cada valor de mcpServers.<server-name> deve ser um objeto com a declaração do respectivo servidor. |
Erros nas habilidades
| Nome | Requisito |
|---|---|
skill_manifest_missing |
A habilidade deve conter um arquivo SKILL.md. |
skill_bundle_too_large |
O pacote compactado de cada habilidade deve respeitar o limite em MiB informado no erro. |
skill_directory_hidden |
O nome do diretório de uma habilidade não pode começar com .. |
skill_manifest_nested |
O diretório de cada habilidade deve ficar diretamente em skills/. |
skill_manifest_not_regular_file |
SKILL.md deve ser um arquivo regular. |
skill_manifest_unreadable |
SKILL.md deve ser legível. |
skill_manifest_invalid_utf8 |
SKILL.md deve conter texto válido em UTF-8. |
skill_frontmatter_missing |
SKILL.md deve começar com um cabeçalho de metadados YAML delimitado por linhas com ---. |
skill_frontmatter_unclosed |
O cabeçalho de metadados YAML de SKILL.md deve terminar com ---. |
skill_frontmatter_yaml_malformed |
O cabeçalho de metadados de SKILL.md deve conter YAML válido. |
skill_frontmatter_wrong_type |
O cabeçalho de metadados de SKILL.md deve conter um mapeamento YAML. |
skill_name_missing |
name é obrigatório e não pode estar vazio. |
skill_name_wrong_type |
name deve ser uma string. |
skill_name_empty |
name não pode estar vazio. |
skill_name_character_unsupported |
O campo name do cabeçalho de metadados da habilidade deve conter apenas texto aceito. |
skill_description_missing |
description é obrigatório e não pode estar vazio. |
skill_description_wrong_type |
description deve ser uma string. |
skill_description_empty |
description não pode estar vazio. |
skill_description_too_long |
description deve ter até 1.024 caracteres. |
skill_description_character_unsupported |
O campo description do cabeçalho de metadados da habilidade deve conter apenas texto aceito. |
skill_body_empty |
As instruções da habilidade não podem estar vazias. |
skill_identity_too_long |
O nome que combina o plugin e a habilidade (plugin-name:skill-name) deve ter até 64 caracteres. |
skill_identity_duplicate |
O valor de name de cada habilidade deve ser único dentro do plugin. |
Erros nos metadados do agente da habilidade
Uma habilidade incluída no pacote pode definir sua própria interface em skills/<skill>/agents/openai.yaml. Essa configuração controla como a habilidade aparece para os usuários e é independente do objeto interface do manifesto do plugin. Os campos da interface da habilidade usam snake_case:
interface:
display_name: "Summarize documents"
short_description: "Summarize a document"
icon_small: "./assets/icon.png"
default_prompt: "Summarize the selected document."| Nome | Requisito |
|---|---|
skill_agent_not_regular_file |
agents/openai.yaml deve ser um arquivo regular. |
skill_agent_unreadable |
agents/openai.yaml deve ser legível. |
skill_agent_invalid_utf8 |
agents/openai.yaml deve conter texto válido em UTF-8. |
skill_agent_yaml_malformed |
agents/openai.yaml deve conter YAML válido. |
skill_agent_top_level_wrong_type |
agents/openai.yaml deve conter um mapeamento YAML no nível superior. |
skill_agent_interface_missing |
interface é obrigatório em agents/openai.yaml quando o pacote inclui esse arquivo. |
skill_agent_interface_wrong_type |
interface em agents/openai.yaml deve ser um mapeamento YAML. |
skill_agent_display_name_missing |
interface.display_name é obrigatório e não pode estar vazio. |
skill_agent_display_name_wrong_type |
interface.display_name deve ser uma string. |
skill_agent_display_name_empty |
interface.display_name não pode estar vazio. |
skill_agent_short_description_missing |
interface.short_description é obrigatório e não pode estar vazio. |
skill_agent_short_description_wrong_type |
interface.short_description deve ser uma string. |
skill_agent_short_description_empty |
interface.short_description não pode estar vazio. |
skill_agent_icon_small_wrong_type |
Se informado, interface.icon_small deve conter um caminho relativo e não vazio para um arquivo. |
skill_agent_icon_small_empty |
Se informado, interface.icon_small deve conter um caminho relativo e não vazio para um arquivo, como assets/icon.png. |
skill_agent_icon_large_wrong_type |
Se informado, interface.icon_large deve conter um caminho relativo e não vazio para um arquivo. |
skill_agent_icon_large_empty |
Se informado, interface.icon_large deve conter um caminho relativo e não vazio para um arquivo, como assets/icon.png. |
skill_agent_brand_color_wrong_type |
Se informado, interface.brand_color deve ser uma string. |
skill_agent_brand_color_empty |
Se informado, interface.brand_color não pode estar vazio e deve indicar uma cor em formato hexadecimal de seis dígitos, como #1ABCFE. |
skill_agent_brand_color_format |
interface.brand_color deve indicar uma cor em formato hexadecimal de seis dígitos, como #1ABCFE. |
skill_agent_default_prompt_wrong_type |
Se informado, interface.default_prompt deve ser uma string. |
skill_agent_default_prompt_empty |
Se informado, interface.default_prompt não pode estar vazio. |
skill_agent_policy_wrong_type |
Se informado, policy deve ser um mapeamento YAML. |
skill_agent_allow_implicit_invocation_wrong_type |
policy só pode conter products e allow_implicit_invocation. products deve conter CHAT, CODEX ou ambos, e allow_implicit_invocation deve ser true ou false. |
skill_agent_dependencies_wrong_type |
dependencies deve ser um mapeamento YAML. Apenas tools é aceito. |
skill_agent_dependency_unsupported |
Apenas dependencies.tools é aceito em agents/openai.yaml. |
Erros nos caminhos dos recursos
| Nome | Requisito |
|---|---|
declared_asset_path_wrong_type |
O campo de recurso indicado deve ser uma string com o caminho de um arquivo. |
declared_asset_path_empty |
O campo de recurso indicado não pode estar vazio. |
declared_asset_path_has_outer_whitespace |
O valor do campo de recurso indicado não pode começar nem terminar com espaços em branco. |
declared_asset_path_has_control_character |
O campo de recurso indicado não pode conter caracteres de U+0000 a U+001F nem o caractere U+007F. |
branding_asset_path_missing_root_prefix |
O valor do campo de recurso indicado deve começar com ./. |
declared_asset_path_unsafe |
O campo de recurso indicado deve conter um caminho relativo dentro do plugin. Não pode conter um caminho absoluto, um prefixo de unidade nem um segmento .. para acessar o diretório pai. |
declared_asset_path_outside_package |
O campo de recurso indicado deve apontar para um arquivo dentro do plugin. |
declared_asset_file_missing |
O campo de recurso indicado aponta para um arquivo inexistente. |
declared_asset_not_regular_file |
O campo de recurso indicado deve apontar para um arquivo regular. Diretórios e arquivos especiais não são aceitos. |
Erros nas imagens
As imagens de marca exibidas no diretório devem usar um formato de arquivo aceito e respeitar os limites de tamanho e dimensões abaixo. Essas regras se aplicam aos recursos de marca incluídos no pacote.
| Nome | Requisito |
|---|---|
plugin_logo_path_missing |
interface.logo é obrigatório e deve apontar para uma imagem quadrada. |
plugin_composer_icon_path_missing |
interface.composerIcon é obrigatório e deve apontar para uma imagem quadrada. |
image_file_unreadable |
O arquivo de imagem deve ser legível. |
image_file_too_large |
A imagem deve ter no máximo 5 MiB. |
image_file_format_unsupported |
O nome do arquivo de imagem deve terminar em .png, .jpg, .jpeg, .webp ou .svg. |
raster_image_decode_failed |
A imagem raster deve ser um arquivo PNG, JPEG ou WebP que possa ser decodificado com segurança. |
raster_image_extension_content_mismatch |
A extensão do arquivo deve corresponder ao formato de imagem detectado. |
raster_image_not_square |
A imagem deve ser quadrada. |
raster_image_dimensions_too_small |
A imagem deve ter pelo menos 48 × 48 pixels. |
raster_image_dimensions_too_large |
A imagem deve ter no máximo 4.096 × 4.096 pixels. |
svg_xml_malformed |
O SVG deve conter XML válido em UTF-8. |
svg_root_element_invalid |
O elemento raiz do SVG deve ser <svg>. |
svg_dimensions_missing |
O SVG deve definir viewBox com valores numéricos ou definir width e height com valores numéricos. |
svg_dimensions_not_numeric |
As dimensões do SVG devem ser numéricas, sem unidades nem porcentagens. |
svg_dimensions_not_positive |
A largura e a altura do SVG devem ser números positivos e finitos. |
svg_dimensions_not_square |
A largura e a altura do SVG devem ser iguais. |
svg_dimensions_too_small |
O SVG deve ter pelo menos 48 × 48 pixels. |
Erros nas referências a servidores MCP
As verificações comuns a todos os pacotes validam .app.json quando um plugin faz referência a servidores MCP registrados. O portal de envio não publica referências a integrações existentes. O upload pela opção Somente habilidades remove .app.json. Use Com MCP para enviar o servidor MCP diretamente.
Em pacotes locais ou de espaços de trabalho, o objeto apps no nível superior associa cada alias de servidor MCP à entrada de um servidor registrado. Esses nomes de configuração e códigos de erro mantêm a grafia literal app.
| Nome | Requisito |
|---|---|
app_manifest_unreadable |
.app.json deve conter texto legível em UTF-8. |
app_manifest_json_malformed |
.app.json contém JSON com erro de sintaxe próximo à linha indicada. |
app_manifest_wrong_type |
.app.json deve conter um objeto JSON no nível superior. |
app_entries_missing |
apps é obrigatório. |
app_entries_wrong_type |
apps deve ser um objeto. |
app_entry_wrong_type |
Cada entrada de servidor deve ser um objeto. |
app_id_missing |
O campo id é obrigatório em cada entrada de servidor. |
app_id_wrong_type |
O campo id de cada entrada de servidor deve ser uma string. |
app_id_format |
O campo id de cada entrada de servidor deve começar com asdk_app_, connector_ ou templated_apps_. Após o prefixo, use uma letra ou um dígito. Os demais caracteres só podem ser letras, dígitos, _ ou -. |
app_entry_optional_wrong_type |
Em cada entrada de servidor, o campo optional, se informado, deve ter o valor true ou false. |
app_entry_required_wrong_type |
Em cada entrada de servidor, o campo required, se informado, deve ter o valor true ou false. |
app_not_eligible |
Um pacote local ou de um espaço de trabalho deve fazer referência a um servidor MCP elegível e disponível. Para enviar ao diretório, use Com MCP e envie o servidor MCP diretamente. |
Avisos sobre o pacote
Esses avisos identificam conteúdo do pacote que a validação ignora ou normaliza. Eles não impedem o envio. Revise os avisos para confirmar se o plugin enviado contém os arquivos e as configurações esperados.
| Nome | Requisito |
|---|---|
duplicate_app_reference |
Cada ID de servidor em .app.json deve ser referenciado uma única vez. Referências duplicadas contam como um único servidor. |
undeclared_app_manifest_ignored |
O arquivo .app.json na raiz só é importado quando o campo apps do manifesto do plugin tem o valor ./.app.json. |
undeclared_mcp_manifest_ignored |
O arquivo .mcp.json na raiz só é importado quando o campo mcpServers do manifesto do plugin tem o valor ./.mcp.json. |
skill_file_ignored |
Arquivos diretamente em skills/ não são importados como habilidades. Cada habilidade deve estar em um diretório que contenha SKILL.md. |
skill_symlink_ignored |
Links simbólicos diretamente em skills/ não são importados como habilidades. Cada habilidade deve estar em um diretório real que contenha SKILL.md. |
skill_frontmatter_adjusted |
Durante a importação, o sistema normaliza os valores de name e description da habilidade. Ele remove espaços em branco no início e no fim e reduz cada sequência interna de espaços em branco a um único espaço. |
skill_metadata_ignored |
Defina as configurações da interface da habilidade no mapeamento interface de agents/openai.yaml. O campo metadata de SKILL.md não configura a interface. |
Próximos passos
Depois de corrigir todos os erros de validação, volte à página Enviar plugins para concluir o envio.