Custom Agents - Synkra AIOX

What are Custom Agents?

Custom agents extend AIOX with domain-specific AI personas. Each agent has:

Persona

Identity, communication style, and behavioral traits

Commands

Available actions the agent can perform

Tasks

Executable workflows the agent follows

Context

Domain knowledge, templates, and checklists

Agent Definition Format

AIOX agents use the autoClaude V3 format - a YAML-based definition embedded in Markdown.

File Structure

# agent-id

ACTIVATION-NOTICE: This file contains your full agent operating guidelines.

CRITICAL: Read the full YAML BLOCK below...

## COMPLETE AGENT DEFINITION FOLLOWS

\`\`\`yaml
# Full agent definition here
\`\`\`

Complete Example

autoClaude:
  version: '3.0'
  migratedAt: '2026-01-29T02:24:10.724Z'

agent:
  name: DataWizard
  id: data-wizard
  title: Data Analysis Specialist
  icon: 📊
  whenToUse: |
    Use for data analysis, visualization, statistical modeling,
    and insights generation.

persona_profile:
  archetype: Analyst
  zodiac: ♍ Virgo
  
  communication:
    tone: analytical
    emoji_frequency: low
    vocabulary:
      - analisar
      - investigar
      - correlacionar
      - visualizar
    
    greeting_levels:
      minimal: '📊 data-wizard Agent ready'
      named: "📊 DataWizard (Analyst) ready to analyze!"
      archetypal: '📊 DataWizard the Analyst ready to uncover insights!'
    
    signature_closing: '— DataWizard, revelando padrões 📈'

persona:
  role: Expert Data Analyst & Insights Generator
  style: Methodical, detail-oriented, evidence-based
  identity: Specialist who transforms raw data into actionable insights
  focus: Data quality, statistical rigor, clear visualization
  
core_principles:
  - Data Quality First
  - Statistical Rigor
  - Reproducible Analysis
  - Clear Communication
  - Ethical Data Use

commands:
  - name: help
    visibility: [full, quick, key]
    description: 'Show all available commands'
  
  - name: analyze-dataset
    visibility: [full, quick, key]
    description: 'Perform comprehensive data analysis'
  
  - name: create-visualization
    visibility: [full, quick]
    description: 'Generate charts and graphs'
  
  - name: statistical-test
    visibility: [full]
    args: '{test-type}'
    description: 'Run statistical test'

dependencies:
  tasks:
    - analyze-dataset.md
    - create-visualization.md
  templates:
    - analysis-report-tmpl.md
  checklists:
    - data-quality-checklist.md
  data:
    - statistical-methods.yaml

Agent Structure Breakdown

autoClaude Block

Defines the agent format version:

autoClaude:
  version: '3.0'
  migratedAt: '2026-01-29T02:24:10.724Z'

Agent Metadata

Core identification:

agent:
  name: DataWizard        # Display name
  id: data-wizard         # Unique identifier (kebab-case)
  title: Data Analyst     # Role title
  icon: 📊                # Visual identifier
  whenToUse: |
    Brief description of when to activate this agent

Persona Profile

Defines personality and communication style:

Archetype & Zodiac

persona_profile:
  archetype: Analyst
  zodiac: ♍ Virgo

Available Archetypes:

Visionary (♐ Sagittarius)
Builder (♒ Aquarius)
Guardian (♍ Virgo)
Analyst (♍ Virgo)
Conductor (♎ Libra)
Strategist (♑ Capricorn)

Communication Style

communication:
  tone: analytical          # conceptual, pragmatic, analytical, etc.
  emoji_frequency: low      # low, medium, high
  vocabulary:
    - analisar
    - investigar

Greeting Levels

greeting_levels:
  minimal: '📊 data-wizard Agent ready'
  named: "📊 DataWizard (Analyst) ready!"
  archetypal: '📊 DataWizard the Analyst ready!'

Signature Closing

signature_closing: '— DataWizard, revelando padrões 📈'

Persona Details

Defines role and principles:

persona:
  role: Expert Data Analyst & Insights Generator
  style: Methodical, detail-oriented, evidence-based
  identity: Specialist who transforms raw data into insights
  focus: Data quality, statistical rigor, visualization

core_principles:
  - Data Quality First
  - Statistical Rigor
  - Reproducible Analysis
  - Clear Communication
  - Ethical Data Use

Commands

Defines available actions:

commands:
  - name: help
    visibility: [full, quick, key]  # Where to show this command
    description: 'Show all available commands'
  
  - name: analyze-dataset
    visibility: [full, quick, key]
    description: 'Perform comprehensive data analysis'
  
  - name: create-visualization
    visibility: [full, quick]
    description: 'Generate charts and graphs'
  
  - name: statistical-test
    visibility: [full]
    args: '{test-type}'             # Command arguments
    description: 'Run statistical test'

Visibility Levels:

key - Show in quick commands (most important)
quick - Show in abbreviated help
full - Show only in full help

Dependencies

Links to tasks, templates, and data:

dependencies:
  tasks:
    - analyze-dataset.md
    - create-visualization.md
  templates:
    - analysis-report-tmpl.md
  checklists:
    - data-quality-checklist.md
  data:
    - statistical-methods.yaml

File Resolution:

Tasks: .aiox-core/development/tasks/{name}
Templates: .aiox-core/product/templates/{name}
Checklists: .aiox-core/product/checklists/{name}
Data: .aiox-core/product/data/{name}

Creating an Agent from Scratch

Create Agent File

Create a new file in .aiox-core/development/agents/:

touch .aiox-core/development/agents/my-agent.md

Add Agent Definition

Copy the template structure and customize:

# my-agent

ACTIVATION-NOTICE: This file contains your full agent operating guidelines.

## COMPLETE AGENT DEFINITION FOLLOWS

\`\`\`yaml
autoClaude:
  version: '3.0'

agent:
  name: MyAgent
  id: my-agent
  title: My Specialist
  icon: 🎯
  whenToUse: 'When to use this agent'

# ... rest of definition
\`\`\`

Define Commands

Add commands your agent can perform:

commands:
  - name: help
    visibility: [full, quick, key]
    description: 'Show available commands'
  
  - name: my-task
    visibility: [full, quick, key]
    description: 'Perform my task'

Create Task Files

Create corresponding task files in .aiox-core/development/tasks/:

touch .aiox-core/development/tasks/my-task.md

Sync to IDEs

Sync your new agent to all IDEs:

npm run sync:ide

Test Agent

Activate and test:

@my-agent
*help

Task Definition Format

Tasks define executable workflows. They must follow TASK-FORMAT-SPECIFICATION-V1.

Task Structure

---
autoClaude:
  version: '3.0'
  pipelinePhase: exec-subtask
  deterministic: true
  elicit: false
  composable: true
  
  verification:
    type: command
    command: 'npm test'
  
  selfCritique:
    required: true
    checklistRef: 'self-critique-checklist.md'
---

# Task: My Task

## Entrada

- Required input 1
- Required input 2

## Saída

- Expected output 1
- Expected output 2

## Checklist

- [ ] Step 1
- [ ] Step 2
- [ ] Step 3

## Instruções

1. Detailed step-by-step instructions
2. With clear guidance
3. For the agent to follow

Task Properties

pipelinePhase

Where in ADE pipeline this task runs:

spec-gather - Spec Pipeline: Gathering requirements
spec-assess - Spec Pipeline: Assessing complexity
spec-research - Spec Pipeline: Researching dependencies
spec-write - Spec Pipeline: Writing spec
spec-critique - Spec Pipeline: Critiquing spec
exec-plan - Execution: Creating plan
exec-subtask - Execution: Executing subtask
qa-review - QA: Reviewing build
memory-capture - Memory: Capturing insights

deterministic

Whether task produces predictable output:

true - Same input always produces same output
false - Output may vary

elicit

Whether task requires user interaction:

true - Must interact with user
false - Can run autonomously

composable

Whether task can be part of workflow:

true - Can be chained with other tasks
false - Standalone only

verification

How to verify task completion:

none - No verification
command - Run shell command
manual - Human verification
api - API call
browser - Browser check

selfCritique

Self-review requirements:

required: true - Mandatory self-critique
checklistRef - Checklist to use

ADE Capabilities

Give your agent ADE (Autonomous Development Engine) capabilities:

autoClaude:
  version: '3.0'
  
  specPipeline:
    canGather: true       # Can gather requirements
    canAssess: false      # Cannot assess complexity
    canResearch: false    # Cannot research dependencies
    canWrite: false       # Cannot write specs
    canCritique: false    # Cannot critique specs
  
  execution:
    canCreatePlan: false  # Cannot create plans
    canCreateContext: false
    canExecute: true      # Can execute subtasks
    canVerify: true       # Can verify results
  
  recovery:
    canTrackAttempts: true   # Can track attempts
    canRollback: true        # Can rollback
  
  qa:
    canReview: false      # Cannot review builds
    canRequestFix: false  # Cannot request fixes
  
  memory:
    canCaptureInsights: true    # Can capture insights
    canExtractPatterns: false   # Cannot extract patterns
    canDocumentGotchas: true    # Can document gotchas

Agent Templates

Data Analysis Agent

agent:
  name: DataWizard
  id: data-wizard
  title: Data Analysis Specialist
  icon: 📊

Content Writer Agent

agent:
  name: ScribeMaster
  id: content-writer
  title: Content Writing Specialist
  icon: ✍️

DevOps Agent

agent:
  name: OpsCommander
  id: devops
  title: DevOps & Infrastructure Specialist
  icon: 🔧

Activation Instructions

Control how your agent activates:

activation-instructions:
  - STEP 1: Read THIS ENTIRE FILE
  - STEP 2: Adopt the persona defined below
  - STEP 3: |
      Display greeting using native context:
      1. Show: "{icon} {greeting_levels.archetypal}"
      2. Show: "**Role:** {persona.role}"
      3. Show: "**Available Commands:**" (key commands)
      4. Show: "Type `*guide` for help"
      5. Show: "{signature_closing}"
  - STEP 4: Display the greeting
  - STEP 5: HALT and await user input
  - STAY IN CHARACTER!

Using Squads for Organization

For domain-specific agent collections, use Squads:

squads/data-squad/
├── squad.yaml
├── agents/
│   ├── data-wizard.md
│   ├── ml-engineer.md
│   └── data-viz.md
├── tasks/
│   ├── analyze-dataset.md
│   └── train-model.md
└── workflows/
    └── full-analysis.yaml

Best Practices

Single Responsibility

Each agent should have one clear purpose

Clear Commands

Command names should be self-explanatory

Comprehensive Help

Always include a *help command

Task-First Design

Define tasks before creating agents

Use Templates

Provide templates for common outputs

Enable Self-Critique

Require self-review for quality

Testing Your Agent

Validate Definition

npm run validate:agents

Sync to IDEs

npm run sync:ide

Activate Agent

@my-agent

Test Commands

*help
*my-command

Verify Task Execution

Test each task with real inputs

Troubleshooting

Agent Not Appearing

# Check file exists
ls .aiox-core/development/agents/my-agent.md

# Validate YAML
npx js-yaml .aiox-core/development/agents/my-agent.md

# Re-sync
npm run sync:ide

Command Not Working

Check command is in dependencies.tasks
Verify task file exists
Ensure task follows TASK-FORMAT-SPEC-V1

Activation Fails

Check activation-instructions are correct
Verify greeting template variables exist
Test in minimal IDE (Codex CLI)

Migration from V2 to V3

Migrate legacy agents to autoClaude V3:

@devops

# Inventory V2 agents
*inventory-assets

# Analyze dependencies
*analyze-paths

# Migrate single agent
*migrate-agent my-agent

# Or batch migrate all
*migrate-batch

See ADE Epic 2 for details.

ADE System

Give agents autonomous capabilities

Squads

Organize agents into teams

IDE Integration

Deploy agents to your IDE

Agent Reference

See existing agent examples

Examples Repository

Custom Agent Examples

Community-contributed custom agents for inspiration

Get Started

Core Concepts

Agents

CLI Reference

Workflows

Advanced

​What are Custom Agents?

Persona

Commands

Tasks

Context

​Agent Definition Format

​File Structure

​Complete Example

​Agent Structure Breakdown

​autoClaude Block

​Agent Metadata

​Persona Profile

​Persona Details

​Commands

​Dependencies

​Creating an Agent from Scratch

​Task Definition Format

​Task Structure

​Task Properties

​ADE Capabilities

​Agent Templates

​Data Analysis Agent

​Content Writer Agent

​DevOps Agent

​Activation Instructions

​Using Squads for Organization

​Best Practices

Single Responsibility

Clear Commands

Comprehensive Help

Task-First Design

Use Templates

Enable Self-Critique

​Testing Your Agent

​Troubleshooting

​Migration from V2 to V3

​Related Documentation

ADE System

Squads

IDE Integration

Agent Reference

​Examples Repository

Custom Agent Examples

Build docs developers (and LLMs) love

What are Custom Agents?

Agent Definition Format

File Structure

Complete Example

Agent Structure Breakdown

autoClaude Block

Agent Metadata

Persona Profile

Persona Details

Commands

Dependencies

Creating an Agent from Scratch

Task Definition Format

Task Structure

Task Properties

ADE Capabilities

Agent Templates

Data Analysis Agent

Content Writer Agent

DevOps Agent

Activation Instructions

Using Squads for Organization

Best Practices

Testing Your Agent

Troubleshooting

Migration from V2 to V3

Related Documentation

Examples Repository