Los complementos enviados al directorio público deben cumplir requisitos más exigentes que los instalados en un espacio de trabajo. Los envíos al directorio deben superar las comprobaciones comunes de paquetes y las comprobaciones adicionales de los campos de la ficha, los materiales para la revisión, las herramientas MCP, las habilidades, los recursos y las imágenes. Esta referencia también abarca las comprobaciones comunes de paquetes, como las referencias a servidores MCP, que pueden aparecer fuera del portal de envío.
Usa el código de error que se devuelve durante el envío para encontrar el requisito correspondiente. Los errores bloquean el envío. Las advertencias no lo bloquean, pero debes revisarlas antes de continuar.
Los valores que no pueden estar vacíos tampoco pueden contener únicamente espacios en blanco. El texto admitido excluye los caracteres de control, los separadores de línea o párrafo Unicode y los caracteres de formato invisibles no admitidos. Las URL HTTPS deben incluir un host y no contener credenciales incorporadas ni caracteres no admitidos.
Envío final al directorio
Un paquete puede superar la validación de carga y aun así fallar en el envío final al directorio. El envío final aplica límites más estrictos a la ficha y comprueba la configuración de MCP, los análisis de habilidades, los casos de prueba y las declaraciones de cumplimiento de políticas.
| Campo | Regla para el envío final |
|---|---|
| Nombre del paquete | Obligatorio; como máximo 64 caracteres. Comienza con una letra ASCII o un dígito y usa solo letras ASCII, dígitos, _ y -. |
| Versión | Obligatoria; usa una versión semántica de como máximo 64 caracteres. |
| Nombre para mostrar | Obligatorio; una sola línea; como máximo 30 caracteres. |
| Descripción breve | Obligatoria; una sola línea; como máximo 30 caracteres. |
| Descripción larga | Obligatoria; como máximo 4000 caracteres. Se permiten saltos de línea. |
| Nombre del desarrollador | Obligatorio; una sola línea; como máximo 80 caracteres. |
| Categoría | Obligatoria; elige una categoría admitida de la sección Errores de la ficha y de la interfaz. |
| Capacidades | Como máximo 20. Cada capacidad debe ocupar una sola línea y tener como máximo 120 caracteres; no puede estar vacía. |
| Prompts iniciales | Como máximo 3. Cada prompt debe ser único después de normalizar Unicode y los espacios en blanco, ocupar una sola línea y tener como máximo 128 caracteres; no puede estar vacío ni contener ninguna @mention a un servidor MCP. |
| URL | Obligatorias para los envíos de MCP remoto; opcionales para las cargas ZIP de complementos que solo contienen habilidades. Las URL del sitio web, de soporte, de la política de privacidad y de los términos deben usar HTTPS y tener como máximo 1024 caracteres. |
| Colores de marca | Colores hexadecimales de seis dígitos opcionales. El color claro debe tener un contraste mínimo de 2:1 con el blanco, y el color oscuro debe tener un contraste mínimo de 2:1 con #212121. |
Todo envío de complementos también requiere:
- Superar los análisis de seguridad y protección de cada habilidad incluida. Los análisis pueden tardar hasta 2 horas.
- Una identidad verificada de desarrollador o empresa y todas las declaraciones de cumplimiento de políticas requeridas.
Para un complemento de MCP remoto, el envío final también requiere:
- URL del sitio web, de soporte, de la política de privacidad y de los términos que cumplan las reglas anteriores.
- Una URL de una demostración grabada que muestre los principales casos de uso y herramientas en las plataformas compatibles.
- Exactamente cinco casos de prueba positivos, tres casos de prueba negativos y notas de la versión.
- Una URL HTTPS del servidor MCP de producción, un desafío de verificación de dominio completado y un análisis de herramientas exitoso y vigente.
- Valores explícitos de
readOnlyHint,openWorldHintydestructiveHint, y una justificación de cada valor en todas las herramientas MCP. - Credenciales de demostración listas para que los revisores las usen cuando el servidor utilice OAuth.
- Capturas de pantalla solo cuando el servidor MCP proporcione una interfaz personalizada. Si agregas capturas de pantalla, proporciona una imagen PNG o JPEG por cada prompt inicial. Cada captura debe tener exactamente 706 píxeles de ancho y entre 400 y 860 píxeles de alto.
Errores de metadatos en el envío final
En estos nombres de error, subtitle significa descripción breve y description
significa descripción larga.
| Nombre | Requisito |
|---|---|
submission_display_name_required | El nombre para mostrar es obligatorio, no puede estar vacío y debe ocupar una sola línea. |
submission_display_name_too_long | El nombre para mostrar debe tener 30 caracteres o menos. |
submission_display_name_character_unsupported | El nombre para mostrar debe usar texto admitido y ocupar una sola línea. |
submission_subtitle_required | La descripción breve es obligatoria, no puede estar vacía y debe ocupar una sola línea. |
submission_subtitle_too_long | La descripción breve debe tener 30 caracteres o menos. |
submission_subtitle_character_unsupported | La descripción breve debe usar texto admitido y ocupar una sola línea. |
submission_description_required | La descripción larga es obligatoria y no puede estar vacía. Se permiten saltos de línea. |
submission_description_too_long | La descripción larga debe tener 4000 caracteres o menos. |
submission_description_character_unsupported | La descripción larga debe usar texto admitido. Se permiten saltos de línea. |
submission_developer_name_required | El nombre del desarrollador es obligatorio, no puede estar vacío y debe ocupar una sola línea. |
submission_developer_name_too_long | El nombre del desarrollador debe tener 80 caracteres o menos. |
submission_developer_name_character_unsupported | El nombre del desarrollador debe usar texto admitido y ocupar una sola línea. |
plugin_capability_invalid | Cada capacidad debe usar texto admitido, ocupar una sola línea y tener 120 caracteres o menos; no puede estar vacía. |
plugin_default_prompt_mention | Los prompts iniciales no deben contener @mentions a servidores MCP. |
plugin_default_prompt_duplicate | Los prompts iniciales deben ser únicos después de normalizar Unicode y los espacios en blanco. |
Errores de MCP y de revisión
Estos errores se aplican a los envíos de MCP remoto.
| Nombre | Requisito |
|---|---|
annotations_required | Cada herramienta MCP debe establecer readOnlyHint, openWorldHint y destructiveHint con precisión. |
justification_required | Cada anotación de una herramienta MCP debe incluir una justificación de su comportamiento de solo lectura, de mundo abierto o destructivo. |
scan_required | Las herramientas MCP deben contar con un escaneo exitoso y vigente del servidor MCP de producción. |
domain_verification_required | El token de verificación exacto debe estar alojado en la URL /.well-known/openai-apps-challenge generada, en el host MCP o en un host superior permitido, y la acción Verificar dominio debe completarse correctamente. |
frame_domain_explanation_required | Cada dominio de marcos externos que reporte el escaneo de herramientas MCP debe incluir una explicación de por qué la interfaz de usuario lo necesita y qué contenido proporciona. |
screenshots_not_allowed | Solo se permiten capturas de pantalla cuando el escaneo vigente de herramientas MCP reporta una plantilla de salida de interfaz de usuario. |
Errores del archivo comprimido
Errores y advertencias al cargar archivos ZIP
La opción Solo habilidades del portal acepta paquetes ZIP de habilidades. Los errores bloquean la carga; las advertencias requieren confirmación.
| Nombre | Requisito |
|---|---|
plugin_name_mismatch | El nombre del paquete en una actualización debe coincidir con el nombre del complemento existente. |
plugin_version_unchanged | Una nueva versión debe usar un valor diferente de version en el archivo de manifiesto; reutilizar la versión publicada requiere confirmación. |
mcp_configuration_excluded | Las cargas de solo habilidades excluyen mcpServers, mcp.json y .mcp.json. Envía un servidor MCP remoto mediante Con MCP. |
app_configuration_excluded | Los archivos ZIP de solo habilidades que se carguen no deben incluir apps ni .app.json; los complementos con servidores MCP deben usar Con MCP. |
screenshot_configuration_excluded | Los archivos ZIP de solo habilidades que se carguen no deben incluir interface.screenshots; las capturas de pantalla requieren Con MCP y una interfaz de usuario personalizada. |
claude_format_normalized | .claude-plugin/plugin.json se convierte a .codex-plugin/plugin.json, y el portal agrega los valores predeterminados de interfaz que falten y los campos de texto normalizados. |
manifest_normalized | El portal guarda el archivo de manifiesto normalizado como .codex-plugin/plugin.json; los campos modificados requieren confirmación. |
developer_name_defaulted | author.name y interface.developerName deben coincidir; de lo contrario, se usa la identidad verificada seleccionada para ambos después de la confirmación. |
Errores de estructura y límites del ZIP
| Nombre | Requisito |
|---|---|
archive_empty | El archivo comprimido no debe estar vacío. |
archive_too_large | El ZIP comprimido debe tener un tamaño máximo de 100 MB. |
archive_format_not_zip | El archivo comprimido debe ser un archivo ZIP válido y sin daños. |
archive_member_path_empty | La ruta de la entrada del archivo comprimido no debe estar vacía. |
archive_member_path_has_outer_whitespace | La ruta de la entrada del archivo comprimido no debe comenzar ni terminar con espacios en blanco. |
archive_member_path_has_backslash | La ruta de la entrada del archivo comprimido debe usar /, no barras invertidas. |
archive_member_path_absolute | La ruta de la entrada del archivo comprimido debe ser relativa a la raíz del archivo comprimido. |
archive_member_path_has_empty_segment | La ruta de la entrada del archivo comprimido no debe contener segmentos vacíos. |
archive_member_path_has_parent_segment | La ruta de la entrada del archivo comprimido no debe contener segmentos ... |
archive_member_path_too_deep | La ruta de la entrada del archivo comprimido debe contener como máximo 20 segmentos, incluido el nombre del archivo. |
archive_member_path_too_long | La ruta de la entrada del archivo comprimido debe respetar el límite de longitud de ruta admitido. |
archive_member_path_normalization_collision | Las rutas de las entradas del archivo comprimido deben seguir siendo únicas después de normalizar las mayúsculas, las minúsculas y Unicode. |
archive_member_type_unsupported | Las entradas del archivo comprimido deben ser archivos regulares o directorios. |
archive_member_too_large | La entrada del archivo comprimido no debe superar los 100 MiB. |
archive_member_path_duplicate | La ruta de la entrada del archivo comprimido debe ser única. |
archive_member_path_type_conflict | Una ruta de archivo no puede ser también un directorio ni contener otra entrada del archivo comprimido. |
archive_too_many_entries | El archivo comprimido no debe contener más de 5000 entradas. |
archive_uncompressed_too_large | El contenido extraído del archivo comprimido no debe superar los 512 MiB. |
archive_member_unreadable | Cada entrada del archivo comprimido debe poder leerse, no debe estar cifrada y debe usar un método de compresión compatible. |
Errores de la raíz del complemento
| Nombre | Requisito |
|---|---|
plugin_root_missing | La ruta seleccionada debe existir y ser un directorio que contenga un complemento. |
archive_plugin_files_missing | Un ZIP de solo habilidades debe contener un archivo de manifiesto de complemento compatible y al menos una habilidad válida. |
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 directorio de nivel superior. |
plugin_root_has_siblings | Un ZIP con un directorio de complemento de nivel superior no debe contener archivos al mismo nivel que ese directorio. |
Errores del archivo de manifiesto del complemento
| Nombre | Requisito |
|---|---|
plugin_manifest_missing | El ZIP debe contener plugin.json en la raíz con un esquema de Agent Plugins compatible, o bien .codex-plugin/plugin.json, .agent-plugin/plugin.json o .claude-plugin/plugin.json, en la raíz del archivo comprimido o en su único directorio de nivel superior. |
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 ser texto UTF-8 legible. |
plugin_manifest_json_malformed | El archivo de manifiesto del complemento debe contener JSON válido; los errores de sintaxis se reportan con un 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 de texto cuando se proporcione. |
plugin_id_empty | id no debe estar vacío cuando se proporcione. |
plugin_name_missing | name es obligatorio. |
plugin_name_wrong_type | name debe ser una cadena de texto. |
plugin_name_empty | name no debe estar vacío. |
plugin_name_too_long | name debe tener 64 caracteres o menos. |
plugin_name_format | name debe comenzar con una letra o un dígito ASCII y contener únicamente letras ASCII, dígitos, _ o -. |
plugin_version_missing | version es obligatorio. |
plugin_version_wrong_type | version debe ser una cadena de texto. |
plugin_version_empty | version debe ser una cadena de texto no vacía con una versión semántica, como 1.0.0. |
plugin_version_not_semver | version debe usar el formato de versionado semántico, como 1.0.0. |
plugin_version_too_long | version debe tener 64 caracteres o menos. |
plugin_description_missing | description es obligatorio. |
plugin_description_wrong_type | description debe ser una cadena de texto. |
plugin_description_empty | description no debe estar vacío. |
plugin_description_too_long | description debe tener 1024 caracteres o menos. |
plugin_description_character_unsupported | description debe usar 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. |
plugin_author_wrong_type | author debe ser un objeto. |
plugin_author_name_wrong_type | author.name debe ser una cadena de texto. |
plugin_author_name_empty | author.name no debe estar vacío. |
plugin_author_name_too_long | author.name debe tener 120 caracteres o menos. |
plugin_author_name_character_unsupported | author.name debe usar texto admitido. |
plugin_author_email_wrong_type | author.email debe ser una cadena de texto si se proporciona. |
plugin_author_email_empty | author.email no debe estar vacío si se proporciona. |
plugin_author_email_too_long | author.email debe tener 320 caracteres o menos. |
plugin_author_email_character_unsupported | author.email debe usar texto admitido. |
plugin_author_url_wrong_type | author.url debe ser una cadena de texto si se proporciona. |
plugin_author_url_empty | author.url no debe estar vacío si se proporciona. |
plugin_author_url_not_https | author.url debe ser una URL HTTPS. |
plugin_author_url_has_credentials | author.url no debe contener credenciales. |
plugin_author_url_too_long | author.url debe tener 2048 caracteres o menos. |
plugin_author_url_character_unsupported | author.url debe usar texto admitido. |
Errores de la ficha y la interfaz
El objeto interface del archivo de manifiesto del complemento define la ficha pública que se muestra a
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 para las cargas de archivos ZIP de complementos que solo incluyen habilidades. Son obligatorias para los envíos de MCP remoto. Su límite de longitud es de 2048 caracteres para la validación del paquete y de 1024 caracteres 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 de texto. |
plugin_display_name_empty | interface.displayName es obligatorio y no debe estar vacío. |
plugin_display_name_too_long | interface.displayName debe tener 80 caracteres o menos para la validación del paquete y 30 caracteres o menos para el envío final al directorio. |
plugin_display_name_character_unsupported | interface.displayName debe usar texto admitido. |
plugin_short_description_missing | interface.shortDescription es obligatorio, debe caber en una sola línea y debe tener 240 caracteres o menos para la validación del paquete y 30 caracteres o menos para el envío final al directorio. |
plugin_short_description_wrong_type | interface.shortDescription debe ser una cadena de texto. |
plugin_short_description_empty | interface.shortDescription no debe estar vacío. |
plugin_short_description_too_long | interface.shortDescription debe tener 240 caracteres o menos para la validación del paquete y 30 caracteres o menos para el envío final al directorio. |
plugin_short_description_character_unsupported | interface.shortDescription debe usar texto admitido. |
plugin_long_description_wrong_type | interface.longDescription debe ser una cadena de texto. |
plugin_long_description_empty | interface.longDescription es obligatorio y no debe estar vacío. |
plugin_long_description_too_long | interface.longDescription debe tener 4000 caracteres o menos. |
plugin_long_description_character_unsupported | interface.longDescription debe usar texto admitido. Se permiten saltos de línea. |
plugin_developer_name_wrong_type | interface.developerName debe ser una cadena de texto. |
plugin_developer_name_empty | interface.developerName es obligatorio y no debe estar vacío. |
plugin_developer_name_too_long | interface.developerName debe tener 120 caracteres o menos para la validación del paquete y 80 caracteres o menos para el envío final al directorio. |
plugin_developer_name_character_unsupported | interface.developerName debe usar texto admitido. |
plugin_category_wrong_type | interface.category debe ser una cadena de texto. |
plugin_category_empty | interface.category no debe estar vacío si se proporciona; 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 o Other. |
plugin_category_character_unsupported | interface.category debe usar texto admitido. |
plugin_capabilities_wrong_type | interface.capabilities debe ser una lista de cadenas de texto. |
plugin_capabilities_too_many | interface.capabilities debe contener 20 elementos o menos. |
plugin_capability_wrong_type | Cada elemento de interface.capabilities debe ser una cadena de texto. |
plugin_capability_empty | Cada elemento de interface.capabilities que se proporcione debe tener un valor no vacío. |
plugin_capability_too_long | Cada elemento de interface.capabilities debe tener 120 caracteres o menos. |
plugin_capability_character_unsupported | Cada elemento de interface.capabilities debe usar texto admitido. |
plugin_website_url_wrong_type | interface.websiteURL debe ser una cadena de texto si se proporciona. |
plugin_website_url_empty | interface.websiteURL no debe estar vacío si se proporciona. |
plugin_website_url_format | interface.websiteURL debe ser una URL HTTPS. |
plugin_website_url_too_long | interface.websiteURL debe cumplir los límites de longitud de las URL de la ficha. |
plugin_privacy_policy_url_wrong_type | interface.privacyPolicyURL debe ser una cadena de texto si se proporciona. |
plugin_privacy_policy_url_empty | interface.privacyPolicyURL no debe estar vacío si se proporciona. |
plugin_privacy_policy_url_format | interface.privacyPolicyURL debe ser una URL HTTPS. |
plugin_privacy_policy_url_too_long | interface.privacyPolicyURL debe cumplir los límites de longitud de las URL de la ficha. |
plugin_terms_of_service_url_wrong_type | interface.termsOfServiceURL debe ser una cadena de texto si se proporciona. |
plugin_terms_of_service_url_empty | interface.termsOfServiceURL no debe estar vacío si se proporciona. |
plugin_terms_of_service_url_format | interface.termsOfServiceURL debe ser una URL HTTPS. |
plugin_terms_of_service_url_too_long | interface.termsOfServiceURL debe cumplir los límites de longitud de las URL de la ficha. |
plugin_support_url_wrong_type | interface.supportURL debe ser una cadena de texto si se proporciona. |
plugin_support_url_empty | interface.supportURL no debe estar vacío si se proporciona. |
plugin_support_url_format | interface.supportURL debe ser una URL HTTPS. |
plugin_support_url_too_long | interface.supportURL debe cumplir los límites de longitud de las URL de la ficha. |
plugin_homepage_wrong_type | homepage debe ser una cadena de texto si se proporciona. |
plugin_homepage_empty | homepage no debe estar vacío si se proporciona. |
plugin_homepage_format | homepage debe ser una URL HTTPS. |
plugin_homepage_too_long | homepage debe tener 2048 caracteres o menos. |
plugin_brand_color_wrong_type | interface.brandColor debe ser una cadena de texto si se proporciona. |
plugin_brand_color_empty | interface.brandColor no debe estar vacío si se proporciona. |
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 de texto si se proporciona. |
plugin_brand_color_dark_empty | interface.brandColorDark no debe estar vacío si se proporciona. |
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 de texto o una lista de cadenas de texto. |
plugin_default_prompt_too_many | interface.defaultPrompt debe contener como máximo tres prompts. |
plugin_default_prompt_entry_wrong_type | Cada entrada de interface.defaultPrompt debe ser una cadena de texto. |
plugin_default_prompt_empty | Ninguna entrada de interface.defaultPrompt debe estar vacía si se proporciona. |
plugin_default_prompt_too_long | Cada entrada de interface.defaultPrompt debe tener 512 caracteres o menos para la validación del paquete y 128 caracteres o menos para el envío final al directorio. |
plugin_default_prompt_character_unsupported | Cada entrada de interface.defaultPrompt debe usar texto compatible y ocupar una sola línea. |
Errores de contenido del complemento
| Nombre | Requisito |
|---|---|
plugin_skills_path_wrong_type | skills debe ser una cadena de texto con la ruta al directorio skills/ ubicado en la raíz. |
plugin_skills_path_empty | Si se proporciona, skills debe ser una ruta no vacía al directorio skills/ ubicado en la raíz. |
plugin_skills_path_unsupported | skills debe resolverse al directorio skills/ ubicado en la raíz. |
plugin_skills_directory_missing | Si se declara un directorio skills/ en la raíz, este 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 de texto con la ruta al archivo .app.json ubicado en la raíz. |
plugin_apps_path_empty | Si se proporciona, apps debe ser una ruta no vacía al archivo .app.json ubicado en la raíz. |
plugin_apps_path_unsupported | apps debe resolverse al archivo .app.json ubicado en la raíz. |
plugin_apps_file_missing | Si se declara un archivo .app.json en la raíz, este 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 de texto con la ruta al archivo .mcp.json ubicado en la raíz. |
plugin_mcp_path_empty | mcpServers debe ser una ruta no vacía. Establece su valor en ./.mcp.json o elimina el campo. |
plugin_mcp_path_unsupported | mcpServers debe resolverse al archivo .mcp.json ubicado en la raíz. |
plugin_mcp_file_missing | mcpServers declara el archivo .mcp.json en la raíz, pero ese archivo no existe. |
plugin_mcp_path_not_file | .mcp.json, ubicado en la raíz, debe ser un archivo regular. |
plugin_runtime_surface_missing | Un ZIP que solo incluya habilidades debe contener al menos una habilidad válida. Los paquetes locales y de espacios de trabajo también pueden hacer referencia a un servidor MCP que cumpla los requisitos. |
Errores del archivo de manifiesto MCP
Estos errores se aplican al archivo de compatibilidad .mcp.json. Para los paquetes portables,
el proceso de ingesta genera 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 anteriores también pueden hacer referencia a
estos archivos generados. Corrige la configuración portable de origen; no cambies el nombre de
mcp.json a .mcp.json solo porque un diagnóstico de compatibilidad lo mencione.
| Nombre | Requisito |
|---|---|
mcp_manifest_unreadable | .mcp.json debe ser texto UTF-8 que se pueda leer. |
mcp_manifest_json_malformed | .mcp.json debe contener JSON válido; los errores de sintaxis se informan con un 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 habilidades
| Nombre | Requisito |
|---|---|
skill_manifest_missing | La habilidad debe contener un archivo SKILL.md. |
skill_bundle_too_large | Cada paquete comprimido de una habilidad debe respetar el límite en MiB indicado en el error. |
skill_directory_hidden | Los nombres de los directorios de habilidades no deben comenzar con .. |
skill_manifest_nested | Cada directorio de habilidad debe ser un subdirectorio directo de skills/. |
skill_manifest_not_regular_file | SKILL.md debe ser un archivo regular. |
skill_manifest_unreadable | SKILL.md debe poder leerse. |
skill_manifest_invalid_utf8 | SKILL.md debe contener texto UTF-8 válido. |
skill_frontmatter_missing | SKILL.md debe comenzar con un encabezado de metadatos YAML delimitado por líneas ---. |
skill_frontmatter_unclosed | El encabezado de metadatos YAML de SKILL.md debe terminar con ---. |
skill_frontmatter_yaml_malformed | El encabezado de metadatos de SKILL.md debe contener YAML válido. |
skill_frontmatter_wrong_type | El encabezado de metadatos de SKILL.md debe contener un mapa YAML. |
skill_name_missing | name es obligatorio y no debe estar vacío. |
skill_name_wrong_type | name debe ser una cadena de texto. |
skill_name_empty | name no debe estar vacío. |
skill_name_character_unsupported | El campo name del encabezado de metadatos de la habilidad debe usar texto compatible. |
skill_description_missing | description es obligatorio y no debe estar vacío. |
skill_description_wrong_type | description debe ser una cadena de texto. |
skill_description_empty | description no debe estar vacío. |
skill_description_too_long | description debe tener 1024 caracteres o menos. |
skill_description_character_unsupported | El campo description del encabezado de metadatos de la habilidad debe usar texto compatible. |
skill_body_empty | Las instrucciones de la habilidad no deben estar vacías. |
skill_identity_too_long | El nombre combinado del complemento y la habilidad (plugin-name:skill-name) debe tener 64 caracteres o menos. |
skill_identity_duplicate | El valor de name de cada habilidad debe ser único dentro del complemento. |
Errores en los metadatos de agente de las habilidades
Una habilidad incluida en el paquete puede definir su propio interface en
skills/<skill>/agents/openai.yaml. Esto controla cómo se muestra la habilidad a
los usuarios y es independiente del campo interface del 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 poder leerse. |
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 cuando 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 debe estar vacío. |
skill_agent_display_name_wrong_type | interface.display_name debe ser una cadena de texto. |
skill_agent_display_name_empty | interface.display_name no debe estar vacío. |
skill_agent_short_description_missing | interface.short_description es obligatorio y no debe estar vacío. |
skill_agent_short_description_wrong_type | interface.short_description debe ser una cadena de texto. |
skill_agent_short_description_empty | interface.short_description no debe estar vacío. |
skill_agent_icon_small_wrong_type | Si se proporciona interface.icon_small, debe ser una ruta relativa de archivo no vacía. |
skill_agent_icon_small_empty | Si se proporciona interface.icon_small, debe ser una ruta relativa de archivo no vacía, como assets/icon.png. |
skill_agent_icon_large_wrong_type | Si se proporciona interface.icon_large, debe ser una ruta relativa de archivo no vacía. |
skill_agent_icon_large_empty | Si se proporciona interface.icon_large, debe ser una ruta relativa de archivo no vacía, como assets/icon.png. |
skill_agent_brand_color_wrong_type | Si se proporciona interface.brand_color, debe ser una cadena de texto. |
skill_agent_brand_color_empty | Si se proporciona interface.brand_color, debe ser un valor no vacío de 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 | Si se proporciona interface.default_prompt, debe ser una cadena de texto. |
skill_agent_default_prompt_empty | Si se proporciona interface.default_prompt, no debe estar vacío. |
skill_agent_policy_wrong_type | Si se proporciona policy, debe ser un mapa YAML. |
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 en las rutas de recursos
| Nombre | Requisito |
|---|---|
declared_asset_path_wrong_type | El campo de recurso indicado debe ser una cadena de texto con una ruta de archivo. |
declared_asset_path_empty | El campo de recurso indicado no debe estar vacío. |
declared_asset_path_has_outer_whitespace | El campo de recurso indicado no debe comenzar ni terminar con espacios en blanco. |
declared_asset_path_has_control_character | El campo de recurso indicado no debe contener los caracteres U+0000–U+001F ni U+007F. |
branding_asset_path_missing_root_prefix | El campo de recurso indicado debe comenzar con ./. |
declared_asset_path_unsafe | El campo de recurso indicado debe ser una ruta relativa dentro del complemento y no debe contener una ruta absoluta, un prefijo de unidad ni un segmento .. de acceso al directorio superior. |
declared_asset_path_outside_package | El campo de recurso indicado debe hacer referencia a un archivo dentro del complemento. |
declared_asset_file_missing | El campo de recurso indicado hace referencia a un archivo que no existe. |
declared_asset_not_regular_file | El campo de recurso indicado debe hacer referencia a un archivo, no a un directorio ni a un archivo especial. |
Errores de imágenes
Las imágenes de marca del directorio deben usar un tipo de archivo compatible y cumplir los límites de tamaño y dimensiones que se indican a continuación. Estas reglas se aplican a los recursos de marca incluidos en el paquete; las capturas de pantalla de los prompts iniciales están sujetas a los límites específicos del portal indicados anteriormente.
| 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 poder leerse. |
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 de imagen debe coincidir con el formato de imagen detectado. |
raster_image_not_square | La imagen debe ser cuadrada. |
raster_image_dimensions_too_small | Las dimensiones de la imagen deben ser de 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 codificado en UTF-8. |
svg_root_element_invalid | El elemento raíz del SVG debe ser <svg>. |
svg_dimensions_missing | El SVG debe definir un valor numérico para viewBox o valores numéricos para width y height. |
svg_dimensions_not_numeric | Las dimensiones del SVG deben ser numéricas y no incluir unidades ni porcentajes. |
svg_dimensions_not_positive | El ancho y la altura del SVG deben ser números finitos positivos. |
svg_dimensions_not_square | El ancho y la altura del SVG deben ser iguales. |
svg_dimensions_too_small | Las dimensiones del SVG deben ser de al menos 48×48 píxeles. |
Errores de referencias a servidores MCP
Las comprobaciones comunes de paquetes validan .app.json cuando un complemento hace referencia a
servidores MCP registrados. El portal de envío no publica referencias a
integraciones existentes. Al cargar un paquete mediante Solo habilidades , se elimina .app.json. Usa
Con MCP para enviar el servidor MCP directamente.
En los paquetes locales o del espacio de trabajo, el objeto apps de 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 ser texto UTF-8 que pueda leerse. |
app_manifest_json_malformed | .app.json contiene JSON mal formado 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 | id es obligatorio en cada entrada de servidor. |
app_id_wrong_type | id de cada entrada de servidor debe ser una cadena. |
app_id_format | id de cada entrada de servidor debe comenzar con asdk_app_, connector_ o templated_apps_, seguido de una letra o un dígito y, después, solo letras, dígitos, _ o -. |
app_entry_optional_wrong_type | El valor de optional de cada entrada de servidor debe ser true o false cuando se proporcione. |
app_entry_required_wrong_type | El valor de required de cada entrada de servidor debe ser true o false cuando se proporcione. |
app_not_eligible | Un paquete local o del espacio de trabajo debe hacer referencia a un servidor MCP que cumpla los requisitos y esté disponible. Para los envíos al directorio, se debe usar Con MCP y enviar el servidor MCP directamente. |
Advertencias del paquete
Estas advertencias identifican contenido del paquete que la validación ignora o normaliza. No bloquean el envío. Revísalas para confirmar que el complemento enviado contenga los archivos y la configuración esperados.
| Nombre | Requisito |
|---|---|
duplicate_app_reference | Cada ID de servidor en .app.json debe tener una sola referencia; las referencias duplicadas se tratan como un único servidor. |
undeclared_app_manifest_ignored | Un archivo .app.json en la raíz se importa solo cuando el campo apps del archivo de manifiesto del complemento está establecido en ./.app.json. |
undeclared_mcp_manifest_ignored | Un archivo .mcp.json en la raíz se importa solo cuando el campo mcpServers del archivo de manifiesto del complemento está establecido en ./.mcp.json. |
skill_file_ignored | Los archivos ubicados 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 ubicados directamente en skills/ no se importan como habilidades; cada habilidad debe ser un directorio real que contenga SKILL.md. |
skill_frontmatter_adjusted | Los campos name y description de la habilidad se normalizan durante la importación: se eliminan los espacios en blanco al principio y al final, y se reducen las secuencias internas de espacios en blanco a un solo espacio. |
skill_metadata_ignored | La configuración de la interfaz de la habilidad debe usar el mapeo interface de agents/openai.yaml; metadata en SKILL.md no configura la interfaz. |
Siguientes pasos
Después de resolver todos los errores de validación, vuelve a Enviar complementos para completar el envío.