Los complementos que se envían al directorio público deben cumplir requisitos más estrictos que los que se instalan en un Espacio de trabajo. Para enviar un complemento al directorio, el paquete debe pasar las comprobaciones comunes y las comprobaciones adicionales de los campos de la ficha, los materiales de revisión, las herramientas MCP, las habilidades, los recursos y las imágenes. Esta referencia también cubre las comprobaciones comunes de los paquetes, como la validación de referencias a servidores MCP, que pueden generar errores fuera del portal de envíos.
Usa el código de error que recibas durante el envío para encontrar el requisito correspondiente. Los errores bloquean el envío. Las advertencias permiten continuar, pero conviene revisarlas antes de hacerlo.
Los valores que deben tener contenido no pueden consistir únicamente en espacios en blanco. El texto admitido excluye los caracteres de control, los separadores Unicode de línea o párrafo y los caracteres invisibles de formato no admitidos. Las URL HTTPS deben incluir un host y no pueden contener credenciales integradas ni caracteres no admitidos.
Envío final al directorio
Un paquete puede pasar la validación de carga y aun así fallar en el envío final al directorio. En el envío final se aplican límites más estrictos a la ficha y se comprueban la configuración de MCP, los análisis de las habilidades, los casos de prueba y las declaraciones de cumplimiento de las políticas.
| Campo | Regla para el envío final |
|---|---|
| Nombre del paquete | Obligatorio. Admite hasta 64 caracteres. Empieza con una letra o un dígito ASCII y usa solo letras y dígitos ASCII, _ y -. |
| Versión | Obligatoria. Usa una versión semántica de hasta 64 caracteres. |
| Nombre para mostrar | Obligatorio. Debe ocupar una sola línea y tener hasta 30 caracteres. |
| Descripción breve | Obligatoria. Debe ocupar una sola línea y tener hasta 30 caracteres. |
| Descripción larga | Obligatoria. Admite hasta 4000 caracteres y puede incluir saltos de línea. |
| Nombre del desarrollador | Obligatorio. Debe ocupar una sola línea y tener hasta 80 caracteres. |
| Categoría | Obligatoria. Elige una de las categorías admitidas que figuran en la sección Errores de la ficha y de la interfaz. |
| Capacidades | Hasta 20. Cada capacidad debe tener contenido, ocupar una sola línea y tener hasta 120 caracteres. |
| Prompts iniciales | Hasta 3. Cada prompt debe tener contenido, ser único tras normalizar el texto Unicode y los espacios en blanco, ocupar una sola línea y tener hasta 128 caracteres. No puede incluir ninguna @mention de un servidor MCP. |
| URL | Obligatorias para el envío de servidores MCP remotos y opcionales para la carga de archivos ZIP de complementos que solo incluyen habilidades. Las URL del sitio web, de soporte, de la Política de privacidad y de los términos deben usar HTTPS y tener hasta 1024 caracteres. |
| Colores de marca | Opcionales. Usa colores hexadecimales de seis dígitos. El color claro debe tener una relación de contraste de al menos 2:1 con el blanco y el oscuro, de al menos 2:1 con #212121. |
Para enviar cualquier complemento, también debes cumplir los siguientes requisitos.
- Todas las habilidades incluidas deben pasar los análisis de seguridad y protección. Los análisis pueden tardar hasta 2 horas.
- Debes contar con una identidad verificada de desarrollador o empresa y presentar todas las declaraciones de cumplimiento de las políticas que se exijan.
El envío final de un complemento MCP remoto también tiene los siguientes requisitos.
- Las URL del sitio web, de soporte, de la Política de privacidad y de los términos deben cumplir las reglas anteriores.
- Incluye la URL de una grabación de demostración que muestre los principales casos de uso y herramientas en las plataformas compatibles.
- Incluye exactamente cinco casos de prueba positivos, tres negativos y las notas de la versión.
- Proporciona una URL HTTPS del servidor MCP de producción, completa el desafío de verificación del dominio y asegúrate de que el análisis de las herramientas esté actualizado y haya finalizado correctamente.
- Para cada herramienta MCP, establece valores explícitos para
readOnlyHint,openWorldHintydestructiveHinty justifica cada valor. - Si el servidor usa OAuth, proporciona credenciales de demostración que el equipo de revisión pueda usar.
Errores de metadatos en el envío final
En estos nombres de error, subtitle se refiere a la descripción breve y description a la descripción larga.
| Nombre | Requisito |
|---|---|
submission_display_name_required |
El nombre para mostrar es obligatorio, debe tener contenido y debe ocupar una sola línea. |
submission_display_name_too_long |
El nombre para mostrar debe tener hasta 30 caracteres. |
submission_display_name_character_unsupported |
El nombre para mostrar debe contener solo texto admitido y ocupar una sola línea. |
submission_subtitle_required |
La descripción breve es obligatoria, debe tener contenido y debe ocupar una sola línea. |
submission_subtitle_too_long |
La descripción breve debe tener hasta 30 caracteres. |
submission_subtitle_character_unsupported |
La descripción breve debe contener solo texto admitido y ocupar una sola línea. |
submission_description_required |
La descripción larga es obligatoria y debe tener contenido. Se permiten saltos de línea. |
submission_description_too_long |
La descripción larga debe tener hasta 4000 caracteres. |
submission_description_character_unsupported |
La descripción larga debe contener solo texto admitido. Se permiten saltos de línea. |
submission_developer_name_required |
El nombre del desarrollador es obligatorio, debe tener contenido y debe ocupar una sola línea. |
submission_developer_name_too_long |
El nombre del desarrollador debe tener hasta 80 caracteres. |
submission_developer_name_character_unsupported |
El nombre del desarrollador debe contener solo texto admitido y ocupar una sola línea. |
plugin_capability_invalid |
Cada capacidad debe tener contenido, usar solo texto admitido, ocupar una sola línea y tener hasta 120 caracteres. |
plugin_default_prompt_mention |
Los prompts iniciales no pueden incluir @mentions de servidores MCP. |
plugin_default_prompt_duplicate |
Los prompts iniciales deben ser únicos tras normalizar el texto Unicode y los espacios en blanco. |
Errores de MCP y de revisión
Estos errores se aplican al envío de servidores MCP remotos.
| Nombre | Requisito |
|---|---|
annotations_required |
En cada herramienta MCP, los valores de readOnlyHint, openWorldHint y destructiveHint deben reflejar con precisión el comportamiento de la herramienta. |
justification_required |
Cada anotación de una herramienta MCP debe justificar el comportamiento que indica, ya sea de solo lectura, de interacción con el mundo exterior o destructivo. |
scan_required |
El análisis de las herramientas MCP debe haberse realizado correctamente en el servidor MCP de producción y estar actualizado. |
domain_verification_required |
Publica el token de verificación exacto en la URL generada /.well-known/openai-apps-challenge del host MCP o de un host superior permitido. La comprobación Verificar dominio debe completarse correctamente. |
frame_domain_explanation_required |
Para cada dominio externo que el análisis de herramientas MCP detecte en los marcos de la interfaz, explica por qué la interfaz necesita ese dominio y qué contenido proporciona. |
Errores de archivos comprimidos
Errores y advertencias al cargar archivos ZIP
La opción Solo habilidades del portal acepta paquetes ZIP de habilidades y complementos MCP locales aprobados. Los complementos MCP locales aprobados no necesitan incluir habilidades. Los errores bloquean la carga. Las advertencias requieren confirmación.
| Nombre | Requisito |
|---|---|
plugin_name_mismatch |
Al actualizar un complemento, el nombre del paquete debe coincidir con el nombre del complemento existente. |
plugin_version_unchanged |
Para publicar una nueva versión, cambia el valor de version en el archivo de manifiesto. Si reutilizas la versión publicada, debes confirmarlo. |
mcp_configuration_excluded |
La configuración de MCP se excluye a menos que tu organización tenga aprobación para enviar complementos MCP locales. Si se trata de un complemento MCP local, pídele a tu representante de OpenAI que confirme que la organización que realiza el envío está en la lista de organizaciones permitidas. Envía los servidores MCP remotos mediante Con MCP. |
app_configuration_excluded |
Los archivos ZIP que cargues no deben incluir apps ni .app.json. Para enviar servidores MCP remotos, usa Con MCP. Para servidores MCP locales, sigue las instrucciones de envío para complementos exclusivos de escritorio. |
claude_format_normalized |
El portal convierte .claude-plugin/plugin.json en .codex-plugin/plugin.json, agrega los valores predeterminados de interfaz que faltan e incorpora los campos de texto normalizados. |
manifest_normalized |
El portal guarda el archivo de manifiesto normalizado como .codex-plugin/plugin.json. Debes confirmar los cambios en los campos. |
developer_name_defaulted |
El portal asigna automáticamente el nombre del desarrollador de la ficha a partir de la identidad de desarrollador verificada que seleccionaste, independientemente del nombre que figure en el ZIP. |
Errores de estructura y límites del ZIP
| Nombre | Requisito |
|---|---|
archive_empty |
El archivo comprimido no puede estar vacío. |
archive_too_large |
El tamaño del ZIP comprimido no debe superar los 100 MB. |
archive_format_not_zip |
El archivo debe ser un ZIP válido y no estar dañado. |
archive_member_path_empty |
La ruta de una entrada del archivo comprimido no puede estar vacía. |
archive_member_path_has_outer_whitespace |
La ruta de una entrada no puede empezar ni terminar con espacios en blanco. |
archive_member_path_has_backslash |
La ruta de una entrada debe usar / y no puede incluir barras invertidas. |
archive_member_path_absolute |
La ruta de una entrada debe ser relativa a la raíz del archivo comprimido. |
archive_member_path_has_empty_segment |
La ruta de una entrada no puede incluir segmentos vacíos. |
archive_member_path_has_parent_segment |
La ruta de una entrada no puede incluir segmentos ... |
archive_member_path_too_deep |
La ruta de una entrada puede tener hasta 20 segmentos, incluido el nombre del archivo. |
archive_member_path_too_long |
La longitud de la ruta de una entrada no debe superar el límite admitido. |
archive_member_path_normalization_collision |
Las rutas de las entradas deben seguir siendo únicas tras normalizar las mayúsculas, las minúsculas y el texto Unicode. |
archive_member_type_unsupported |
Las entradas deben ser archivos regulares o directorios. |
archive_member_too_large |
Ninguna entrada puede superar los 100 MiB. |
archive_member_path_duplicate |
La ruta de cada entrada debe ser única. |
archive_member_path_type_conflict |
La ruta de un archivo no puede corresponder también a un directorio ni contener otra entrada del archivo comprimido. |
archive_too_many_entries |
El archivo comprimido no puede contener más de 5000 entradas. |
archive_uncompressed_too_large |
El tamaño del archivo descomprimido no debe superar los 512 MiB. |
archive_member_unreadable |
Cada entrada debe ser legible, estar sin cifrar y usar un método de compresión admitido. |
Errores de la raíz del complemento
| Nombre | Requisito |
|---|---|
plugin_root_missing |
La ruta seleccionada debe existir y corresponder a un directorio que contenga un complemento. |
archive_plugin_files_missing |
El ZIP debe contener un archivo de manifiesto de complemento compatible y al menos una habilidad válida (o un servidor MCP local aprobado). |
plugin_root_ambiguous |
El ZIP debe contener exactamente una raíz de complemento, ya sea en la raíz del archivo comprimido o en un único directorio de primer nivel. |
plugin_root_has_siblings |
Si el ZIP contiene un directorio de complemento en el primer nivel, no puede haber archivos en ese mismo nivel. |
Errores del archivo de manifiesto del complemento
| Nombre | Requisito |
|---|---|
plugin_manifest_missing |
El ZIP debe contener plugin.json en la raíz del complemento con un esquema compatible de Agent Plugins, o bien .codex-plugin/plugin.json, .agent-plugin/plugin.json o .claude-plugin/plugin.json. El complemento debe estar en la raíz del ZIP o en su único directorio de primer nivel. |
plugin_manifest_not_file |
El archivo de manifiesto del complemento debe ser un archivo JSON regular. |
plugin_manifest_unreadable |
El archivo de manifiesto del complemento debe contener texto UTF-8 legible. |
plugin_manifest_json_malformed |
El archivo de manifiesto del complemento debe contener JSON válido. Si hay un error de sintaxis, se indica el número de línea. |
plugin_manifest_root_not_object |
El archivo de manifiesto del complemento debe contener un objeto JSON en el nivel superior. |
codex_manifest_parent_not_directory |
.codex-plugin debe ser un directorio. |
codex_manifest_path_not_file |
.codex-plugin/plugin.json debe ser un archivo JSON regular. |
plugin_id_wrong_type |
id debe ser una cadena si se incluye. |
plugin_id_empty |
id no puede estar vacío si se incluye. |
plugin_name_missing |
name es obligatorio. |
plugin_name_wrong_type |
name debe ser una cadena. |
plugin_name_empty |
name no puede estar vacío. |
plugin_name_too_long |
name debe tener hasta 64 caracteres. |
plugin_name_format |
name debe empezar con una letra o un dígito ASCII y solo puede contener letras y dígitos ASCII, _ o -. |
plugin_version_missing |
version es obligatorio. |
plugin_version_wrong_type |
version debe ser una cadena. |
plugin_version_empty |
version debe ser una cadena no vacía que represente una versión semántica, como 1.0.0. |
plugin_version_not_semver |
version debe seguir el formato de versiones semánticas, como 1.0.0. |
plugin_version_too_long |
version debe tener hasta 64 caracteres. |
plugin_description_missing |
description es obligatorio. |
plugin_description_wrong_type |
description debe ser una cadena. |
plugin_description_empty |
description no puede estar vacío. |
plugin_description_too_long |
description debe tener hasta 1024 caracteres. |
plugin_description_character_unsupported |
description debe contener solo texto admitido. Se permiten saltos de línea. |
plugin_developer_missing |
author.name es obligatorio. interface.developerName también es obligatorio y se informa por separado si falta. |
plugin_author_wrong_type |
author debe ser un objeto. |
plugin_author_name_wrong_type |
author.name debe ser una cadena. |
plugin_author_name_empty |
author.name no puede estar vacío. |
plugin_author_name_too_long |
author.name debe tener hasta 120 caracteres. |
plugin_author_name_character_unsupported |
author.name debe contener solo texto admitido. |
plugin_author_email_wrong_type |
author.email debe ser una cadena si se incluye. |
plugin_author_email_empty |
author.email no puede estar vacío si se incluye. |
plugin_author_email_too_long |
author.email debe tener hasta 320 caracteres. |
plugin_author_email_character_unsupported |
author.email debe contener solo texto admitido. |
plugin_author_url_wrong_type |
author.url debe ser una cadena si se incluye. |
plugin_author_url_empty |
author.url no puede estar vacío si se incluye. |
plugin_author_url_not_https |
author.url debe ser una URL HTTPS. |
plugin_author_url_has_credentials |
author.url no puede contener credenciales. |
plugin_author_url_too_long |
author.url debe tener hasta 2048 caracteres. |
plugin_author_url_character_unsupported |
author.url debe contener solo texto admitido. |
Errores de la ficha y de la interfaz
El objeto interface del archivo de manifiesto del complemento define la ficha pública que ven los usuarios. Se encuentra en .codex-plugin/plugin.json y usa campos como displayName y shortDescription.
{
"interface": {
"displayName": "Example Plugin",
"shortDescription": "Summarize documents",
"longDescription": "Summarize and organize documents.",
"developerName": "Example",
"category": "Productivity",
"capabilities": ["Summarize documents"]
}
}Las cuatro URL de la ficha (sitio web, Política de privacidad, términos y soporte) son opcionales al cargar archivos ZIP de complementos que solo incluyen habilidades. Son obligatorias para el envío de servidores MCP remotos. El límite por URL es de 2048 caracteres para la validación del paquete y de 1024 para el envío final al directorio.
| Nombre | Requisito |
|---|---|
plugin_interface_wrong_type |
El campo interface del archivo de manifiesto del complemento debe ser un objeto JSON. |
plugin_display_name_wrong_type |
interface.displayName debe ser una cadena. |
plugin_display_name_empty |
interface.displayName es obligatorio y no puede estar vacío. |
plugin_display_name_too_long |
interface.displayName admite hasta 80 caracteres en la validación del paquete y hasta 30 en el envío final al directorio. |
plugin_display_name_character_unsupported |
interface.displayName debe contener solo texto admitido. |
plugin_short_description_missing |
interface.shortDescription es obligatorio y debe ocupar una sola línea. Admite hasta 240 caracteres en la validación del paquete y hasta 30 en el envío final al directorio. |
plugin_short_description_wrong_type |
interface.shortDescription debe ser una cadena. |
plugin_short_description_empty |
interface.shortDescription no puede estar vacío. |
plugin_short_description_too_long |
interface.shortDescription admite hasta 240 caracteres en la validación del paquete y hasta 30 en el envío final al directorio. |
plugin_short_description_character_unsupported |
interface.shortDescription debe contener solo texto admitido. |
plugin_long_description_wrong_type |
interface.longDescription debe ser una cadena. |
plugin_long_description_empty |
interface.longDescription es obligatorio y no puede estar vacío. |
plugin_long_description_too_long |
interface.longDescription debe tener hasta 4000 caracteres. |
plugin_long_description_character_unsupported |
interface.longDescription debe contener solo texto admitido. Se permiten saltos de línea. |
plugin_developer_name_wrong_type |
interface.developerName debe ser una cadena. |
plugin_developer_name_empty |
interface.developerName es obligatorio y no puede estar vacío. |
plugin_developer_name_too_long |
interface.developerName admite hasta 120 caracteres en la validación del paquete y hasta 80 en el envío final al directorio. |
plugin_developer_name_character_unsupported |
interface.developerName debe contener solo texto admitido. |
plugin_category_wrong_type |
interface.category debe ser una cadena. |
plugin_category_empty |
interface.category no puede estar vacío si se incluye. Omítelo para usar Other. |
plugin_category_unknown |
interface.category debe ser Productivity, Creativity, Developer Tools, Business & Operations, Data & Analytics, Communication, Education & Research, Security, Finance, Healthcare, Travel, Entertainment u Other. |
plugin_category_character_unsupported |
interface.category debe contener solo texto admitido. |
plugin_capabilities_wrong_type |
interface.capabilities debe ser una lista de cadenas. |
plugin_capabilities_too_many |
interface.capabilities debe contener hasta 20 entradas. |
plugin_capability_wrong_type |
Cada entrada de interface.capabilities debe ser una cadena. |
plugin_capability_empty |
Ninguna entrada de interface.capabilities puede estar vacía si se incluye. |
plugin_capability_too_long |
Cada entrada de interface.capabilities debe tener hasta 120 caracteres. |
plugin_capability_character_unsupported |
Cada entrada de interface.capabilities debe contener solo texto admitido. |
plugin_website_url_wrong_type |
interface.websiteURL debe ser una cadena si se incluye. |
plugin_website_url_empty |
interface.websiteURL no puede estar vacío si se incluye. |
plugin_website_url_format |
interface.websiteURL debe ser una URL HTTPS. |
plugin_website_url_too_long |
interface.websiteURL debe respetar los límites de longitud de las URL de la ficha. |
plugin_privacy_policy_url_wrong_type |
interface.privacyPolicyURL debe ser una cadena si se incluye. |
plugin_privacy_policy_url_empty |
interface.privacyPolicyURL no puede estar vacío si se incluye. |
plugin_privacy_policy_url_format |
interface.privacyPolicyURL debe ser una URL HTTPS. |
plugin_privacy_policy_url_too_long |
interface.privacyPolicyURL debe respetar los límites de longitud de las URL de la ficha. |
plugin_terms_of_service_url_wrong_type |
interface.termsOfServiceURL debe ser una cadena si se incluye. |
plugin_terms_of_service_url_empty |
interface.termsOfServiceURL no puede estar vacío si se incluye. |
plugin_terms_of_service_url_format |
interface.termsOfServiceURL debe ser una URL HTTPS. |
plugin_terms_of_service_url_too_long |
interface.termsOfServiceURL debe respetar los límites de longitud de las URL de la ficha. |
plugin_support_url_wrong_type |
interface.supportURL debe ser una cadena si se incluye. |
plugin_support_url_empty |
interface.supportURL no puede estar vacío si se incluye. |
plugin_support_url_format |
interface.supportURL debe ser una URL HTTPS. |
plugin_support_url_too_long |
interface.supportURL debe respetar los límites de longitud de las URL de la ficha. |
plugin_homepage_wrong_type |
homepage debe ser una cadena si se incluye. |
plugin_homepage_empty |
homepage no puede estar vacío si se incluye. |
plugin_homepage_format |
homepage debe ser una URL HTTPS. |
plugin_homepage_too_long |
homepage debe tener hasta 2048 caracteres. |
plugin_brand_color_wrong_type |
interface.brandColor debe ser una cadena si se incluye. |
plugin_brand_color_empty |
interface.brandColor no puede estar vacío si se incluye. |
plugin_brand_color_format |
interface.brandColor debe ser un color hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_dark_wrong_type |
interface.brandColorDark debe ser una cadena si se incluye. |
plugin_brand_color_dark_empty |
interface.brandColorDark no puede estar vacío si se incluye. |
plugin_brand_color_dark_format |
interface.brandColorDark debe ser un color hexadecimal de seis dígitos, como #1ABCFE. |
plugin_brand_color_contrast |
interface.brandColor debe tener una relación de contraste de al menos 2:1 con el blanco. |
plugin_brand_color_dark_contrast |
interface.brandColorDark debe tener una relación de contraste de al menos 2:1 con #212121. |
plugin_default_prompt_wrong_type |
interface.defaultPrompt debe ser una cadena o una lista de cadenas. |
plugin_default_prompt_too_many |
interface.defaultPrompt puede contener hasta tres prompts. |
plugin_default_prompt_entry_wrong_type |
Cada entrada de interface.defaultPrompt debe ser una cadena. |
plugin_default_prompt_empty |
Ninguna entrada de interface.defaultPrompt puede estar vacía si se incluye. |
plugin_default_prompt_too_long |
Cada entrada de interface.defaultPrompt admite hasta 512 caracteres en la validación del paquete y hasta 128 en el envío final al directorio. |
plugin_default_prompt_character_unsupported |
Cada entrada de interface.defaultPrompt debe contener solo texto admitido y ocupar una sola línea. |
Errores de contenido del complemento
| Nombre | Requisito |
|---|---|
plugin_skills_path_wrong_type |
skills debe ser una cadena que indique la ruta al directorio skills/ de la raíz. |
plugin_skills_path_empty |
Si se incluye skills, debe ser una ruta no vacía al directorio skills/ de la raíz. |
plugin_skills_path_unsupported |
skills debe apuntar al directorio skills/ de la raíz. |
plugin_skills_directory_missing |
Si se declara el directorio skills/ en la raíz, debe existir. |
plugin_skills_path_not_directory |
Si se declara skills/ en la raíz, debe ser un directorio. |
plugin_apps_path_wrong_type |
apps debe ser una cadena que indique la ruta al archivo .app.json de la raíz. |
plugin_apps_path_empty |
Si se incluye apps, debe ser una ruta no vacía al archivo .app.json de la raíz. |
plugin_apps_path_unsupported |
apps debe apuntar al archivo .app.json de la raíz. |
plugin_apps_file_missing |
Si se declara el archivo .app.json en la raíz, debe existir. |
plugin_apps_path_not_file |
Si se declara .app.json en la raíz, debe ser un archivo regular. |
plugin_mcp_path_wrong_type |
mcpServers debe ser una cadena que indique la ruta al archivo .mcp.json de la raíz. |
plugin_mcp_path_empty |
mcpServers debe ser una ruta no vacía. Asígnale el valor ./.mcp.json o elimina el campo. |
plugin_mcp_path_unsupported |
mcpServers debe apuntar al archivo .mcp.json de la raíz. |
plugin_mcp_file_missing |
mcpServers declara .mcp.json en la raíz, pero ese archivo no existe. |
plugin_mcp_path_not_file |
.mcp.json en la raíz debe ser un archivo regular. |
plugin_runtime_surface_missing |
El ZIP que envíes al directorio público debe contener al menos una habilidad válida (o un servidor MCP local aprobado). Los paquetes locales y los de un Espacio de trabajo también pueden hacer referencia a un servidor MCP que cumpla los requisitos. |
Errores del archivo de manifiesto de MCP
Estos errores se aplican al archivo de compatibilidad .mcp.json. Al importar un paquete portátil, se generan este archivo y .codex-plugin/plugin.json a partir de los archivos plugin.json y mcp.json de la raíz. Los errores de rutas de componentes descritos anteriormente también pueden referirse a estos archivos generados. Corrige la configuración original del paquete portátil. No cambies el nombre de mcp.json a .mcp.json solo porque un diagnóstico de compatibilidad mencione ese archivo.
| Nombre | Requisito |
|---|---|
mcp_manifest_unreadable |
.mcp.json debe contener texto UTF-8 legible. |
mcp_manifest_json_malformed |
.mcp.json debe contener JSON válido. Si hay un error de sintaxis, se indica el número de línea. |
mcp_manifest_wrong_type |
.mcp.json debe contener un objeto JSON en el nivel superior. |
mcp_servers_missing |
.mcp.json debe contener el campo mcpServers en el nivel superior. |
mcp_servers_wrong_type |
mcpServers debe ser un objeto. |
mcp_server_name_empty |
El nombre de cada servidor MCP debe contener al menos un carácter que no sea un espacio en blanco. |
mcp_server_wrong_type |
Cada valor de mcpServers.<server-name> debe ser un objeto que contenga la declaración de ese servidor. |
Errores de las habilidades
| Nombre | Requisito |
|---|---|
skill_manifest_missing |
La habilidad debe contener un archivo SKILL.md. |
skill_bundle_too_large |
El tamaño del paquete comprimido de cada habilidad no debe superar el límite en MiB que indica el error. |
skill_directory_hidden |
Los nombres de los directorios de habilidades no pueden empezar con .. |
skill_manifest_nested |
Cada directorio de habilidad debe estar directamente dentro de skills/. |
skill_manifest_not_regular_file |
SKILL.md debe ser un archivo regular. |
skill_manifest_unreadable |
SKILL.md debe ser legible. |
skill_manifest_invalid_utf8 |
SKILL.md debe contener texto UTF-8 válido. |
skill_frontmatter_missing |
SKILL.md debe empezar con un bloque de metadatos YAML delimitado por líneas con ---. |
skill_frontmatter_unclosed |
El bloque de metadatos YAML de SKILL.md debe terminar con ---. |
skill_frontmatter_yaml_malformed |
El bloque de metadatos de SKILL.md debe contener YAML válido. |
skill_frontmatter_wrong_type |
El bloque de metadatos de SKILL.md debe contener un mapa YAML. |
skill_name_missing |
name es obligatorio y no puede estar vacío. |
skill_name_wrong_type |
name debe ser una cadena. |
skill_name_empty |
name no puede estar vacío. |
skill_name_character_unsupported |
El campo name del bloque de metadatos de la habilidad debe contener solo texto admitido. |
skill_description_missing |
description es obligatorio y no puede estar vacío. |
skill_description_wrong_type |
description debe ser una cadena. |
skill_description_empty |
description no puede estar vacío. |
skill_description_too_long |
description debe tener hasta 1024 caracteres. |
skill_description_character_unsupported |
El campo description del bloque de metadatos de la habilidad debe contener solo texto admitido. |
skill_body_empty |
Las instrucciones de la habilidad no pueden estar vacías. |
skill_identity_too_long |
La combinación del nombre del complemento y el de la habilidad (plugin-name:skill-name) debe tener hasta 64 caracteres. |
skill_identity_duplicate |
El valor de name de cada habilidad debe ser único dentro del complemento. |
Errores de metadatos del agente de una habilidad
Una habilidad incluida en el paquete puede definir su propia interface en skills/<skill>/agents/openai.yaml. Esta configuración determina cómo se muestra la habilidad a los usuarios y es independiente de interface en el archivo de manifiesto del complemento. Los campos de la interfaz de la habilidad usan snake_case.
interface:
display_name: "Summarize documents"
short_description: "Summarize a document"
icon_small: "./assets/icon.png"
default_prompt: "Summarize the selected document."| Nombre | Requisito |
|---|---|
skill_agent_not_regular_file |
agents/openai.yaml debe ser un archivo regular. |
skill_agent_unreadable |
agents/openai.yaml debe ser legible. |
skill_agent_invalid_utf8 |
agents/openai.yaml debe contener texto UTF-8 válido. |
skill_agent_yaml_malformed |
agents/openai.yaml debe contener YAML válido. |
skill_agent_top_level_wrong_type |
agents/openai.yaml debe contener un mapa YAML en el nivel superior. |
skill_agent_interface_missing |
interface es obligatorio en agents/openai.yaml si se incluye ese archivo. |
skill_agent_interface_wrong_type |
interface en agents/openai.yaml debe ser un mapa YAML. |
skill_agent_display_name_missing |
interface.display_name es obligatorio y no puede estar vacío. |
skill_agent_display_name_wrong_type |
interface.display_name debe ser una cadena. |
skill_agent_display_name_empty |
interface.display_name no puede estar vacío. |
skill_agent_short_description_missing |
interface.short_description es obligatorio y no puede estar vacío. |
skill_agent_short_description_wrong_type |
interface.short_description debe ser una cadena. |
skill_agent_short_description_empty |
interface.short_description no puede estar vacío. |
skill_agent_icon_small_wrong_type |
Si se incluye interface.icon_small, debe ser una ruta relativa no vacía a un archivo. |
skill_agent_icon_small_empty |
Si se incluye interface.icon_small, debe ser una ruta relativa no vacía a un archivo, como assets/icon.png. |
skill_agent_icon_large_wrong_type |
Si se incluye interface.icon_large, debe ser una ruta relativa no vacía a un archivo. |
skill_agent_icon_large_empty |
Si se incluye interface.icon_large, debe ser una ruta relativa no vacía a un archivo, como assets/icon.png. |
skill_agent_brand_color_wrong_type |
interface.brand_color debe ser una cadena si se incluye. |
skill_agent_brand_color_empty |
Si se incluye interface.brand_color, no puede estar vacío y debe contener un color hexadecimal de seis dígitos, como #1ABCFE. |
skill_agent_brand_color_format |
interface.brand_color debe ser un color hexadecimal de seis dígitos, como #1ABCFE. |
skill_agent_default_prompt_wrong_type |
interface.default_prompt debe ser una cadena si se incluye. |
skill_agent_default_prompt_empty |
interface.default_prompt no puede estar vacío si se incluye. |
skill_agent_policy_wrong_type |
policy debe ser un mapa YAML si se incluye. |
skill_agent_allow_implicit_invocation_wrong_type |
policy solo puede contener products y allow_implicit_invocation. products debe contener CHAT, CODEX o ambos, y allow_implicit_invocation debe ser true o false. |
skill_agent_dependencies_wrong_type |
dependencies debe ser un mapa YAML. Solo se admite tools. |
skill_agent_dependency_unsupported |
Solo se admite dependencies.tools en agents/openai.yaml. |
Errores de rutas de recursos
| Nombre | Requisito |
|---|---|
declared_asset_path_wrong_type |
El campo del recurso indicado debe ser una cadena que contenga la ruta a un archivo. |
declared_asset_path_empty |
El campo del recurso indicado no puede estar vacío. |
declared_asset_path_has_outer_whitespace |
El campo del recurso indicado no puede empezar ni terminar con espacios en blanco. |
declared_asset_path_has_control_character |
El campo del recurso indicado no puede contener caracteres del intervalo U+0000–U+001F ni el carácter U+007F. |
branding_asset_path_missing_root_prefix |
El campo del recurso indicado debe empezar con ./. |
declared_asset_path_unsafe |
El campo del recurso indicado debe contener una ruta relativa dentro del complemento. No puede incluir una ruta absoluta, un prefijo de unidad ni un segmento .. para subir de directorio. |
declared_asset_path_outside_package |
El campo del recurso indicado debe hacer referencia a un archivo dentro del complemento. |
declared_asset_file_missing |
El campo del recurso indicado hace referencia a un archivo que no existe. |
declared_asset_not_regular_file |
El campo del recurso indicado debe hacer referencia a un archivo. No se admiten directorios ni archivos especiales. |
Errores de imágenes
Las imágenes de marca que aparecen en el directorio deben usar un tipo de archivo admitido y cumplir los siguientes límites de tamaño y dimensiones. Estas reglas se aplican a los recursos de marca incluidos en el paquete.
| Nombre | Requisito |
|---|---|
plugin_logo_path_missing |
interface.logo es obligatorio y debe hacer referencia a una imagen cuadrada. |
plugin_composer_icon_path_missing |
interface.composerIcon es obligatorio y debe hacer referencia a una imagen cuadrada. |
image_file_unreadable |
El archivo de imagen debe ser legible. |
image_file_too_large |
La imagen no debe superar los 5 MiB. |
image_file_format_unsupported |
El nombre del archivo de imagen debe terminar en .png, .jpg, .jpeg, .webp o .svg. |
raster_image_decode_failed |
La imagen de mapa de bits debe ser un archivo PNG, JPEG o WebP que pueda decodificarse de forma segura. |
raster_image_extension_content_mismatch |
La extensión del archivo debe coincidir con el formato de imagen detectado. |
raster_image_not_square |
La imagen debe ser cuadrada. |
raster_image_dimensions_too_small |
La imagen debe medir al menos 48×48 píxeles. |
raster_image_dimensions_too_large |
Las dimensiones de la imagen no deben superar los 4096×4096 píxeles. |
svg_xml_malformed |
El SVG debe contener XML válido en UTF-8. |
svg_root_element_invalid |
El elemento raíz del SVG debe ser <svg>. |
svg_dimensions_missing |
El SVG debe definir un viewBox con valores numéricos o los atributos width y height con valores numéricos. |
svg_dimensions_not_numeric |
Las dimensiones del SVG deben ser numéricas y expresarse sin unidades ni porcentajes. |
svg_dimensions_not_positive |
El ancho y el alto del SVG deben ser números positivos y finitos. |
svg_dimensions_not_square |
El ancho y el alto del SVG deben ser iguales. |
svg_dimensions_too_small |
El SVG debe medir al menos 48×48 píxeles. |
Errores de referencias a servidores MCP
Las comprobaciones comunes de los paquetes validan .app.json cuando un complemento hace referencia a servidores MCP registrados. El portal de envíos no publica referencias a integraciones existentes. Al cargar un paquete mediante Solo habilidades, el portal elimina .app.json. Usa Con MCP para enviar el servidor MCP directamente.
En los paquetes locales o de un Espacio de trabajo, el objeto apps del nivel superior asocia cada alias de servidor MCP con una entrada de servidor registrado. Estos nombres de configuración y códigos de error conservan la forma literal app.
| Nombre | Requisito |
|---|---|
app_manifest_unreadable |
.app.json debe contener texto UTF-8 legible. |
app_manifest_json_malformed |
.app.json contiene un error de sintaxis JSON cerca de la línea indicada. |
app_manifest_wrong_type |
.app.json debe contener un objeto JSON en el nivel superior. |
app_entries_missing |
apps es obligatorio. |
app_entries_wrong_type |
apps debe ser un objeto. |
app_entry_wrong_type |
Cada entrada de servidor debe ser un objeto. |
app_id_missing |
El campo id es obligatorio en cada entrada de servidor. |
app_id_wrong_type |
El campo id de cada entrada de servidor debe ser una cadena. |
app_id_format |
El campo id de cada entrada de servidor debe empezar con asdk_app_, connector_ o templated_apps_. Después del prefijo debe haber una letra o un dígito. A partir de ahí, solo se permiten letras, dígitos, _ o -. |
app_entry_optional_wrong_type |
Si se incluye optional en una entrada de servidor, su valor debe ser true o false. |
app_entry_required_wrong_type |
Si se incluye required en una entrada de servidor, su valor debe ser true o false. |
app_not_eligible |
Un paquete local o de un Espacio de trabajo debe hacer referencia a un servidor MCP disponible que cumpla los requisitos. Para enviar el servidor MCP al directorio, usa Con MCP y envíalo directamente. |
Advertencias del paquete
Estas advertencias indican qué contenido del paquete se ignora o se normaliza durante la validación. No bloquean el envío. Revísalas para confirmar que el complemento que envías contiene los archivos y la configuración que esperas.
| Nombre | Requisito |
|---|---|
duplicate_app_reference |
Cada ID de servidor debe aparecer una sola vez en .app.json. Las referencias duplicadas se tratan como un único servidor. |
undeclared_app_manifest_ignored |
El archivo .app.json de la raíz solo se importa si el campo apps del archivo de manifiesto del complemento tiene el valor ./.app.json. |
undeclared_mcp_manifest_ignored |
El archivo .mcp.json de la raíz solo se importa si el campo mcpServers del archivo de manifiesto del complemento tiene el valor ./.mcp.json. |
skill_file_ignored |
Los archivos que se encuentran directamente en skills/ no se importan como habilidades. Cada habilidad debe estar en un directorio que contenga SKILL.md. |
skill_symlink_ignored |
Los enlaces simbólicos que se encuentran directamente en skills/ no se importan como habilidades. Cada habilidad debe ser un directorio real que contenga SKILL.md. |
skill_frontmatter_adjusted |
Al importar la habilidad, se normalizan los campos name y description eliminando los espacios en blanco al principio y al final y reduciendo a uno los espacios en blanco consecutivos del interior. |
skill_metadata_ignored |
La configuración de la interfaz de la habilidad debe usar el mapa interface de agents/openai.yaml. El campo metadata de SKILL.md no configura la interfaz. |
Próximos pasos
Una vez que hayas corregido todos los errores de validación, vuelve a Enviar complementos para completar el envío.