Agent YAML Specification

Agents are defined in YAML files placed in ~/.pilot/agents/ (Global) or .pilot/agents/ (Project).

Schema

agent:
  id: string          # Unique identifier (e.g., "my-agent")
  name: string        # Display name
  description: string # Purpose description
  category: string    # grouping (development, security, etc.)
  version: string     # Semantic version

model:
  provider: string    # ollama, openai, etc.
  name: string        # Model name (e.g., gpt-4)
  temperature: float  # 0.0 to 1.0 (Creative vs Deterministic)
  max_tokens: int

system_prompt: string | multiline-string

tools:
  - type: mcp
    server: string    # MCP server name (e.g., filesystem)
    allowed: [string] # List of allowed tool names (e.g., read_file)
  
  - type: command
    name: string      # Command alias
    
behavior:
  autonomy: string    # suggest | auto | supervised

Example

agent:
  id: code-refactor
  name: Legacy Code Refactorer
  description: Modernizes Python codebases
  
model:
  provider: openai
  name: gpt-4-turbo
  
system_prompt: |
  You are an expert in Python modernization.
  Update type hints, use f-strings, and improve readability.
  
tools:
  - type: mcp
    server: filesystem
    allowed: [read_file, write_file, list_directory]