Composing Skills

Requires OS 0.7.0 or newer.

A skill can call other skills. Declare the one you want as a type annotation, then call it like a method — the runtime runs it to completion and returns control to your code. This is how you build a high-level behavior out of capabilities you already have, without re-implementing navigation, manipulation, or speech.

Declare, then call

Sub-skills are declared exactly like robot state — annotate the attribute with the skill’s class:

from innate import Skill, SkillReturn
from innate_skills.move_straight import MoveStraight
from innate_skills.turn_in_place import TurnInPlace

class PatrolCorner(Skill):
    move: MoveStraight
    turn: TurnInPlace

    def guidelines(self) -> str:
        return "Use to walk the robot around one corner of the room."

    def execute(self) -> SkillReturn:
        self.move(distance=1.0)
        self.turn(angle_degrees=90)
        return "Rounded the corner"

Each call:

Blocks until the sub-skill finishes — no callbacks or polling.
Raises SkillFailed if the sub-skill fails, so a failing step stops the routine unless you catch it.
Returns a SkillOutput — .message, .data, and .ok.
Shows up as its own step in the app timeline, so a composed routine is legible while it runs.

Declaring a sub-skill also means a missing or broken dependency fails the run up front, before the robot moves, instead of halfway through.

Learned policies call the same way

A physical skill — a trained policy or recorded demonstration — has no class of its own, so the catalog generates a typed reference for it inside its own folder. Import and declare it exactly like a code skill:

from innate_skills.pick_socks import PickSocks   # a trained ACT policy
from innate_skills.wave import Wave              # a recorded demonstration

class TidyUp(Skill):
    pick: PickSocks
    wave: Wave

    def guidelines(self) -> str:
        return "Use to greet the room and then pick up any socks on the floor."

    def execute(self) -> SkillReturn:
        self.wave()
        self.pick(timeout=60)     # bound how long a policy may run
        return "Tidied up"

The caller doesn’t need to know how a sub-skill is implemented. See Policy-Defined Skills for how these get trained.

Reading a sub-skill’s output

Skills that return structured data expose it on .data:

result = self.turn(angle_degrees=90)
self.say(f"I turned {result.data.turned_degrees:.0f} degrees.")

Handling failure

A sub-skill that fails raises SkillFailed. Catch it to recover, or let it propagate to fail your skill too — which is often what you want for a step that must succeed:

from innate import SkillFailed

try:
    self.pick(timeout=60)
except SkillFailed:
    self.say("No socks today.")

Never catch bare Exception around a sub-skill call and swallow it. Cancellation travels as SkillCancelled, which must reach the runtime for a Stop to work. Catch SkillFailed specifically.

A worked example

Talk, emote, shuffle, turn, and attempt a learned pick — six skills chained into one:

from innate import Battery, Skill, SkillFailed, SkillReturn
from innate_skills.arm.arm_zero_position import ArmZeroPosition
from innate_skills.head_emotion import HeadEmotion
from innate_skills.move_straight import MoveStraight
from innate_skills.pick_socks import PickSocks
from innate_skills.turn_in_place import TurnInPlace


class RunDemo(Skill):
    arm_zero: ArmZeroPosition
    emote: HeadEmotion
    move: MoveStraight
    turn: TurnInPlace
    pick: PickSocks

    battery: Battery | None   # nice to have — the demo runs without a reading

    def guidelines(self) -> str:
        return "Run the demo routine. Use when the user asks for the demo."

    def execute(self) -> SkillReturn:
        runs = self.storage.get("runs", 0) + 1
        self.storage["runs"] = runs

        self.arm_zero()
        self.emote(emotion="excited")
        self.say(f"Demo number {runs}. Watch this.", wait=True)

        for distance in (0.2, -0.2):
            self.move(distance=distance)

        result = self.turn(angle_degrees=90)
        self.say(f"I turned {result.data.turned_degrees:.0f} degrees.")
        self.turn(angle_degrees=-90)

        try:
            self.pick(timeout=60)
        except SkillFailed:
            self.emote(emotion="disappointed")
            self.say("No socks today.")

        if self.battery:
            self.say(f"Battery at {self.battery.percentage:.0%}.")
        return "Demo complete"

Everything else is an ordinary code-defined skill: it declares robot state with annotations, persists counters with self.storage, speaks with self.say(..., wait=True), and returns a plain success message.

Because each sub-skill call is its own step, a composed routine is easy to follow in the app and easy to interrupt — a Stop unwinds the whole chain, wherever it is.

Choosing a skill at run time

When you don’t know which skill to call until the routine is running, dispatch by id:

output = self.skills.run("innate-os/turn_in_place", angle_degrees=90, timeout=20)
if not output.ok:
    self.fail(output.message)

self.skills.run() returns a failed SkillOutput rather than raising, so you check .ok yourself. Prefer a declaration whenever the skill is known ahead of time — it’s typed, your editor catches renames, and the dependency is verified before the run starts.

When to compose vs. write from scratch

Reach for composition when…	Write a flat skill when…
The building blocks already exist as skills	You need low-level interface control the sub-skills don’t expose
You want each step visible and separately cancellable	The steps are tightly coupled and shouldn’t be interrupted mid-sequence
You’re mixing scripted skills and learned policies	Everything is a few interface calls with no reusable sub-behavior

Composing is also how a one-off demo becomes a reusable capability: name the routine, give it guidelines(), and the agent can trigger the whole chain with a single skill call.

Get Started

MARS Hardware

Simulator

Controller App

Web App

Agent SDK

Hacking on MARS

Manipulation

ROS2 Core

Troubleshooting & Support

Hackathon

Declare, then call

Learned policies call the same way

Reading a sub-skill’s output

Handling failure

A worked example

Choosing a skill at run time

When to compose vs. write from scratch

​Declare, then call

​Learned policies call the same way

​Reading a sub-skill’s output

​Handling failure

​A worked example

​Choosing a skill at run time

​When to compose vs. write from scratch

Declare, then call

Learned policies call the same way

Reading a sub-skill’s output

Handling failure

A worked example

Choosing a skill at run time

When to compose vs. write from scratch