v3.10.0 — conformidad con Agent Plugins 1.0.0 (formato portátil AAIF)

[novanoticia]

Qué cambia

Adapta el empaquetado al estándar Agent Plugins 1.0.0 (Agentic AI Foundation, publicado el 2026-08-06), que define el formato portátil para skills y servidores MCP. Es un cambio puramente estructural: no toca el motor de scoring, ni S0–S5, ni un solo veredicto.

Por el camino arregla dos fallos reales que no se veían porque Claude Code es permisivo donde la spec es estricta: el SKILL.md no validaba contra Agent Skills, y con la spec en la mano un cliente conformante se saltaba el skill entero (§7.1), dejando el plugin instalado y vacío en cualquier cliente que no fuera Claude.

Los tres arreglos

• Frontmatter del SKILL.md conforme. El conjunto es cerrado (name, description, license, compatibility, metadata, allowed-tools) y había dos infracciones simultáneas: una clave version al nivel superior, y una description de 1475 caracteres contra un máximo de 1024. Cualquiera de las dos, por separado, basta para que el skill se descarte. Ahora la versión vive en metadata.version y la description mide 943, conservando todas las frases de activación (incluidas «test del triaje» y «muéstrame qué haría sin ejecutarlo»).
• Los requisitos de entorno tienen su sitio. macOS, Mail.app/AppleScript o el MCP de Gmail, y Python 3.9+ estaban solo en prosa dentro de la description. Pasan al campo compatibility (194 de 500 caracteres), que es el que la spec reserva para eso: un cliente incompatible puede saberlo antes de intentar ejecutarlo.
• Manifiesto portable en la raíz del plugin: plugins/email-triage/plugin.json con el $schema canónico. El §5.1 lo exige ahí; sin él, un cliente conformante rechaza el plugin sin llegar a mirar los componentes. .claude-plugin/plugin.json se queda — es el único que Claude Code lee hoy — y el CI mantiene los dos en sincronía.

Para que no vuelva a derivar

• Gate v3.8.2 — hardening de auditoría verificada contra el código #7 de CI: valida el esquema cerrado del manifiesto, el $schema exacto, el name contra §5.5, el author como objeto, el frontmatter con sus presupuestos 1024/500, el mcp.json si algún día existe (incluida la coherencia de versión de spec del §10.1) y que ningún symlink escape de la raíz del plugin (§4.1).
• La versión pasa de 8 a 9 sitios y bump-version.sh los cubre de una pasada. El sed del frontmatter se acota al bloque 1,/^---$/ para no pisar otro version: del cuerpo.
• CLAUDE.md y AGENTS.md documentan los dos manifiestos y las tres reglas fáciles de romper sin darse cuenta.

Comprobado

• Tests OK: 287 tests, OK (skipped=3, expected failures=1)
• Versión coherente: v3.10.0 en los 9 sitios, fijada con ./scripts/bump-version.sh (no a mano)
• He revisado el diff
• Los 7 gates del workflow en verde en local, ejecutando los pasos de tests.yml tal cual, incluido el fuzz de 20 000 iteraciones × 4 entradas
• El gate v3.8.2 — hardening de auditoría verificada contra el código #7 probado contra seis mutaciones deliberadas — version al nivel superior, description > 1024, manifiesto ausente, $schema de otra versión, mcp.json sin $schema, y compatibility > 500: las seis lo rompen, y el árbol sin mutar vuelve a pasar
• El manifiesto valida además contra el JSON Schema oficial de la spec (schemas/1.0.0/plugin.schema.json), no solo contra las comprobaciones propias

Notas

Esto todavía no da compatibilidad efectiva con otros clientes. La documentación de Claude Code no menciona aún Agent Plugins, ni el plugin.json de raíz ni el mcp.json sin punto, así que hoy esos ficheros son inocuos pero inertes: posicionan el plugin para cuando Anthropic adopte el formato. Lo que sí vale ya son los dos defectos del SKILL.md, que existían desde antes de que saliera el estándar y que además mejoran el triggering.

No se publica mcp.json. El §6.2 dice que una ubicación ausente no es error, .mcp.json está vacío, y el MCP de Gmail lo gestiona el cliente en vez de empaquetarlo el plugin. De paso se corrige CLAUDE.md, que lo describía como «proveedor de correo (Gmail MCP)» cuando en realidad estaba vacío.

commands/triage.md no se toca. Los commands no son un componente portable en v1 (la spec solo define skills y MCP, y obliga a los clientes a ignorar el resto), pero moverlo a un directorio de extensión rompería Claude Code, que lee commands/ de forma nativa. /triage seguirá siendo de Claude Code y eso no afecta a la conformidad. La distribución (marketplace.json, install-plugin.sh, fix-cowork-version.sh) también sigue igual: la spec la deja deliberadamente a cada cliente.

Riesgo a vigilar en el futuro: el sed de metadata.version depende de que la clave esté indentada con dos espacios dentro del frontmatter. Si alguien reformatea el bloque, el bump fallará ruidosamente en su propia validación (no en silencio), que es el comportamiento que queremos.

---

Generated by Claude Code