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

> Learn how to create a custom squad with domain-specific agents in AIOX. Follow our step-by-step guide to define and validate your custom squads for enhanced AI solutions.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: how-to-guide
- Published: 2026-03-15

---

**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`](https://github.com/SynkraAI/aiox-core/blob/main/squad.yaml) at `squads/<your-squad>/`.

The scaffolding process copies the official **squad-template** located at [`.aiox-core/development/templates/squad-template/squad.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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.

```yaml
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](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/templates/squad-template/squad.yaml)

## 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.

```markdown
---
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](https://github.com/SynkraAI/aiox-core/blob/main/docs/examples/squads/basic-squad/agents/greeter-agent.md)

## 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:

```markdown
---
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:

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

```

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

```bash
*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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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`](https://github.com/SynkraAI/aiox-core/blob/main/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.