🤖 Agent AI Skill Developer Program

Master Agent AI skill development and empower your robots with intelligent interaction capabilities. Complete projects to earn free token credits for robot model training and data collection on the XRollout platform.

🎁 Earn up to 1000 free tokens upon completion

📚

Online Tutorials

From basics to advanced, master Agent AI Skill development step-by-step

Agent AI Fundamentals

Understand what Agent AI is, the role of Skills in the Agent framework, and core design principles.

30 min Beginner ✦ Expanded

Learning Objectives

Describe the perception–reasoning–action loop that drives an Agent AI system
Explain how Skills are discovered, loaded, and invoked at runtime
Identify the four core design principles: modularity, composability, safety, and observability
Distinguish stateless vs. stateful Skills and know when to use each
Read and interpret a SKILL.md specification file

Agent AI Architecture

┌─────────────────────────── Agent Runtime ────────────────────────────┐ │ │ │ Perception Layer Reasoning Core Action Executor │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │ Camera / IMU │ ──────► │ LLM Planner │ ──────► │ Skill Router │ │ │ │ Microphone │ │ (chain-of- │ │ │ │ │ │ Joint States │ │ thought) │ └──────┬───────┘ │ │ └──────────────┘ └──────────────┘ │ │ │ ▼ │ │ ┌────────────────────┐ │ │ │ Skill Registry │ │ │ │ ┌──────────────┐ │ │ │ │ │ skill_A.py │ │ │ │ │ │ skill_B.py │ │ │ │ │ │ SKILL.md │ │ │ │ │ └──────────────┘ │ │ │ └────────────────────┘ │ └────────────────────────────────────────────────────────────────────────┘ Feedback loop: action results feed back into Perception

Core Concepts

🧩 What is a Skill?

A self-contained, versioned capability unit. Each Skill exposes a single entry-point function, declares its inputs/outputs in a SKILL.md manifest, and can be loaded or hot-swapped without restarting the Agent.

🔄 Skill Lifecycle

Discover → Load → Validate → Execute → Unload. The runtime auto-discovers Skills from a registry path, validates their manifest schema, then exposes them to the planner as callable tools.

📦 Stateless vs. Stateful

Stateless Skills (e.g., object detection) produce the same output for the same input with no memory. Stateful Skills (e.g., navigation planner) maintain internal state across invocations via a SkillContext object.

🛡️ Safety Guardrails

Every Skill runs inside a sandboxed subprocess with resource limits (CPU, memory, time). Safety-critical Skills (motion, power) require an additional @safety_verified decorator to be scheduled.

The Four Design Principles

Modularity — one Skill, one responsibility

A Skill should do exactly one thing well. Resist the temptation to bundle detection + tracking + control into a single file. Compose them instead.

Composability — Skills call Skills

The planner can chain Skills into a pipeline. Your Skill can also explicitly invoke a sub-skill via context.invoke("skill_name", args) rather than duplicating logic.

Safety-first — fail loudly and early

Return structured SkillError objects instead of raising raw exceptions. The runtime can then decide whether to retry, escalate, or engage a fallback Skill.

Observability — emit structured logs

Use context.log(level, message, metadata) for every meaningful event. Structured logs flow automatically into the XRollout telemetry dashboard for replay and debugging.

💡 Quick check: Before continuing, make sure you can answer — "What happens between the moment a user says 'pick up the cup' and the robot's gripper closes?" The answer is the entire Agent AI pipeline in microcosm.

Setting Up Your Development Environment

Configure your dev environment, install dependencies, and understand project structure & tooling.

20 min Setup ✦ Expanded

Learning Objectives

Install and verify all required system dependencies
Clone the XRollout Agent SDK and create an isolated Python environment
Understand the project directory layout and configuration files
Run the built-in environment health-check to confirm everything works
Set up VS Code (or any editor) with recommended extensions for Skill development

Prerequisites

Tool	Version	Purpose	Status
Python	3.10 or 3.11	Runtime for all Skills	Required
Git	2.40+	Source control & submodule support	Required
Docker	24+	Simulated robot sandbox	Required
Node.js	20 LTS	XRollout CLI tooling	Required
CUDA Toolkit	12.x	GPU-accelerated vision models	Optional
ROS 2 Humble	Humble Hawksbill	Physical hardware integration	Optional

Installation Steps

Clone the Agent SDK

bash

# Clone repo and enter the workspace
git clone https://github.com/xrollout/agent-sdk.git
cd agent-sdk

# Pull submodules (simulator + example skills)
git submodule update --init --recursive

Create an isolated Python environment

bash

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -e ".[dev]"             # installs SDK + dev tools

Configure environment variables

bash

cp .env.example .env

# Edit .env and fill in your credentials:
#   XROLLOUT_API_KEY=xr-xxxxxxxxxxxxxxxxxx
#   AGENT_SKILL_REGISTRY_PATH=./skills
#   AGENT_SANDBOX_BACKEND=docker   # or "local"

Run the environment health-check

bash

python -m agent_sdk.check_env

# Expected output:
# ✓  Python 3.11.9   (ok)
# ✓  Docker 24.0.6   (ok)
# ✓  API key         (authenticated)
# ✓  Skill registry  (3 example skills found)
# ✓  Simulator image (ready)

Project Structure

agent-sdk/ ├── skills/ # your Skills live here │ ├── hello_world/ │ │ ├── skill.py # entry-point: run(context, args) │ │ ├── SKILL.md # manifest: name, I/O schema, triggers │ │ └── requirements.txt # skill-specific pip deps ├── agent_sdk/ # SDK source (don't edit) │ ├── context.py # SkillContext, SkillError │ ├── registry.py # auto-discover & hot-reload │ └── sandbox.py # Docker/local execution wrapper ├── tests/ ├── .env # secrets (git-ignored) ├── pyproject.toml └── README.md

Recommended VS Code Extensions

🐍 Pylance + Ruff

Type-aware autocompletion and fast linting. The SDK ships full type stubs so you get inline docs for every SDK class.

🐳 Dev Containers

One-click open the project inside a pre-built Docker container. Eliminates "works on my machine" issues and mirrors the CI environment exactly.

📄 YAML by Red Hat

SKILL.md uses YAML front matter for its schema block. This extension gives validation and autocompletion against the XRollout JSON Schema.

⚠️ Windows users: Run all commands in WSL2 (Ubuntu 22.04). Native Windows support is experimental and the simulator Docker image currently requires a Linux kernel.

Skill API & Interface Specification

Learn skill lifecycle management, input/output protocols, and error handling patterns.

45 min API Design

Build Your First Skill

Hands-on development of a simple hello-world skill to understand the complete workflow.

60 min Hands-on ✦ Expanded

Learning Objectives

Scaffold a new Skill directory using the XRollout CLI
Implement the required run(context, args) entry-point
Write a valid SKILL.md manifest with input/output schema
Test the Skill locally using the simulator and the SDK test harness
Iterate on your Skill using hot-reload without restarting the Agent

Step-by-Step Walkthrough

Scaffold the Skill with the CLI

The xr new skill command creates a boilerplate directory with all required files.

bash

xr new skill greeting_generator
# Creates: skills/greeting_generator/
#           ├── skill.py
#           ├── SKILL.md
#           └── requirements.txt

Write the SKILL.md manifest

The manifest tells the runtime what this Skill is called, what inputs it accepts, and what it returns.

SKILL.md

---
name: greeting_generator
version: "1.0.0"
description: Generates a context-aware greeting for a given scenario.
trigger_keywords: ["greet", "welcome", "introduce"]

inputs:
  scenario:
    type: string
    description: The context for the greeting (e.g., "lab visit", "delivery")
    required: true
  language:
    type: string
    default: "en"
    enum: ["en", "zh", "ja"]

outputs:
  message:
    type: string
    description: The generated greeting string
---

## Overview
Generates polite, context-sensitive greeting messages for various robot interaction scenarios.

## Usage Notes
Keep `scenario` under 80 characters. For custom languages, use the `language` field
to request an override; the Skill falls back to English if unsupported.

Implement skill.py

Every Skill must expose a top-level run(context, args) function. The SDK injects a SkillContext object that provides logging, sub-skill invocation, and config access.

skill.py

from agent_sdk import SkillContext, SkillArgs, SkillResult, SkillError

# Templates keyed by language
_TEMPLATES = {
    "en": "Hello! I'm your robot assistant. Scenario: {scenario}. How can I help?",
    "zh": "你好！我是您的机器人助手。场景：{scenario}。有什么可以帮您？",
    "ja": "こんにちは！ロボットアシスタントです。シナリオ：{scenario}。",
}

def run(context: SkillContext, args: SkillArgs) -> SkillResult:
    """Entry-point called by the Agent runtime."""

    scenario = args.get("scenario")
    language = args.get("language", "en")

    # Validate required input
    if not scenario:
        return SkillError(code="MISSING_INPUT", message="'scenario' is required")

    # Emit a structured log event
    context.log("info", "Generating greeting", {"scenario": scenario, "lang": language})

    template = _TEMPLATES.get(language, _TEMPLATES["en"])
    message = template.format(scenario=scenario)

    return SkillResult(outputs={"message": message})

Run the built-in test harness

The SDK ships a lightweight test runner that validates your manifest and exercises your run() function without a full Agent.

bash

xr test skills/greeting_generator

# ──────────────────────────────────────────────────
# PASS  manifest schema valid
# PASS  run() returns SkillResult for valid input
# PASS  run() returns SkillError for missing 'scenario'
# PASS  Chinese language output correct
# ──────────────────────────────────────────────────
# 4 passed in 0.38s

Load the Skill into a live Agent with hot-reload

Start the Agent in dev mode, then invoke your Skill via the CLI REPL or the simulator UI.

bash

# Terminal 1 — start the Agent in watch mode
xr agent start --watch

# Terminal 2 — invoke your Skill directly
xr skill invoke greeting_generator \
  --scenario "lab visitor welcome" \
  --language en

# Output:
# { "message": "Hello! I'm your robot assistant.
#   Scenario: lab visitor welcome. How can I help?" }

Common Pitfalls

⛔ Raising raw exceptions

Never raise ValueError(...) from inside run(). The runtime can't route unhandled exceptions to a fallback Skill. Always return a SkillError instead.

⛔ Hardcoding secrets

Never embed API keys in skill.py. Use context.config("MY_SECRET") which reads from the sandboxed environment at runtime, never from the file itself.

⛔ Blocking I/O in the main thread

Long-running HTTP calls will time out the planner. Either return quickly with a PENDING status or use context.run_async() to schedule background work.

⛔ Missing outputs in manifest

If the planner can't infer what your Skill returns, it can't chain it with other Skills. Always declare every output field in SKILL.md, even if optional.

🚀 Next step: Once your Skill passes all tests, continue to Tutorial 05 to learn how to send motion commands directly to the robot — where safety validation becomes critical.

Robot Control Skill

Develop a skill that directly controls robot motion, learn motion command encoding and safety validation.

90 min Robotics

Data Collection & Processing Skill

Create custom skills for robot data collection, cleaning, and format conversion.

90 min Data Processing

Tool Calling & Integration

Integrate external APIs, tools, and services to extend skill capabilities with third-party functionality.

60 min Integration

Testing, Debugging & Publishing

Write unit tests, debug common issues, and publish your Skill to the Agent marketplace.

45 min DevOps

🛠️

Practice Projects

Reinforce your knowledge with hands-on projects, choose by difficulty level

👋

Welcome Bot

Develop a skill that generates custom welcome messages based on different scenarios. Learn basic parameter configuration and text generation.

Beginner

📷

Object Recognition Skill

Integrate a pre-trained vision model to identify objects in images from the robot's camera.

Beginner

🧭

Navigation Planning Skill

Develop path planning and obstacle avoidance based on environment maps, enabling autonomous navigation to goal positions.

Intermediate

🗣️

Voice Interaction Skill

Integrate speech recognition and synthesis to enable natural voice conversations with robots.

Intermediate

📊

Data Visualization Skill

Create a skill for real-time visualization of robot sensor data to aid debugging and monitoring.

Beginner

🧪

Experiment Automation Skill

Automate robot training experiments, track key metrics, and automatically generate experiment reports.

Intermediate

🔌

Hardware Driver Skill

Develop driver skills for new grippers or sensors, enabling communication with the Agent framework.

Advanced

🤝

Multi-Agent Collaboration Skill

Develop skills enabling collaboration and communication between multiple Agents for multi-robot coordinated tasks.

Advanced

💎

Reward Rules

Earn free tokens for robot development upon completing projects

New Developer	100 Tokens Complete 1 beginner project and pass code review
Skilled Developer	300 Tokens Complete 2 beginner + 1 intermediate projects
Advanced Developer	600 Tokens Complete all tutorials + 2 intermediate + 1 advanced projects
Core Contributor	1000 Tokens Complete all projects, your Skill is widely adopted by the community

💡 Token Usage: Free tokens can be used for cloud robot simulation, model fine-tuning, and data storage on XRollout, helping you accelerate robot development without payment barriers.

❓

Frequently Asked Questions

Q: Do I need to pay for this program?

A: It's completely free! All tutorials and project resources are open, and you earn free token rewards after completing projects.

Q: What prerequisites do I need to participate?

A: Basic Python programming is required. Familiarity with AI and robotics concepts helps, but our tutorials start from scratch - beginners are welcome!

Q: Do earned tokens have an expiration date?

A: Tokens are valid for one year, which is more than enough for completing multiple robot development projects.

Q: How do I submit completed projects?

A: After registering an XRollout account, submit your project link through the developer dashboard. We review within 1-3 business days and issue tokens.

Ready to start your Agent AI development journey?

Join us to learn modern Agent AI skill development and get free tokens to accelerate your robot research.