Os plug-ins enviados ao diretório público devem atender a critérios mais rigorosos do que os plug-ins instalados em um workspace. Os envios ao diretório devem passar pelas verificações comuns de pacotes e pelas verificações adicionais dos campos da listagem, dos materiais para revisão, das ferramentas MCP, das habilidades, dos recursos e das imagens. Esta referência também abrange verificações comuns de pacotes, como referências a servidores MCP, que podem ocorrer fora do portal de envio.
Use o código de erro retornado durante o envio para encontrar o requisito correspondente. Erros bloqueiam o envio. Avisos não bloqueiam o envio, mas você deve revisá-los antes de continuar.
Valores não vazios não podem conter apenas espaços em branco. O texto aceito exclui caracteres de controle, separadores Unicode de linha ou parágrafo e caracteres invisíveis de formatação não aceitos. URLs HTTPS devem incluir um host e não podem conter credenciais embutidas nem caracteres não aceitos.
Envio final ao diretório
Um pacote pode passar na validação do upload e ainda falhar no envio final ao diretório. O envio final aplica limites mais rigorosos à listagem e verifica a configuração do MCP, as verificações 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; no máximo 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 com no máximo 64 caracteres. |
| Nome de exibição | Obrigatório; uma única linha; no máximo 30 caracteres. |
| Descrição curta | Obrigatória; uma única linha; no máximo 30 caracteres. |
| Descrição longa | Obrigatória; no máximo 4.000 caracteres. Quebras de linha são permitidas. |
| Nome do desenvolvedor | Obrigatório; uma única linha; no máximo 80 caracteres. |
| Categoria | Obrigatória; escolha uma categoria aceita, listada na seção Erros de listagem e interface. |
| Capacidades | No máximo 20. Cada capacidade deve ter um valor não vazio, ocupar uma única linha e ter no máximo 120 caracteres. |
| Prompts iniciais | No máximo 3. Cada prompt deve ser não vazio, ser único após a normalização Unicode e de espaços em branco, ocupar uma única linha, ter no máximo 128 caracteres e não conter @mention a servidor MCP. |
| URLs | Obrigatórias para envios de MCP remoto; opcionais para uploads de ZIP de plug-ins que contêm apenas habilidades. As URLs do site, do suporte, da política de privacidade e dos termos devem usar HTTPS e ter no máximo 1.024 caracteres. |
| Cores da marca | Cores hexadecimais opcionais de seis dígitos. A cor clara deve ter contraste de pelo menos 2:1 com o branco, e a cor escura deve ter contraste de pelo menos 2:1 com #212121. |
Todo envio de plug-in também exige:
- Aprovação nas verificações de segurança de uso e de segurança técnica de cada habilidade incluída no pacote. As verificações podem levar até 2 horas.
- Identidade verificada do desenvolvedor ou da empresa e todas as declarações obrigatórias de conformidade com as políticas.
Para um plug-in de MCP remoto, o envio final também exige:
- URLs do site, do suporte, da política de privacidade e dos termos que atendam às regras acima.
- Uma URL de gravação de demonstração que mostre os principais casos de uso e ferramentas nas plataformas compatíveis.
- Exatamente cinco casos de teste positivos, três casos de teste negativos e notas de versão.
- Uma URL HTTPS do servidor MCP de produção, um desafio de verificação de domínio concluído e uma verificação de ferramentas bem-sucedida e atualizada.
- Valores explícitos de
readOnlyHint,openWorldHintedestructiveHinte uma justificativa para cada valor em todas as ferramentas MCP. - Credenciais de demonstração prontas para uso pelos revisores quando o servidor usa OAuth.
- Capturas de tela somente quando o servidor MCP oferece uma interface personalizada. Se adicionar capturas de tela, forneça uma imagem PNG ou JPEG para cada prompt inicial. Cada captura de tela deve ter exatamente 706 pixels de largura e de 400 a 860 pixels de altura.
Erros de metadados no envio final
Nesses nomes de erro, subtitle significa descrição curta e description
significa descrição longa.
| Nome | Requisito |
|---|---|
submission_display_name_required | O nome de exibição é obrigatório, não pode estar vazio e deve ocupar uma única linha. |
submission_display_name_too_long | O nome de exibição deve ter no máximo 30 caracteres. |
submission_display_name_character_unsupported | O nome de exibição deve usar texto aceito e caber em uma única linha. |
submission_subtitle_required | A descrição curta é obrigatória, não pode estar vazia e deve ocupar uma única linha. |
submission_subtitle_too_long | A descrição curta deve ter no máximo 30 caracteres. |
submission_subtitle_character_unsupported | A descrição curta deve usar texto aceito e caber em uma única linha. |
submission_description_required | A descrição longa é obrigatória e não pode estar vazia. Quebras de linha são permitidas. |
submission_description_too_long | A descrição longa deve ter no máximo 4.000 caracteres. |
submission_description_character_unsupported | A descrição longa deve usar texto aceito. Quebras de linha são permitidas. |
submission_developer_name_required | O nome do desenvolvedor é obrigatório, não pode estar vazio e deve ocupar uma única linha. |
submission_developer_name_too_long | O nome do desenvolvedor deve ter no máximo 80 caracteres. |
submission_developer_name_character_unsupported | O nome do desenvolvedor deve usar texto aceito e caber em uma única linha. |
plugin_capability_invalid | Cada capacidade deve ter um valor não vazio, usar texto aceito, caber em uma única linha e ter no máximo 120 caracteres. |
plugin_default_prompt_mention | Os prompts iniciais não devem conter @mentions a servidores MCP. |
plugin_default_prompt_duplicate | Os prompts iniciais devem ser únicos após a normalização Unicode e de espaços em branco. |
Erros de MCP e de revisão
Esses erros se aplicam a envios de MCP remoto.
| Nome | Requisito |
|---|---|
annotations_required | Toda ferramenta MCP deve definir readOnlyHint, openWorldHint e destructiveHint com precisão. |
justification_required | Toda anotação de ferramenta MCP deve incluir uma justificativa para seu comportamento somente leitura, de mundo aberto ou destrutivo. |
scan_required | As ferramentas MCP devem ter uma varredura atual e bem-sucedida do servidor MCP de produção. |
domain_verification_required | O token de verificação exato deve estar hospedado na URL /.well-known/openai-apps-challenge gerada, no host MCP ou em um host pai permitido, e a ação Verificar domínio deve ser concluída com sucesso. |
frame_domain_explanation_required | Cada domínio de frame externo informado pela varredura de ferramentas MCP deve ter uma explicação de por que a interface precisa dele e de qual conteúdo ele fornece. |
screenshots_not_allowed | Capturas de tela só são permitidas quando a varredura atual de ferramentas MCP informa um template de saída de interface. |
Erros de arquivo compactado
Erros e avisos de upload de ZIP
A opção Somente habilidades do portal aceita pacotes ZIP de habilidades. Os erros bloqueiam o upload; os avisos exigem confirmação.
| Nome | Requisito |
|---|---|
plugin_name_mismatch | O nome do pacote em uma atualização deve corresponder ao nome do plug-in existente. |
plugin_version_unchanged | Uma nova versão deve usar um valor diferente de version no manifesto; reutilizar a versão publicada exige confirmação. |
mcp_configuration_excluded | Uploads somente de habilidades excluem mcpServers, mcp.json e .mcp.json. Envie um servidor MCP remoto pela opção Com MCP. |
app_configuration_excluded | Uploads de ZIP somente de habilidades não devem incluir apps nem .app.json; plug-ins com servidores MCP devem usar a opção Com MCP. |
screenshot_configuration_excluded | Uploads de ZIP somente de habilidades não devem incluir interface.screenshots; capturas de tela exigem a opção Com MCP e uma interface personalizada. |
claude_format_normalized | .claude-plugin/plugin.json é convertido em .codex-plugin/plugin.json, e o portal adiciona os valores padrão de interface ausentes e os campos de texto normalizados. |
manifest_normalized | O portal salva o manifesto normalizado como .codex-plugin/plugin.json; campos alterados exigem confirmação. |
developer_name_defaulted | author.name e interface.developerName devem corresponder; caso contrário, a identidade verificada selecionada será usada em ambos após a confirmação. |
Erros de estrutura e limites do ZIP
| Nome | Requisito |
|---|---|
archive_empty | O arquivo compactado não deve estar vazio. |
archive_too_large | O ZIP compactado deve ter no máximo 100 MB. |
archive_format_not_zip | O arquivo compactado deve ser um arquivo ZIP válido e não corrompido. |
archive_member_path_empty | O caminho da entrada no arquivo compactado não deve estar vazio. |
archive_member_path_has_outer_whitespace | O caminho da entrada no arquivo compactado não deve começar nem terminar com espaços em branco. |
archive_member_path_has_backslash | O caminho da entrada no arquivo compactado deve usar /, e não barras invertidas. |
archive_member_path_absolute | O caminho da entrada no arquivo compactado deve ser relativo à raiz do arquivo compactado. |
archive_member_path_has_empty_segment | O caminho da entrada no arquivo compactado não deve conter segmentos vazios. |
archive_member_path_has_parent_segment | O caminho da entrada no arquivo compactado não deve conter segmentos ... |
archive_member_path_too_deep | O caminho da entrada no arquivo compactado deve conter no máximo 20 segmentos, incluindo o nome do arquivo. |
archive_member_path_too_long | O caminho da entrada no arquivo compactado deve respeitar o limite de comprimento de caminho suportado. |
archive_member_path_normalization_collision | Os caminhos das entradas no arquivo compactado devem permanecer únicos após a normalização de maiúsculas e minúsculas e de Unicode. |
archive_member_type_unsupported | As entradas no arquivo compactado devem ser arquivos regulares ou diretórios. |
archive_member_too_large | A entrada no arquivo compactado não deve exceder 100 MiB. |
archive_member_path_duplicate | O caminho da entrada no arquivo compactado deve ser único. |
archive_member_path_type_conflict | Um caminho de arquivo não pode também ser um diretório nem conter outra entrada do arquivo compactado. |
archive_too_many_entries | O arquivo compactado não deve conter mais de 5.000 entradas. |
archive_uncompressed_too_large | O conteúdo extraído do arquivo compactado não deve exceder 512 MiB. |
archive_member_unreadable | Toda entrada no arquivo compactado deve permitir leitura, não deve estar criptografada e deve usar um método de compactação suportado. |
Erros da raiz do plug-in
| Nome | Requisito |
|---|---|
plugin_root_missing | O caminho selecionado deve existir e ser um diretório que contenha um plug-in. |
archive_plugin_files_missing | Um ZIP somente de habilidades deve conter um manifesto de plug-in suportado e pelo menos uma habilidade válida. |
plugin_root_ambiguous | O ZIP deve conter exatamente uma raiz de plug-in, na raiz do arquivo compactado ou em um diretório de nível superior. |
plugin_root_has_siblings | Um ZIP com um diretório de plug-in no nível superior não deve conter arquivos no mesmo nível desse diretório. |
Erros do manifesto do plug-in
| Nome | Requisito |
|---|---|
plugin_manifest_missing | O ZIP deve conter plugin.json na raiz com um esquema Agent Plugins suportado, .codex-plugin/plugin.json, .agent-plugin/plugin.json ou .claude-plugin/plugin.json, na raiz do arquivo compactado ou em seu único diretório de nível superior. |
plugin_manifest_not_file | O manifesto do plug-in deve ser um arquivo JSON regular. |
plugin_manifest_unreadable | O manifesto do plug-in deve ser um texto UTF-8 legível. |
plugin_manifest_json_malformed | O manifesto do plug-in deve conter JSON válido; erros de sintaxe são informados com o número da linha. |
plugin_manifest_root_not_object | O manifesto do plug-in 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 | id deve ser uma string quando fornecido. |
plugin_id_empty | id não deve estar vazio quando fornecido. |
plugin_name_missing | name é obrigatório. |
plugin_name_wrong_type | name deve ser uma string. |
plugin_name_empty | name não deve estar vazio. |
plugin_name_too_long | name deve ter no máximo 64 caracteres. |
plugin_name_format | name deve começar com uma letra ASCII ou um dígito e conter apenas letras ASCII, dígitos, _ 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 de 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 no máximo 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 no máximo 1.024 caracteres. |
plugin_description_character_unsupported | description deve usar texto compatível. Quebras de linha são permitidas. |
plugin_developer_missing | author.name é obrigatório. interface.developerName também é obrigatório e é indicado separadamente. |
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 no máximo 120 caracteres. |
plugin_author_name_character_unsupported | author.name deve usar texto compatível. |
plugin_author_email_wrong_type | author.email deve ser uma string quando fornecido. |
plugin_author_email_empty | author.email não pode estar vazio quando fornecido. |
plugin_author_email_too_long | author.email deve ter no máximo 320 caracteres. |
plugin_author_email_character_unsupported | author.email deve usar texto compatível. |
plugin_author_url_wrong_type | author.url deve ser uma string quando fornecido. |
plugin_author_url_empty | author.url não pode estar vazio quando fornecido. |
plugin_author_url_not_https | author.url deve ser uma URL HTTPS. |
plugin_author_url_has_credentials | author.url não deve conter credenciais. |
plugin_author_url_too_long | author.url deve ter no máximo 2.048 caracteres. |
plugin_author_url_character_unsupported | author.url deve usar texto compatível. |
Erros de listagem e interface
O objeto interface do manifesto do plug-in define a listagem pública exibida aos
usuários. 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 listagem (site, política de privacidade, termos e suporte) são opcionais para uploads de ZIP de plug-ins que contêm apenas habilidades. Elas são obrigatórias para envios de MCP remoto. O limite de tamanho é de 2.048 caracteres para validação do pacote e 1.024 caracteres para o envio final ao diretório.
| Nome | Requisito |
|---|---|
plugin_interface_wrong_type | O campo interface do manifesto do plug-in 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 no máximo 80 caracteres para validação do pacote e no máximo 30 caracteres para o envio final ao diretório. |
plugin_display_name_character_unsupported | interface.displayName deve usar texto compatível. |
plugin_short_description_missing | interface.shortDescription é obrigatório, deve ocupar uma única linha e ter no máximo 240 caracteres para validação do pacote e no máximo 30 caracteres para o 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 no máximo 240 caracteres para validação do pacote e no máximo 30 caracteres para o envio final ao diretório. |
plugin_short_description_character_unsupported | interface.shortDescription deve usar texto compatível. |
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 no máximo 4.000 caracteres. |
plugin_long_description_character_unsupported | interface.longDescription deve usar texto compatível. Quebras de linha são permitidas. |
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 no máximo 120 caracteres para validação do pacote e no máximo 80 caracteres para o envio final ao diretório. |
plugin_developer_name_character_unsupported | interface.developerName deve usar texto compatível. |
plugin_category_wrong_type | interface.category deve ser uma string. |
plugin_category_empty | interface.category não pode estar vazio quando fornecido; omita-o para usar Other. |
plugin_category_unknown | interface.category deve ser 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 usar texto compatível. |
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 | Cada item de interface.capabilities não pode estar vazio quando fornecido. |
plugin_capability_too_long | Cada item de interface.capabilities deve ter no máximo 120 caracteres. |
plugin_capability_character_unsupported | Cada item de interface.capabilities deve usar texto compatível. |
plugin_website_url_wrong_type | interface.websiteURL deve ser uma string quando fornecido. |
plugin_website_url_empty | interface.websiteURL não pode estar vazio quando fornecido. |
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 listagem. |
plugin_privacy_policy_url_wrong_type | interface.privacyPolicyURL deve ser uma string quando informado. |
plugin_privacy_policy_url_empty | interface.privacyPolicyURL não pode estar vazio quando informado. |
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 listagem. |
plugin_terms_of_service_url_wrong_type | interface.termsOfServiceURL deve ser uma string quando informado. |
plugin_terms_of_service_url_empty | interface.termsOfServiceURL não pode estar vazio quando informado. |
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 listagem. |
plugin_support_url_wrong_type | interface.supportURL deve ser uma string quando informado. |
plugin_support_url_empty | interface.supportURL não pode estar vazio quando informado. |
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 listagem. |
plugin_homepage_wrong_type | homepage deve ser uma string quando informado. |
plugin_homepage_empty | homepage não pode estar vazio quando informado. |
plugin_homepage_format | homepage deve ser uma URL HTTPS. |
plugin_homepage_too_long | homepage deve ter no máximo 2.048 caracteres. |
plugin_brand_color_wrong_type | interface.brandColor deve ser uma string quando informado. |
plugin_brand_color_empty | interface.brandColor não pode estar vazio quando informado. |
plugin_brand_color_format | interface.brandColor deve ser uma cor hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_dark_wrong_type | interface.brandColorDark deve ser uma string quando informado. |
plugin_brand_color_dark_empty | interface.brandColorDark não pode estar vazio quando informado. |
plugin_brand_color_dark_format | interface.brandColorDark deve ser uma cor hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_contrast | interface.brandColor deve ter contraste de pelo menos 2:1 em relação ao branco. |
plugin_brand_color_dark_contrast | interface.brandColorDark deve ter contraste de pelo menos 2:1 em relação a #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 entrada de interface.defaultPrompt deve ser uma string. |
plugin_default_prompt_empty | Cada entrada de interface.defaultPrompt não pode estar vazia quando informada. |
plugin_default_prompt_too_long | Cada entrada de interface.defaultPrompt deve ter no máximo 512 caracteres para a validação do pacote e no máximo 128 caracteres para o envio final ao diretório. |
plugin_default_prompt_character_unsupported | Cada entrada de interface.defaultPrompt deve usar texto compatível e caber em uma única linha. |
Erros de conteúdo do plug-in
| Nome | Requisito |
|---|---|
plugin_skills_path_wrong_type | skills deve ser uma string com o caminho para o diretório skills/ na raiz. |
plugin_skills_path_empty | Quando informado, skills deve ser um caminho não vazio para o diretório skills/ na raiz. |
plugin_skills_path_unsupported | skills deve resolver para o diretório skills/ na raiz. |
plugin_skills_directory_missing | Se declarado, o diretório skills/ na raiz deve existir. |
plugin_skills_path_not_directory | Quando declarado, skills/ na raiz deve ser um diretório. |
plugin_apps_path_wrong_type | apps deve ser uma string com o caminho para o arquivo .app.json na raiz. |
plugin_apps_path_empty | Quando informado, apps deve ser um caminho não vazio para o arquivo .app.json na raiz. |
plugin_apps_path_unsupported | apps deve resolver para o arquivo .app.json na raiz. |
plugin_apps_file_missing | Se declarado, o arquivo .app.json na raiz deve existir. |
plugin_apps_path_not_file | Quando declarado, .app.json na raiz deve ser um arquivo regular. |
plugin_mcp_path_wrong_type | mcpServers deve ser uma string com o caminho para o arquivo .mcp.json na raiz. |
plugin_mcp_path_empty | mcpServers deve ser um caminho não vazio. Defina seu valor como ./.mcp.json ou remova o campo. |
plugin_mcp_path_unsupported | mcpServers deve resolver para o arquivo .mcp.json na raiz. |
plugin_mcp_file_missing | mcpServers declara o arquivo .mcp.json na raiz, mas esse arquivo não existe. |
plugin_mcp_path_not_file | .mcp.json na raiz deve ser um arquivo regular. |
plugin_runtime_surface_missing | Um ZIP que contém apenas habilidades deve conter pelo menos uma habilidade válida. Pacotes locais e de workspace também podem referenciar um servidor MCP elegível. |
Erros do manifesto MCP
Esses erros se aplicam ao arquivo de compatibilidade .mcp.json. Para pacotes portáveis,
a ingestão gera esse arquivo e .codex-plugin/plugin.json a partir dos arquivos
plugin.json e mcp.json na raiz. Os erros de caminho de componente acima também podem se referir a
esses arquivos gerados. Corrija a configuração portável de origem; não renomeie
mcp.json para .mcp.json só porque um diagnóstico de compatibilidade menciona esse nome.
| Nome | Requisito |
|---|---|
mcp_manifest_unreadable | .mcp.json deve ser um arquivo de texto UTF-8 que possa ser lido. |
mcp_manifest_json_malformed | .mcp.json deve conter JSON válido; erros de sintaxe são informados com 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 um espaço em branco. |
mcp_server_wrong_type | Cada valor de mcpServers.<server-name> deve ser um objeto que contenha a declaração desse servidor. |
Erros de habilidades
| Nome | Requisito |
|---|---|
skill_manifest_missing | A habilidade deve conter um arquivo SKILL.md. |
skill_bundle_too_large | Cada pacote compactado de habilidade deve respeitar o limite em MiB informado no erro. |
skill_directory_hidden | Os nomes dos diretórios de habilidades não devem começar com .. |
skill_manifest_nested | Cada diretório de habilidade deve ser um subdiretório direto de skills/. |
skill_manifest_not_regular_file | SKILL.md deve ser um arquivo regular. |
skill_manifest_unreadable | SKILL.md deve permitir leitura. |
skill_manifest_invalid_utf8 | SKILL.md deve conter UTF-8 válido. |
skill_frontmatter_missing | SKILL.md deve começar com um cabeçalho YAML entre linhas ---. |
skill_frontmatter_unclosed | O cabeçalho YAML de SKILL.md deve terminar com ---. |
skill_frontmatter_yaml_malformed | O cabeçalho de SKILL.md deve conter YAML válido. |
skill_frontmatter_wrong_type | O cabeçalho de SKILL.md deve conter um mapeamento YAML. |
skill_name_missing | name é obrigatório e não deve estar vazio. |
skill_name_wrong_type | name deve ser uma string. |
skill_name_empty | name não deve estar vazio. |
skill_name_character_unsupported | O campo name do cabeçalho da habilidade deve usar texto compatível. |
skill_description_missing | description é obrigatório e não deve estar vazio. |
skill_description_wrong_type | description deve ser uma string. |
skill_description_empty | description não deve estar vazio. |
skill_description_too_long | description deve ter no máximo 1.024 caracteres. |
skill_description_character_unsupported | O campo description do cabeçalho da habilidade deve usar texto compatível. |
skill_body_empty | As instruções da habilidade não devem estar vazias. |
skill_identity_too_long | O nome combinado do plug-in e da habilidade (plugin-name:skill-name) deve ter no máximo 64 caracteres. |
skill_identity_duplicate | O valor de name de cada habilidade deve ser único dentro do plug-in. |
Erros nos metadados de agente da habilidade
Uma habilidade incluída no pacote pode definir seu próprio campo interface em
skills/<skill>/agents/openai.yaml. Isso controla como a habilidade é exibida aos
usuários e é separado do campo interface do manifesto do plug-in. Os campos de 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 permitir leitura. |
skill_agent_invalid_utf8 | agents/openai.yaml deve conter UTF-8 válido. |
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 esse arquivo está incluído. |
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 deve 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 deve estar vazio. |
skill_agent_short_description_missing | interface.short_description é obrigatório e não deve 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 deve estar vazio. |
skill_agent_icon_small_wrong_type | Quando fornecido, interface.icon_small deve ser um caminho relativo de arquivo e não deve estar vazio. |
skill_agent_icon_small_empty | Quando fornecido, interface.icon_small deve ser um caminho relativo de arquivo, como assets/icon.png, e não deve estar vazio. |
skill_agent_icon_large_wrong_type | Quando fornecido, interface.icon_large deve ser um caminho relativo de arquivo e não deve estar vazio. |
skill_agent_icon_large_empty | Quando fornecido, interface.icon_large deve ser um caminho relativo de arquivo, como assets/icon.png, e não deve estar vazio. |
skill_agent_brand_color_wrong_type | interface.brand_color deve ser uma string quando fornecido. |
skill_agent_brand_color_empty | Quando fornecido, interface.brand_color deve ser uma cor hexadecimal de seis dígitos, como #1ABCFE, e não deve estar vazio. |
skill_agent_brand_color_format | interface.brand_color deve ser uma cor hexadecimal de seis dígitos, como #1ABCFE. |
skill_agent_default_prompt_wrong_type | interface.default_prompt deve ser uma string quando fornecido. |
skill_agent_default_prompt_empty | interface.default_prompt não deve estar vazio quando fornecido. |
skill_agent_policy_wrong_type | policy deve ser um mapeamento YAML quando fornecido. |
skill_agent_allow_implicit_invocation_wrong_type | policy pode conter apenas 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 de recursos
| Nome | Requisito |
|---|---|
declared_asset_path_wrong_type | O campo de recurso indicado deve ser uma string de caminho de arquivo. |
declared_asset_path_empty | O campo de recurso indicado não deve estar vazio. |
declared_asset_path_has_outer_whitespace | O campo de recurso indicado não deve começar nem terminar com espaços em branco. |
declared_asset_path_has_control_character | O campo de recurso indicado não deve conter os caracteres U+0000–U+001F ou U+007F. |
branding_asset_path_missing_root_prefix | O campo de recurso indicado deve começar com ./. |
declared_asset_path_unsafe | O campo de recurso indicado deve ser um caminho relativo dentro do plug-in e não deve conter um caminho absoluto, um prefixo de unidade ou um segmento .. de navegação para o diretório pai. |
declared_asset_path_outside_package | O campo de recurso indicado deve referenciar um arquivo dentro do plug-in. |
declared_asset_file_missing | O campo de recurso indicado referencia um arquivo que não existe. |
declared_asset_not_regular_file | O campo de recurso indicado deve referenciar um arquivo, não um diretório nem um arquivo especial. |
Erros de imagem
As imagens de identidade visual do diretório devem usar um tipo de arquivo compatível e respeitar os limites de tamanho e dimensões abaixo. Essas regras se aplicam aos recursos de identidade visual incluídos no pacote; as capturas de tela dos prompts iniciais seguem os limites específicos do portal listados acima.
| Nome | Requisito |
|---|---|
plugin_logo_path_missing | interface.logo é obrigatório e deve referenciar uma imagem quadrada. |
plugin_composer_icon_path_missing | interface.composerIcon é obrigatório e deve referenciar uma imagem quadrada. |
image_file_unreadable | O arquivo de imagem deve permitir leitura. |
image_file_too_large | A imagem não deve exceder 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 rasterizada 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 de imagem deve corresponder ao formato de imagem detectado. |
raster_image_not_square | A imagem deve ser quadrada. |
raster_image_dimensions_too_small | As dimensões da imagem devem ser de pelo menos 48×48 pixels. |
raster_image_dimensions_too_large | As dimensões da imagem não devem exceder 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 um viewBox numérico ou valores numéricos para width e height. |
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 finitos positivos. |
svg_dimensions_not_square | A largura e a altura do SVG devem ser iguais. |
svg_dimensions_too_small | As dimensões do SVG devem ser de pelo menos 48×48 pixels. |
Erros de referência a servidores MCP
As verificações comuns de pacotes validam .app.json quando um plug-in referencia
servidores MCP registrados. O portal de envio não publica referências a
integrações existentes. Um upload pela opção Somente habilidades remove .app.json. Use
Com MCP para enviar o servidor MCP diretamente.
Para pacotes locais ou de workspace, o objeto apps de nível superior mapeia cada alias de servidor MCP
para uma entrada de 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 ser um arquivo de texto em UTF-8 que permita leitura. |
app_manifest_json_malformed | .app.json contém JSON malformado 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 | id é obrigatório em cada entrada de servidor. |
app_id_wrong_type | id de cada entrada de servidor deve ser uma string. |
app_id_format | id de cada entrada de servidor deve começar com asdk_app_, connector_ ou templated_apps_, seguido de uma letra ou dígito e, depois, apenas letras, dígitos, _ ou -. |
app_entry_optional_wrong_type | O valor de optional de cada entrada de servidor deve ser true ou false quando fornecido. |
app_entry_required_wrong_type | O valor de required de cada entrada de servidor deve ser true ou false quando fornecido. |
app_not_eligible | Um pacote local ou de workspace deve referenciar um servidor MCP elegível e disponível. Os envios ao diretório devem usar Com MCP e enviar o servidor MCP diretamente. |
Avisos do pacote
Esses avisos identificam conteúdo do pacote que a validação ignora ou normaliza. Eles não impedem o envio. Revise-os para confirmar que o plug-in 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 são tratadas como um único servidor. |
undeclared_app_manifest_ignored | Um arquivo .app.json na raiz só é importado quando o campo apps do manifesto do plug-in está definido como ./.app.json. |
undeclared_mcp_manifest_ignored | Um arquivo .mcp.json na raiz só é importado quando o campo mcpServers do manifesto do plug-in está definido como ./.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 ser um diretório real que contenha SKILL.md. |
skill_frontmatter_adjusted | Os campos name e description da habilidade são normalizados durante a importação, removendo espaços em branco nas extremidades e reduzindo sequências internas de espaços em branco a um único espaço. |
skill_metadata_ignored | As configurações de interface da habilidade devem usar o mapeamento interface em agents/openai.yaml; metadata em SKILL.md não configura a interface. |
Próximos passos
Depois de resolver todos os erros de validação, volte a Enviar plug-ins para concluir o envio.