Validation Guide

Ensure your squad meets quality standards before publishing to the marketplace.

Why Validate?

Squads execute code in the user's environment. Validation ensures quality, security, and structural integrity before your squad reaches other developers.

What Gets Checked

The validator analyzes your squad across 6 weighted categories:

Category	Weight	What it validates
Manifest (squad.yaml)	25%	name, version, description, components
Structure	15%	Directories, expected files, file extensions
Agents	20%	Required fields, archetype, persona_profile, whenToUse
Tasks	15%	Entrada/Saída contracts, responsavel, atomic_layer
Workflows	10%	agent_sequence, transitions, success_indicators
Cross-References	15%	Agents referenced exist, no circular dependencies

Score System

Each squad receives a score from 0 to 100 based on the weighted categories above.

SAFEScore >= 80, no errors — ready to publish

WARNINGHas warnings but no blocking errors

CRITICALHas errors or score below threshold — must fix before publishing

How to Validate

a) CLI (recommended)

The fastest way to validate your squad locally before publishing:

squads validate ./my-squad           # Full validation

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

squads publish ./my-squad --dry-run  # Simulate publish

validationDocs.aiosMethodTitle

validationDocs.aiosMethodDescription

/SQUADS:nsc:squad-validator

*validate-squad my-squad

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

b) Claude Code Validator

Instruct Claude Code to validate your squad using the CLI:

npx squads validate ./squads/my-squad

d) Web (submit page)

The submit page runs validation automatically when you paste a GitHub URL. Fix any issues before submitting.

Common Errors & Fixes

Error	Cause	Fix
description parsed as object	Multi-line YAML (\| or >)	Use inline string in quotes
Agent missing required fields	Missing whenToUse, archetype, etc.	Add fields to the frontmatter
Task responsavel not found	Agent name mismatch	Use exact agent.name value
Workflow agent not in sequence	Invalid ID in agent_sequence	Use agent.id (kebab-case)
Components mismatch	Files listed in squad.yaml don't exist	Sync components with actual files

Pre-Publish Checklist

squad.yaml valid with name, version, description

No .env files or hardcoded credentials

No node_modules/ or .git/ directories

README.md exists with installation section

All agents have required fields (archetype, whenToUse, persona_profile)

All tasks have Entrada/Saída contracts

Cross-references are valid (agents exist, no circular deps)

validationDocs.qualityGatesTitle

validationDocs.qualityGatesDescription

▸Phase 6: Squad Generation Quality Gate — 22 blocking checks on structure, fields, and cross-references.
▸Phase 9: Pre-Publish Checklist — 16 blocking checks on readiness for marketplace publication.

Use *validate-squad and *extend-squad commands for iterative validation and fixing:

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

For more details, see the CLI Reference