How to Create a Custom Squad with Domain-Specific Agents in AIOX

Create a custom squad by generating a skeleton with the @squad-creator agent, defining agents as markdown files in squads/<name>/agents/, and validating with *validate-squad.

AIOX treats a squad as a self-contained package of agents, tasks, workflows, templates, and optional tooling. According to the SynkraAI/aiox-core source code, building a domain-specific squad—whether for finance, healthcare, or marketing—requires scaffolding a directory structure, authoring agent definitions in markdown, and declaring all components in a central YAML manifest.

Generate the Squad Skeleton

Start by invoking the built-in @squad-creator agent through the AIOX CLI. This agent provides two primary commands for initialization:

• *design-squad – Launches an interactive wizard that suggests components based on your domain requirements.
• *create-squad <name> – Generates the folder structure and a minimal squad.yaml at squads/<your-squad>/.

The scaffolding process copies the official squad-template located at .aiox-core/development/templates/squad-template/squad.yaml to establish the baseline directory layout and configuration files.

Define the Squad Manifest

Every squad requires a squad.yaml manifest that declares the package identity, AIOX version requirements, and component inventory. Place this file at the root of your squad directory (e.g., squads/my-finance-squad/squad.yaml).

The manifest must specify:

• Metadata: name, version, description, author, and license.
• AIOX compatibility: aiox.minVersion (e.g., "2.1.0") and type: squad.
• Components: Lists of paths to agents, tasks, workflows, checklists, templates, and tools.

name: my-finance-squad
version: 0.1.0
description: Squad for finance-domain analytics
author: Your Name <you@example.com>
license: MIT
slashPrefix: finance

aiox:
  minVersion: "2.1.0"
  type: squad

components:
  agents:
    - agents/finance-insight-agent.md
  tasks:
    - tasks/generate-insight.md
  workflows: []
  checklists: []
  templates: []
  tools: []

Source: squad-template

Add Domain-Specific Agents

Agents are the core domain experts of your squad. Each agent is a markdown file stored under squads/<your-squad>/agents/ and must begin with a YAML front-matter block declaring its configuration.

Required front-matter fields:

• name: The agent identifier.
• description: Purpose of the agent.
• slashPrefix: The command prefix for invoking the agent (e.g., finance).

Body content can include natural language prompts, @-commands for tool invocation, and template references.

---
name: finance-insight-agent
description: Generates concise financial insights from CSV data
slashPrefix: finance
---

# Finance Insight Agent

> This agent reads a CSV file, extracts revenue, expenses and profit margin, then formats the result with the **FinanceReport** template.

@tool csv-analyzer
@template FinanceReport

Source: greeter-agent.md example

Create Supporting Tasks (Optional)

Tasks orchestrate agents and tools for specific workflows. Define tasks as markdown files in squads/<your-squad>/tasks/ and invoke them via *run-task <task-name>.

Tasks also use front-matter for metadata and can accept variables through templating syntax:

---
name: generate-insight
description: Run the finance-insight-agent on a given CSV file
---
Please analyze the file `{{inputFile}}` and produce a concise insight.

Validate and Publish Your Squad

Before deploying, run the squad validator to ensure the manifest adheres to the JSON schema and that all referenced component paths exist:

*validate-squad squads/my-finance-squad --strict

When ready for distribution, publish to the public aiox-squads repository:

*publish-squad squads/my-finance-squad
*sync-squad-synkra squads/my-finance-squad --public

Summary

• Use the @squad-creator agent with *create-squad <name> to scaffold the directory structure at squads/<name>/.
• Define the squad manifest in squad.yaml, specifying aiox.minVersion and component paths.
• Author domain-specific agents as markdown files in agents/ with required front-matter (name, description, slashPrefix).
• Add reusable tasks in tasks/ to orchestrate complex workflows.
• Validate with *validate-squad --strict before publishing via *publish-squad.

Frequently Asked Questions

What is the difference between *design-squad and *create-squad?

*design-squad launches an interactive wizard that asks questions about your domain and suggests appropriate components, while *create-squad <name> immediately generates the folder structure and minimal squad.yaml without interactive prompts. Use the design wizard when you need guidance on squad architecture; use create when you know exactly which components you need.

How do I reference external tools inside an agent definition?

Inside the agent's markdown body, prefix tool names with the @tool directive (e.g., @tool csv-analyzer). You can also reference templates using @template TemplateName. These directives tell AIOX which capabilities to load when the agent executes.

What AIOX version is required to run custom squads?

The squad.yaml manifest must declare aiox.minVersion under the aiox key. The official template and examples specify "2.1.0" as the baseline, ensuring compatibility with the squad validation schema and the @squad-creator agent commands.

How do I share my custom squad with other AIOX users?

Run *publish-squad squads/<your-squad> to package your squad, then use *sync-squad-synkra squads/<your-squad> --public to push it to the public aiox-squads repository. This makes your domain-specific agents available for installation by other users via the AIOX CLI.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}