Ikiro Developer Docs

A superpower definition is a YAML or JSON file that describes everything the superpower does. This is the complete schema reference.

Root structure

version: '1.0'                    # Required. Always "1.0"
metadata:                          # Required. Name, description, category
  name: My Superpower
  description: What this does
  category: custom                 # finance | travel | productivity | social | health | entertainment | shopping | custom
  icon: star                       # Emoji or SF Symbol name
  tags: [tag1, tag2]
  version: '1.0.0'

completion_criteria: ''            # Plain-language success statement
escalation: {}                     # Recovery instructions for error scenarios
initial_state: {}                  # Starting state for sessions
trigger_patterns: {}               # Top-level routing triggers
actions: []                        # Array of action definitions
ui_blocks: {}                      # Named UI views (optional)

metadata

Field	Type	Required	Description
`name`	string	Yes	Display name (1-50 chars)
`description`	string	Yes	Short description (1-200 chars)
`category`	enum	Yes	One of: finance, travel, productivity, social, health, entertainment, shopping, custom
`icon`	string	No	Emoji or SF Symbol name
`tags`	string[]	No	Searchable tags
`version`	string	No	Semantic version (default: "1.0.0")

trigger_patterns

Top-level routing — determines when this superpower is activated by the tool router.

trigger_patterns:
  keywords: [umbrella, rain]       # Any keyword match activates
  phrases: [do I need an umbrella] # Exact phrase match
  regex_patterns: []               # Regex patterns
  priority: 5                      # 1-10, higher = checked first

actions

An array of action definitions. Each action has its own triggers, operations, and response.

actions:
  - id: check_weather              # Unique snake_case ID
    name: Check Weather            # Display name
    description: Fetches forecast   # What this action does
    triggers:                       # When this action activates
      keywords: [weather, forecast]
      phrases: [what's the weather]
    operations: []                  # Steps to execute (see Operations Reference)
    response:                       # What to say back
      template: "{{$vars.result}}"
    oauth_required: []              # OAuth scopes needed (gmail, calendar, etc.)
    enabled: true                   # Can be disabled without removing

Action triggers

Field	Type	Description
`keywords`	string[]	Words that activate (case-insensitive, partial match)
`phrases`	string[]	Exact phrases (case-insensitive)
`intents`	string[]	Named intents from the router
`has_image`	boolean	Activate when message has an image
`has_url`	boolean	Activate when message has a URL
`state_condition`	string	Template expression that must be true

Action response

response:
  template: "The weather is {{$vars.weather}}."  # Single response
  # OR
  bubbles:                                         # Multi-bubble (iOS-style)
    - "checking the weather..."
    - "looks like {{$vars.weather}}"

escalation

Recovery instructions for when operations fail.

escalation:
  on_empty_result: "Couldn't find data. Try a different search term."
  on_oauth_failure: "You need to connect your Gmail first."
  on_ambiguous_input: "Which city did you mean?"
  on_rate_limit: "Too many requests. Try again in a minute."

initial_state

Starting state for superpower sessions. Operations can read and update state.

initial_state:
  count: 0
  history: []
  last_checked: null

Access state in templates with {{$state.count}}.

completion_criteria

Plain-language statement of when the superpower has successfully completed its job. Used for internal quality evaluation.

completion_criteria: "User receives a clear yes/no umbrella verdict with supporting weather details."

Definition Schema