> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Agents

> Create your own AI agents with specialized capabilities for any domain

## What are Custom Agents?

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

<CardGroup cols={2}>
  <Card title="Persona" icon="user">
    Identity, communication style, and behavioral traits
  </Card>

  <Card title="Commands" icon="terminal">
    Available actions the agent can perform
  </Card>

  <Card title="Tasks" icon="list-check">
    Executable workflows the agent follows
  </Card>

  <Card title="Context" icon="book">
    Domain knowledge, templates, and checklists
  </Card>
</CardGroup>

## Agent Definition Format

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

### File Structure

```markdown theme={null}
# 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

<CodeGroup>
  ```yaml Agent Definition theme={null}
  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
  ```
</CodeGroup>

## Agent Structure Breakdown

### autoClaude Block

Defines the agent format version:

```yaml theme={null}
autoClaude:
  version: '3.0'
  migratedAt: '2026-01-29T02:24:10.724Z'
```

### Agent Metadata

Core identification:

```yaml theme={null}
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:

<AccordionGroup>
  <Accordion title="Archetype & Zodiac">
    ```yaml theme={null}
    persona_profile:
      archetype: Analyst
      zodiac: ♍ Virgo
    ```

    **Available Archetypes:**

    * Visionary (♐ Sagittarius)
    * Builder (♒ Aquarius)
    * Guardian (♍ Virgo)
    * Analyst (♍ Virgo)
    * Conductor (♎ Libra)
    * Strategist (♑ Capricorn)
  </Accordion>

  <Accordion title="Communication Style">
    ```yaml theme={null}
    communication:
      tone: analytical          # conceptual, pragmatic, analytical, etc.
      emoji_frequency: low      # low, medium, high
      vocabulary:
        - analisar
        - investigar
    ```
  </Accordion>

  <Accordion title="Greeting Levels">
    ```yaml theme={null}
    greeting_levels:
      minimal: '📊 data-wizard Agent ready'
      named: "📊 DataWizard (Analyst) ready!"
      archetypal: '📊 DataWizard the Analyst ready!'
    ```
  </Accordion>

  <Accordion title="Signature Closing">
    ```yaml theme={null}
    signature_closing: '— DataWizard, revelando padrões 📈'
    ```
  </Accordion>
</AccordionGroup>

### Persona Details

Defines role and principles:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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

<Steps>
  <Step title="Create Agent File">
    Create a new file in `.aiox-core/development/agents/`:

    ```bash theme={null}
    touch .aiox-core/development/agents/my-agent.md
    ```
  </Step>

  <Step title="Add Agent Definition">
    Copy the template structure and customize:

    ```yaml theme={null}
    # 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
    \`\`\`
    ```
  </Step>

  <Step title="Define Commands">
    Add commands your agent can perform:

    ```yaml theme={null}
    commands:
      - name: help
        visibility: [full, quick, key]
        description: 'Show available commands'
      
      - name: my-task
        visibility: [full, quick, key]
        description: 'Perform my task'
    ```
  </Step>

  <Step title="Create Task Files">
    Create corresponding task files in `.aiox-core/development/tasks/`:

    ```bash theme={null}
    touch .aiox-core/development/tasks/my-task.md
    ```
  </Step>

  <Step title="Sync to IDEs">
    Sync your new agent to all IDEs:

    ```bash theme={null}
    npm run sync:ide
    ```
  </Step>

  <Step title="Test Agent">
    Activate and test:

    ```bash theme={null}
    @my-agent
    *help
    ```
  </Step>
</Steps>

## Task Definition Format

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

### Task Structure

```markdown theme={null}
---
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

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="deterministic">
    Whether task produces predictable output:

    * `true` - Same input always produces same output
    * `false` - Output may vary
  </Accordion>

  <Accordion title="elicit">
    Whether task requires user interaction:

    * `true` - Must interact with user
    * `false` - Can run autonomously
  </Accordion>

  <Accordion title="composable">
    Whether task can be part of workflow:

    * `true` - Can be chained with other tasks
    * `false` - Standalone only
  </Accordion>

  <Accordion title="verification">
    How to verify task completion:

    * `none` - No verification
    * `command` - Run shell command
    * `manual` - Human verification
    * `api` - API call
    * `browser` - Browser check
  </Accordion>

  <Accordion title="selfCritique">
    Self-review requirements:

    * `required: true` - Mandatory self-critique
    * `checklistRef` - Checklist to use
  </Accordion>
</AccordionGroup>

## ADE Capabilities

Give your agent ADE (Autonomous Development Engine) capabilities:

```yaml theme={null}
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

<CodeGroup>
  ```yaml Metadata theme={null}
  agent:
    name: DataWizard
    id: data-wizard
    title: Data Analysis Specialist
    icon: 📊
  ```

  ```yaml Commands theme={null}
  commands:
    - name: analyze-dataset
      description: 'Comprehensive data analysis'
    - name: create-visualization
      description: 'Generate visualizations'
    - name: statistical-test
      description: 'Run statistical tests'
  ```

  ```yaml ADE Capabilities theme={null}
  autoClaude:
    specPipeline:
      canResearch: true
    execution:
      canExecute: true
    memory:
      canExtractPatterns: true
  ```
</CodeGroup>

### Content Writer Agent

<CodeGroup>
  ```yaml Metadata theme={null}
  agent:
    name: ScribeMaster
    id: content-writer
    title: Content Writing Specialist
    icon: ✍️
  ```

  ```yaml Commands theme={null}
  commands:
    - name: write-article
      description: 'Write blog article'
    - name: edit-content
      description: 'Edit and improve content'
    - name: seo-optimize
      description: 'SEO optimization'
  ```

  ```yaml ADE Capabilities theme={null}
  autoClaude:
    specPipeline:
      canGather: true
      canWrite: true
    qa:
      canReview: true
  ```
</CodeGroup>

### DevOps Agent

<CodeGroup>
  ```yaml Metadata theme={null}
  agent:
    name: OpsCommander
    id: devops
    title: DevOps & Infrastructure Specialist
    icon: 🔧
  ```

  ```yaml Commands theme={null}
  commands:
    - name: deploy-service
      description: 'Deploy application'
    - name: configure-ci
      description: 'Configure CI/CD'
    - name: monitor-health
      description: 'Check system health'
  ```

  ```yaml ADE Capabilities theme={null}
  autoClaude:
    execution:
      canExecute: true
      canVerify: true
    recovery:
      canTrackAttempts: true
      canRollback: true
  ```
</CodeGroup>

## Activation Instructions

Control how your agent activates:

```yaml theme={null}
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](/advanced/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

<CardGroup cols={2}>
  <Card title="Single Responsibility" icon="bullseye">
    Each agent should have one clear purpose
  </Card>

  <Card title="Clear Commands" icon="list">
    Command names should be self-explanatory
  </Card>

  <Card title="Comprehensive Help" icon="circle-question">
    Always include a `*help` command
  </Card>

  <Card title="Task-First Design" icon="diagram-project">
    Define tasks before creating agents
  </Card>

  <Card title="Use Templates" icon="copy">
    Provide templates for common outputs
  </Card>

  <Card title="Enable Self-Critique" icon="magnifying-glass">
    Require self-review for quality
  </Card>
</CardGroup>

## Testing Your Agent

<Steps>
  <Step title="Validate Definition">
    ```bash theme={null}
    npm run validate:agents
    ```
  </Step>

  <Step title="Sync to IDEs">
    ```bash theme={null}
    npm run sync:ide
    ```
  </Step>

  <Step title="Activate Agent">
    ```bash theme={null}
    @my-agent
    ```
  </Step>

  <Step title="Test Commands">
    ```bash theme={null}
    *help
    *my-command
    ```
  </Step>

  <Step title="Verify Task Execution">
    Test each task with real inputs
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Agent Not Appearing">
    ```bash theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Command Not Working">
    * Check command is in `dependencies.tasks`
    * Verify task file exists
    * Ensure task follows TASK-FORMAT-SPEC-V1
  </Accordion>

  <Accordion title="Activation Fails">
    * Check `activation-instructions` are correct
    * Verify greeting template variables exist
    * Test in minimal IDE (Codex CLI)
  </Accordion>
</AccordionGroup>

## Migration from V2 to V3

Migrate legacy agents to autoClaude V3:

```bash theme={null}
@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](/advanced/ade#epic-2-migration-v2v3) for details.

## Related Documentation

<CardGroup cols={2}>
  <Card title="ADE System" icon="brain-circuit" href="/advanced/ade">
    Give agents autonomous capabilities
  </Card>

  <Card title="Squads" icon="people-group" href="/advanced/squads">
    Organize agents into teams
  </Card>

  <Card title="IDE Integration" icon="code" href="/advanced/ide-integration">
    Deploy agents to your IDE
  </Card>

  <Card title="Agent Reference" icon="users" href="/agents/overview">
    See existing agent examples
  </Card>
</CardGroup>

## Examples Repository

<Card title="Custom Agent Examples" icon="github" href="https://github.com/SynkraAI/aiox-custom-agents">
  Community-contributed custom agents for inspiration
</Card>