Guía de Validación

Asegura que tu squad cumpla los estándares de calidad antes de publicar en el marketplace.

¿Por qué validar?

Los squads ejecutan código en el entorno del usuario. La validación garantiza calidad, seguridad e integridad estructural antes de que tu squad llegue a otros desarrolladores.

Qué se verifica

El validador analiza tu squad en 6 categorías ponderadas:

Categoría	Peso	Qué valida
Manifiesto (squad.yaml)	25%	name, version, description, aiox.minVersion, components
Estructura	15%	Directorios, archivos esperados, extensiones
Agentes	20%	Campos requeridos, archetype, persona_profile, whenToUse
Tareas	15%	Contratos Entrada/Salida, responsavel, atomic_layer
Workflows	10%	agent_sequence, transitions, success_indicators
Referencias Cruzadas	15%	Los agentes referenciados existen, sin dependencias circulares

Sistema de Puntuación

Cada squad recibe una puntuación de 0 a 100 basada en las categorías ponderadas anteriores.

SAFEPuntuación >= 80, sin errores — listo para publicar

WARNINGTiene advertencias pero sin errores bloqueantes

CRITICALTiene errores o puntuación por debajo del umbral — debe corregir antes de publicar

Cómo Validar

a) CLI (recomendado)

La forma más rápida de validar tu squad localmente antes de publicar:

squads validate ./my-squad           # Validación completa

squads validate ./my-squad --json    # Salida JSON

squads publish ./my-squad --dry-run  # Simular publicación

validationDocs.aiosMethodTitle

validationDocs.aiosMethodDescription

/SQUADS:nsc:squad-validator

*validate-squad my-squad

*extend-squad my-squad --add task --name missing-task

c) Claude Code (sin Squad)

Indica a Claude Code que valide tu squad usando el CLI:

npx squads validate ./squads/my-squad

d) Web (página de envío)

La página de envío ejecuta la validación automáticamente al pegar la URL de GitHub. Corrige los problemas antes de enviar.

Errores Comunes y Correcciones

Error	Causa	Corrección
description interpretado como objeto	YAML multi-línea (\| o >)	Usar cadena inline entre comillas
Agente sin campos requeridos	Falta whenToUse, archetype, etc.	Agregar campos al frontmatter
Task responsavel no encontrado	Nombre del agente no coincide	Usar exactamente el valor de agent.name
Agente del workflow ausente en la secuencia	ID inválido en agent_sequence	Usar agent.id (kebab-case)
Incompatibilidad de componentes	Archivos listados en squad.yaml no existen	Sincronizar components con archivos reales

Checklist de Pre-Publicación

squad.yaml válido con name, version, description

Sin archivos .env o credenciales hardcodeadas

Sin directorios node_modules/ o .git/

README.md existe con sección de instalación

Todos los agentes tienen campos requeridos (archetype, whenToUse, persona_profile)

Todas las tareas tienen contratos Entrada/Salida

Referencias cruzadas válidas (agentes existen, sin deps circulares)

Quality Gates Squad

Para usuarios de Squad Core, el framework proporciona quality gates integrados durante la generación de squads:

▸Fase 6: Quality Gate de Generación — 22 verificaciones bloqueantes en estructura, campos y referencias cruzadas.
▸Fase 9: Checklist de Pre-Publicación — 16 verificaciones bloqueantes de preparación para el marketplace.

Usa los comandos *validate-squad y *extend-squad para validación y corrección iterativa:

*validate-squad my-squad
*extend-squad my-squad --add agent --name new-agent

Para más detalles, consulta la Referencia CLI