Overview

A code-defined skill is a Python class that implements a robot behavior with explicit logic. One rule covers everything it consumes: annotate it.

from innate import MainImage, Mobility, Skill


class FindTheDog(Skill):
    """Drive around until the dog is in frame. Use when the user asks
    where the dog is."""

    mobility: Mobility          # an interface — the base
    image: MainImage            # a sensor feed — the head camera

    def execute(self, max_turns: int = 8):
        for _ in range(max_turns):
            if looks_like_a_dog(self.image):
                return "Found the dog"
            self.mobility.rotate(0.8)
        self.fail("No dog anywhere")

Three things fall out of that class, and there is no boilerplate for any of them: The class name is the skill name. class FindTheDog becomes find_the_dog. Defining the class is what registers it — no name property, no registration call, no file scanning. The class docstring is the guidelines. It is the text the agent reads to decide when to call the skill, so write it for the agent, not for a reviewer. A skill states its purpose exactly once. The execute() signature is the parameter schema. The agent sees execute(self, max_turns: int = 8) and knows what it may pass. Type hints and defaults are part of the contract, so annotate them.

Declaring what you need

Every feed — interfaces, cameras, robot state, other skills — is declared the same way: a bare type annotation on the class. The type identifies the feed, so there is nothing to wire in __init__.

from innate import Arm, Battery, Manipulation, Mobility, Odometry, Skill
from innate_skills.arm_rest_position import ArmRestPosition


class TidyUp(Skill):
    """Put the arm away and back off."""

    mobility: Mobility               # interface
    manipulation: Manipulation       # interface
    odom: Odometry                   # robot state
    arm: Arm                         # robot state
    battery: Battery | None          # best effort — may be None
    arm_rest: ArmRestPosition        # another skill, called like a method

A plain annotation is guaranteed. The runtime waits for the first value before execute() starts and fails the run up front if none arrives, so a declared feed is never None inside execute() and needs no guard. The wait is bounded per feed — cameras get 3 s because they start with the run, the battery gets 6 s because it only publishes every few seconds, everything else 2 s. | None makes it best effort. battery: Battery | None is injected when a value is available and left None otherwise, and the run starts either way. Reading a feed you didn’t declare raises immediately with the annotation to add, and because the annotations are real types your editor flags a typo before you ship. The four interfaces: See Robot state for the full list of state feeds, Navigation interfaces and Body control interfaces for what the interfaces do, and Composing skills for declaring other skills.

Returning a result

execute() returns the message the agent will read:

def execute(self):
    return "Reached the counter"     # SUCCESS

Returning None is also success. To fail, call self.fail(message) — it raises, so there is no “and then return” to forget:

if distance > 3.0:
    self.fail(f"Target is {distance:.1f}m away — too far to reach safely")

To attach a structured payload for a skill that calls yours, return a SkillOutput:

from pydantic import BaseModel

from innate import Skill, SkillOutput


class MoveResult(BaseModel):
    traveled_m: float


class MoveStraight(Skill):
    """Move the robot straight forward or backward, in meters."""

    def execute(self, distance: float):
        ...
        return SkillOutput(f"Moved {traveled:.2f}m", MoveResult(traveled_m=traveled))

A caller then reads out.message, out.data, out.status and out.ok. SkillOutput also takes image=jpeg_bytes to hand the agent a picture as evidence alongside the message.

The 0.6.x return "message", SkillResult.SUCCESS tuple still works and still normalizes correctly, but it is deprecated — new skills should return the message and call self.fail().

Cancellation is the framework’s job

Write the loop as if cancel didn’t exist. Every blocking framework call raises SkillCancelled the moment a Stop lands, the base is braked and the arm halted automatically, and the run reports CANCELLED — you don’t catch it, and you don’t need a cancel() method.

In skill code, use self.sleep(seconds). Never time.sleep(seconds).self.sleep wakes and raises the moment a Stop lands; time.sleep blocks to completion, so a skill that uses it keeps running — and keeps the robot moving — after the user pressed Stop. Sleeping is the only cancel point a loop needs.

while traveled < target:
    self.mobility.send_cmd_vel(linear_x=velocity, duration=0.5)
    self.sleep(0.1)          # cancellable
    # time.sleep(0.1)        # Stop is ignored until the sleep finishes
    traveled = math.dist(self.odom.position, start)

time itself is fine for measuring — time.time() and time.monotonic() for deadlines and elapsed checks. The rule is only about blocking.

Call	Use for
`self.sleep(seconds)`	Any pause in skill code
`self.wait_for(read, timeout)`	Block until `read()` returns non-`None`
`self.check_cancelled()`	A checkpoint with no sleep, e.g. right before an irreversible commit
`self.cancelled`	Read the latch without raising

Cleanup belongs in a try/finally inside execute(). self.on_cancel(hook) exists only to forward a cancel to an external action goal — braking the base is already automatic. Overriding cancel() is rare enough that the base class handles it for you.

Progress, speech and storage

Feedback streams a progress line to whoever launched the skill — the agent reads it live and can act on it, including cancelling you or triggering something else:

self.feedback(f"Step {i + 1}/10")

Speech is fire-and-forget by default; wait=True blocks until playback ends:

self.say("Starting the sweep.")
self.say("All done!", wait=True)

Storage is a per-skill key-value store that survives restarts:

runs = self.storage.get("runs", 0) + 1
self.storage["runs"] = runs

Expensive objects: `@resource`

When a skill owns something costly to build, declare it with @resource. It is constructed on first access, cached for the run, and torn down at the end while the interfaces are still alive:

from innate import Skill, resource


class NavigateSomewhere(Skill):
    """Drive to a map position."""

    @resource
    def controller(self):
        c = Nav2Controller(self)
        yield c
        c.destroy()          # runs at the end of the run

Skill instances are per-run: constructed when the run starts, disposed when it ends. Don’t stash state on self expecting it to survive — that’s what self.storage is for.

Next steps

Navigation interfaces — driving and rotating the base
Body control interfaces — the arm SDK, the gripper, the head
Robot state — cameras, odometry, map, lidar, battery
Composing skills — declaring and calling other skills, including trained policies
Physical skill examples — full-body behaviors combining navigation and manipulation
External services & APIs — APIs, email, web services

Get Started

MARS Hardware

Simulator

Controller App

Web App

Agent SDK

Hacking on MARS

Manipulation

ROS2 Core

Troubleshooting & Support

Hackathon

Declaring what you need

Returning a result

Cancellation is the framework’s job

Progress, speech and storage

Expensive objects: `@resource`

Next steps

​Declaring what you need

​Returning a result

​Cancellation is the framework’s job

​Progress, speech and storage

​Expensive objects: @resource

​Next steps

Declaring what you need

Returning a result

Cancellation is the framework’s job

Progress, speech and storage

Expensive objects: `@resource`

Next steps