Contributing Squads Guide

EN | PT | ES

How to contribute squads to the AIOX ecosystem.

Overview

There are two ways to share your squad with the community:

aiox-squads Repository - Free, open-source squads on GitHub
Synkra Marketplace - Premium squads via Synkra API

Quality Standards

All contributed squads must meet these standards:

Required

| Requirement | Description | |-------------|-------------| | Valid manifest | squad.yaml passes JSON Schema validation | | Documentation | README.md with usage instructions | | License | Open source license (MIT, Apache 2.0, etc.) | | AIOX compatibility | aiox.minVersion: "2.1.0" or higher | | Task-first architecture | Tasks as primary entry points |

Naming Conventions

Squad Names

Use kebab-case: my-awesome-squad
Be descriptive: etl-data-pipeline not data1
Avoid generic names: helper-squad is too vague
No version numbers in name: my-squad not my-squad-v2

Prefix (slashPrefix)

The slashPrefix in squad.yaml determines command prefixes:

slashPrefix: etl  # Commands become *etl-extract, *etl-transform

Choose a unique, short prefix (2-5 characters).

Manifest Requirements

Required Fields

# These fields are REQUIRED
name: my-squad
version: 1.0.0              # Semantic versioning
description: Clear description of what this squad does

aiox:
  minVersion: "2.1.0"
  type: squad

components:
  agents: []                # At least one agent OR task
  tasks: []

Recommended Fields

# These fields are RECOMMENDED
author: Your Name <email@example.com>
license: MIT
slashPrefix: my

tags:
  - relevant
  - keywords

dependencies:
  node: []
  python: []
  squads: []

Documentation Requirements

README.md Structure

# Squad Name

Brief description (1-2 sentences).

## Installation

How to install/add this squad.

## Usage

Basic usage examples.

## Commands

| Command | Description |
|---------|-------------|
| *cmd1 | What it does |
| *cmd2 | What it does |

## Configuration

Any configuration options.

## Examples

Detailed usage examples.

## Troubleshooting

Common issues and solutions.

## License

License information.

Publishing to aiox-squads

Prerequisites

GitHub account
Squad validated: *validate-squad --strict
Unique squad name (check existing squads)

Steps

# 1. Validate your squad
@squad-creator
*validate-squad my-squad --strict

# 2. Publish (creates PR)
*publish-squad ./squads/my-squad

This will:

Fork SynkraAI/aiox-squads (if needed)
Create branch with your squad
Open PR for review

Review Process

Automated checks - Schema validation, structure check
Maintainer review - Code review, quality check
Merge - Squad added to registry

Timeline: Usually 2-5 business days.

Publishing to Synkra Marketplace

Prerequisites

Synkra account
API token configured
Squad validated

Steps

# 1. Configure token
export SYNKRA_API_TOKEN="your-token"

# 2. Sync to marketplace
@squad-creator
*sync-squad-synkra ./squads/my-squad --public

Visibility Options

| Flag | Effect | |------|--------| | --private | Only visible to your workspace | | --public | Visible to everyone |

Updating Published Squads

Version Bumping

Follow semantic versioning:

MAJOR (1.0.0 → 2.0.0): Breaking changes
MINOR (1.0.0 → 1.1.0): New features, backward compatible
PATCH (1.0.0 → 1.0.1): Bug fixes

Update Process

# 1. Update version in squad.yaml
# 2. Update CHANGELOG.md
# 3. Validate
*validate-squad my-squad --strict

# 4. Re-publish
*publish-squad ./squads/my-squad
# or
*sync-squad-synkra ./squads/my-squad

Code of Conduct

Do

Provide clear, accurate documentation
Test your squad before publishing
Respond to issues and feedback
Keep dependencies minimal
Follow AIOX conventions

Don't

Include malicious code
Store credentials in code
Copy others' work without attribution
Use offensive names or content
Spam the registry with test squads

Getting Help

Questions: GitHub Discussions
Issues: Issue Tracker
Guidelines: This document

Related Resources

Version: 1.0.0 | Updated: 2025-12-26 | Story: SQS-8