Skip to main content

​
Overview

AIOX agents are defined in markdown files with embedded YAML blocks. Each agent combines persona configuration, command definitions, dependencies, and activation instructions in a single, self-contained file.
​
Location
string
.aiox-core/development/agents/*.md
​
Format
string
Markdown with YAML frontmatter
​
Extension
string
.md (Markdown)

​
File Structure

Agent files follow a strict structure with YAML configuration block: 
# {agent-id}

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

CRITICAL: Read the full YAML BLOCK that FOLLOWS...

## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED

```yaml
IDE-FILE-RESOLUTION:
  # Dependency resolution rules

REQUEST-RESOLUTION:
  # Command matching rules

activation-instructions:
  # Activation steps

agent:
  # Agent metadata

persona_profile:
  # Communication style

persona:
  # Role and behavior

commands:
  # Available commands

dependencies:
  # Required files


## Schema Reference

### Agent Metadata

<ParamField path="agent" type="object" required>
  Core agent identification and metadata
  
  <Expandable title="properties">
    <ResponseField name="name" type="string" required>
      Human-friendly agent name
      
      Example: `"Dex"`, `"Aria"`, `"Quinn"`
    </ResponseField>
    
    <ResponseField name="id" type="string" required>
      Unique agent identifier (slug format)
      
      Example: `"dev"`, `"architect"`, `"qa"`
    </ResponseField>
    
    <ResponseField name="title" type="string" required>
      Agent role title
      
      Example: `"Full Stack Developer"`, `"Architect"`
    </ResponseField>
    
    <ResponseField name="icon" type="string" required>
      Emoji icon representing the agent
      
      Example: `"💻"`, `"🏛️"`, `"🧪"`
    </ResponseField>
    
    <ResponseField name="whenToUse" type="string" required>
      Guidance on when to activate this agent
      
      Multi-line description of agent's primary use cases and delegation patterns.
    </ResponseField>
    
    <ResponseField name="customization" type="string">
      Custom behavior overrides (takes precedence over all other instructions)
    </ResponseField>
  </Expandable>
</ParamField>

### Persona Profile

<ParamField path="persona_profile" type="object" required>
  Agent communication style and personality
  
  <Expandable title="properties">
    <ResponseField name="archetype" type="string" required>
      Agent archetype: `"Builder"`, `"Visionary"`, `"Guardian"`, `"Analyst"`
    </ResponseField>
    
    <ResponseField name="zodiac" type="string">
      Zodiac sign for personality reference
      
      Example: `"♒ Aquarius"`, `"♐ Sagittarius"`
    </ResponseField>
    
    <ResponseField name="communication" type="object" required>
      Communication style configuration
      
      <Expandable title="communication properties">
        <ResponseField name="tone" type="string" required>
          Communication tone: `"pragmatic"`, `"conceptual"`, `"analytical"`
        </ResponseField>
        
        <ResponseField name="emoji_frequency" type="string" required>
          Emoji usage level: `"low"`, `"medium"`, `"high"`
        </ResponseField>
        
        <ResponseField name="vocabulary" type="array" required>
          List of preferred vocabulary words used by the agent (e.g., construir, implementar, refatorar)
        </ResponseField>

        <ResponseField name="greeting_levels" type="object" required>
          Agent greeting variations with minimal, named, and archetypal levels
        </ResponseField>
        
        <ResponseField name="signature_closing" type="string" required>
          Agent signature closing message
          
          Example: `"— Dex, sempre construindo 🔨"`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

### Persona Behavior

<ParamField path="persona" type="object" required>
  Agent role, behavior, and operating principles
  
  <Expandable title="properties">
    <ResponseField name="role" type="string" required>
      Agent's primary role
      
      Example: `"Expert Senior Software Engineer & Implementation Specialist"`
    </ResponseField>
    
    <ResponseField name="style" type="string" required>
      Working style description
      
      Example: `"Extremely concise, pragmatic, detail-oriented"`
    </ResponseField>
    
    <ResponseField name="identity" type="string" required>
      Core identity statement
    </ResponseField>
    
    <ResponseField name="focus" type="string" required>
      Primary focus areas
    </ResponseField>
    
    <ResponseField name="core_principles" type="array">
      List of operating principles
      
      Each item is a string principle like `"Story has ALL info needed"` or `"ONLY update Dev Agent Record sections"`
    </ResponseField>
    
    <ResponseField name="responsibility_boundaries" type="object">
      Delegation and collaboration patterns
      
      <Expandable title="responsibility_boundaries">
        <ResponseField name="primary_scope" type="array">
          Agent's primary responsibilities as array of strings
        </ResponseField>
        
        <ResponseField name="delegate_to_{agent}" type="object">
          When to delegate to other agents. Each delegation object contains `when` (array), `retain` (array), and `collaboration_pattern` (string) fields.
          
          Example delegation: `delegate_to_data_engineer` with `when: ["Database schema design", "Query optimization"]`
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ParamField>

### Activation Instructions

<ParamField path="activation-instructions" type="array" required>
  Step-by-step activation sequence
  
  Defines how the agent should activate, display greeting, and prepare for work. Each item is a string instruction like `"STEP 1: Read THIS ENTIRE FILE"` or `"STEP 5: HALT and await user input"`
</ParamField>

### Commands

<ParamField path="commands" type="array" required>
  Available agent commands
  
  <Expandable title="command schema">
    <ResponseField name="name" type="string" required>
      Command name (without `*` prefix)
      
      Example: `"help"`, `"develop"`, `"create-service"`
    </ResponseField>
    
    <ResponseField name="visibility" type="array" required>
      Visibility levels: `["full", "quick", "key"]`
      
      - `key` - Most important commands (shown in greeting)
      - `quick` - Frequently used commands
      - `full` - All commands (shown in `*help`)
    </ResponseField>
    
    <ResponseField name="description" type="string" required>
      Command description
    </ResponseField>
  </Expandable>
</ParamField>

### Dependencies

<ParamField path="dependencies" type="object" required>
  External files required by agent
  
  <Expandable title="dependency categories">
    <ResponseField name="checklists" type="array">
      Quality gate checklists
      
      Array of filenames like `["story-dod-checklist.md", "self-critique-checklist.md"]`
    </ResponseField>
    
    <ResponseField name="tasks" type="array">
      Executable task workflows
      
      Array of filenames like `["dev-develop-story.md", "create-service.md", "qa-fix-issues.md"]`
    </ResponseField>
    
    <ResponseField name="templates" type="array">
      File generation templates
      
      Array of filenames or directories like `["story-template.md", "service-template/"]`
    </ResponseField>
    
    <ResponseField name="scripts" type="array">
      JavaScript/Node.js scripts
      
      Array of filenames like `["recovery-tracker.js", "build-orchestrator.js"]`
    </ResponseField>
    
    <ResponseField name="tools" type="array">
      External tools and MCP servers
      
      Array of tool names like `["coderabbit", "git", "context7"]`
    </ResponseField>
  </Expandable>
</ParamField>

## File Resolution Rules

<ParamField path="IDE-FILE-RESOLUTION" type="array">
  Rules for resolving dependency file paths
  
  Dependencies map to `.aiox-core/development/{type}/{name}` where:
  - `type` = folder (tasks, templates, checklists, data, utils)
  - `name` = file name
  
  Example: `create-doc.md` → `.aiox-core/development/tasks/create-doc.md`
</ParamField>

<ParamField path="REQUEST-RESOLUTION" type="string">
  Rules for matching user requests to commands
  
  Example: `"draft story"` → `*create` → `create-next-story` task
</ParamField>

## Agent Examples

### Dev Agent (Builder)

```yaml
agent:
  name: Dex
  id: dev
  title: Full Stack Developer
  icon: 💻
  whenToUse: 'Use for code implementation, debugging, refactoring'

persona_profile:
  archetype: Builder
  communication:
    tone: pragmatic
    emoji_frequency: medium
    greeting_levels:
      archetypal: '💻 Dex the Builder ready to innovate!'

persona:
  role: Expert Senior Software Engineer
  style: Extremely concise, pragmatic, detail-oriented
  core_principles:
    - FOLLOW develop-story command
    - ONLY update Dev Agent Record sections

​
Architect Agent (Visionary)

agent:
  name: Aria
  id: architect
  title: Architect
  icon: 🏛️
  whenToUse: 'Use for system architecture, API design, security'

persona_profile:
  archetype: Visionary
  communication:
    tone: conceptual
    emoji_frequency: low
    greeting_levels:
      archetypal: '🏛️ Aria the Visionary ready to envision!'

persona:
  role: Holistic System Architect
  style: Comprehensive, pragmatic, user-centric
  responsibility_boundaries:
    delegate_to_data_engineer:
      when:
        - Database schema design
        - Query optimization

​
Command Examples

commands:
  - name: help
    visibility: [full, quick, key]
    description: 'Show all available commands'
  - name: develop
    visibility: [full, quick]
    description: 'Implement story tasks'
  - name: create-service
    visibility: [full]
    description: 'Generate new service from template'

​
Dependency Examples

dependencies:
  checklists:
    - story-dod-checklist.md
    - self-critique-checklist.md
  tasks:
    - dev-develop-story.md
    - create-service.md
    - qa-fix-issues.md
  templates:
    - story-template.md
    - service-template/
  scripts:
    - recovery-tracker.js
    - build-orchestrator.js
  tools:
    - coderabbit
    - git
    - context7

​
Agent Activation Shortcuts

Agents can be activated using multiple patterns:
​
Slash Commands
array
  • /dev, /architect, /qa
  • /@dev, /@architect, /@qa
  • /dev.md, /architect.md
​
At-mentions
array
  • @dev, @architect, @qa
​
Skill Activation
string
/skills → Select aiox-{agent-id} from local skills

​
Best Practices

  • Define clear responsibility boundaries
  • Specify delegation patterns to other agents
  • Keep commands focused and atomic
  • Document when to use vs. delegate
  • Include educational greeting levels
  • Use visibility levels appropriately (key < quick < full)
  • Provide clear, concise descriptions
  • Group related commands together
  • Use consistent naming patterns (create-*, qa-*)
  • List all required files explicitly
  • Organize by category (tasks, checklists, templates)
  • Use relative paths from .aiox-core/development/
  • Document purpose of each dependency
  • Match tone to agent archetype
  • Use consistent vocabulary
  • Define clear core principles
  • Specify boundaries and collaboration patterns

​
IDE Sync Integration

Agent definitions are automatically synced to IDE-specific formats:
​
Claude Code
string
.claude/commands/AIOX/agents/{agent-id}.md (full-markdown-yaml)
​
Codex
string
.codex/agents/{agent-id}.md (full-markdown-yaml)
​
Gemini
string
.gemini/rules/AIOX/agents/{agent-id}.md (full-markdown-yaml)
​
Cursor
string
.cursor/rules/agents/{agent-id} (condensed-rules)
Sync via: 
npm run sync:ide          # Sync all IDEs
npm run sync:ide:claude   # Sync Claude Code only
npm run sync:ide:check    # Validate sync drift
Reference: .aiox-core/development/agents/

Build docs developers (and LLMs) love

Get started for freeTalk to us