Code Skills

A code-defined skill is a Python class. The agent reads your guidelines() to decide when to call it, and your execute() signature to know how.

import math
from innate import Head, Mobility, Skill, SkillReturn


class LookAround(Skill):
    mobility: Mobility   # declared dependencies are injected before execute()
    head: Head

    def guidelines(self) -> str:
        return "Use when the robot needs to scan its surroundings."

    def execute(self, directions: int = 4) -> SkillReturn:
        """Turn in place and look around.

        Args:
            directions: How many stops to make in a full turn.
        """
        self.head.set_position(-15)
        for i in range(max(1, directions)):
            self.feedback(f"Looking {i + 1}/{directions}")
            self.mobility.rotate(2 * math.pi / directions)
            self.sleep(0.2)
        return "Scan complete"

Save it in ~/innate-os/workspace/custom_skills/ and it’s live as look_around. Type hints and the docstring are what the agent sees, so write them carefully. guidelines() is a prompt: tune it when the robot calls your skill at the wrong time.

Declare what you need

Annotate a class attribute and the runtime provides it. A plain annotation is required: the run fails before starting if it’s unavailable, so you never check for None. Add | None to make it optional.

class MySkill(Skill):
    mobility: Mobility          # hardware
    image: MainImage            # sensor feed, kept fresh at 50 Hz
    battery: Battery | None     # optional
    turn: TurnInPlace           # another skill

You can declare	Reference
`Mobility`, `Manipulation`, `Head`	Movement API
Cameras, odometry, map, battery, LiDAR, arm state	Robot state
`SpatialMemory`	Spatial memory
`Llm`	Ask a model below
Other skills	Call other skills below

Return a result

Outcome	How
Success	`return "Moved 2 meters"` (or `return None`)
Failure	`self.fail("Target out of range")`. It raises, so code after it doesn’t run.
Cancelled	Happens automatically when someone presses Stop

To return more than a message, use SkillOutput:

from innate import SkillOutput

return SkillOutput("Found it", data={"x": 1.2})   # data for a calling skill
return SkillOutput("Found it", image=jpeg_bytes)  # an image the agent can look at

Cancellation

A Stop can come at any time, and the framework handles it. Follow one rule: use self.sleep(), never time.sleep(). Every blocking framework call raises on Stop, the base brakes, and the arm halts. You don’t catch anything.

Call	Use for
`self.sleep(seconds)`	Any pause
`self.wait_for(read, timeout)`	Wait until `read()` returns something other than `None`
`self.check_cancelled()`	A checkpoint before something irreversible

Put cleanup in try/finally. Using time.time() to measure durations is fine.

Other helpers

self.feedback("Step 3/10")          # progress the agent sees while you run
self.say("Found it!", wait=True)    # speak; wait=True blocks until done
self.storage["runs"] = 3            # key-value store that survives restarts
self.logger.info("debug message")   # shows in the logs

Call other skills

Declare another skill like any dependency, then call it like a method. The call blocks until it finishes, shows up as its own step in the app, and returns a SkillOutput. Trained policies work the same way.

from innate import Skill, SkillFailed
from innate_skills.navigate_to_position import NavigateToPosition
from innate_skills.pick_socks import PickSocks  # a trained policy


class TidyCorner(Skill):
    go: NavigateToPosition
    pick: PickSocks

    def guidelines(self) -> str:
        return "Use to drive to the corner and pick up a sock there."

    def execute(self):
        self.go(x=1.0, y=0.0, local_frame=True)
        try:
            self.pick(timeout=60)
        except SkillFailed:
            return "No sock to pick up"
        return "Corner tidied"

A failing sub-skill raises SkillFailed. Catch that, not bare Exception, or Stop won’t work.

Ask a model

Declare llm: Llm and ask it about a camera frame. You get the robot’s model, with its keys already set up.

from innate import Llm, MainImage, Skill


class IsDoorOpen(Skill):
    image: MainImage
    llm: Llm

    def guidelines(self) -> str:
        return "Use to check whether the door in front of the robot is open."

    def execute(self):
        answer = self.llm.ask(self.image, "Is the door in this image open? Answer only YES or NO.")
        if answer is None:
            self.fail("No model is reachable")
        return "The door is open" if "YES" in answer.upper() else "The door is closed"


`self.llm.ask(images, question)`	Sends one or two base64 JPEGs, like `MainImage` or `WristImage`, with your question. Returns the reply text, or `None` if the model can’t be reached or all 3 tries fail.
`llm: Llm = Llm("google:gemini-3.5-flash")`	Pin a model for this skill, whatever the robot is set to
`Llm("google:gemini-3.5-flash", thinking="minimal")`	Also set how long it reasons. `minimal` is fastest for quick yes/no or box questions.

Call external services

Skills can call any API. Read secrets from the environment, set timeouts, and turn errors into self.fail():

import os
import requests
from innate import Skill


class GetWeather(Skill):
    def guidelines(self) -> str:
        return "Use when the user asks about the weather. Can't be cancelled."

    def execute(self, city: str):
        key = os.environ.get("WEATHER_API_KEY")
        if not key:
            self.fail("WEATHER_API_KEY is not set")
        try:
            r = requests.get("https://api.example.com/weather",
                             params={"q": city, "key": key}, timeout=10)
            r.raise_for_status()
        except requests.RequestException as e:
            self.fail(f"Weather service error: {e}")
        return r.json()["summary"]

A network call can’t be interrupted halfway. Say so in guidelines() so the agent plans for it.

The best examples are the shipped skills in workspace/innate_skills/. pick_any_object.py combines vision, driving, and grasping.

Get Started

Simulator

Build Agents and Skills

MARS

Train a Policy

Go Deeper

Help

Declare what you need

Return a result

Cancellation

Other helpers

Call other skills

Ask a model

Call external services

​Declare what you need

​Return a result

​Cancellation

​Other helpers

​Call other skills

​Ask a model

​Call external services

Declare what you need

Return a result

Cancellation

Other helpers

Call other skills

Ask a model

Call external services