Build Your First Agent

Run the hello-world-agent example, then change its message and package your own Agent.

Three terms to know:

Term	Purpose	This example
Agent	Runs Tasks and is imported through a ZIP package	hello-world-agent
Skill	A capability with instructions and, optionally, scripts	hello-world: runs a script that prints a success message
Task	A work order defining what to do and how to verify completion	Calls the Skill, saves its message, and checks the file

You are done when: the Task Run is done and hello-world-result.txt holds the success message.

Before you begin

Complete the installation and have an Administrator account.

Download from the IndustrialClaw repository:

File	What it is
hello-world-agent.zip	The Agent. Its one hello-world Skill runs a script that prints a single line.
hello-world-task.md	The Task. It invokes the Skill and checks that the result file holds the success message.

Step 1 — Run the example

1.1 Import the example Agent

Follow Import an Agent with hello-world-agent.zip (no need to extract it). For scan findings, see Scan results.

1.2 Run the example and check its result

Follow Create a Task with these values:

Field	Value
Agent	hello-world-agent (if it has a suffix, choose the new one)
Task Markdown	The downloaded hello-world-task.md
Material ZIP	Leave empty

Start a run, then in Open a run confirm the status is done and hello-world-result.txt contains:

Industrial Claw skill executed successfully.

If the result does not match, see Failed runs.

Step 2 — Understand the Agent package and Task

Three stages of building an Agent

Build your own Agent in these three stages. Step 1 already covered Deploy & Run; the rest of this step covers the first two stages: the Agent resume and the files.

1. 1Object & Skills
   • Agent resume
   • Prepare Skills
   • ZIP in IC format
2. 2Task
   • Prerequisites
   • Prepare materials
   • Input / output
   • Steps
   • Error handling
3. 3Deploy & Run
   • Import an Agent
   • Create a Task
   • Start a run
   • Verify

Agent resume

Start with the Agent resume for an overview, then compare it with each file below. When you build your own Agent, fill in the resume first, then create agent.zip and Task.md from it; each row maps to one place in those files.

Item	Content	Goes into
Name	hello-world-agent	The ZIP filename
Object	Verify that the platform can invoke an installed Skill and run its script	The Task's ## Goal, TOOLS.md's ## Purpose
Skills	hello-world: runs hello.sh, which prints one success line; no extra packages	skills/hello-world/SKILL.md, TOOLS.md's ## Skills; packages or a runtime also go in SKILL.md
Task	Hello World Skill Execution Test	The Task's H1 title
Prerequisite	None; no input data	The first Step: execute runs the check, check decides whether it passed Input data: uploaded as a Material ZIP when creating the Task, extracted into materials/
Input / Output	Input: prompt: tells the model to run the command with the hello-world Skill execute: bash skills/hello-world/scripts/hello.sh > hello-world-result.txt Output: hello-world-result.txt	Input: the Step's prompt and execute Output: ## Expected Outputs
Step	1 Step: Execute hello world skill Run 1 round	The name of each ## Step N Rounds: cycle in ## General Setting
Error Handling	Check the file holds the success message; stop on failure, no retry	The Step's check and on failure Retries: retry in ## General Setting
Verify	The file exists and holds the success message	## Final Verification

Package contents

Extract hello-world-agent.zip. It holds three files:

File	Purpose
TOOLS.md	Lists the Agent's Skills
skills/hello-world/SKILL.md	Tells the model when to use the Skill, which command to run, and what counts as success
skills/hello-world/scripts/hello.sh	Does the actual work; this script prints one line

hello-world-agent.zip
├── TOOLS.md
└── skills/
    └── hello-world/
        ├── SKILL.md
        └── scripts/
            └── hello.sh

TOOLS.md and skills/ sit directly at the archive root, with no enclosing folder.

For the rules, see Build an Agent package.

TOOLS.md

View the complete TOOLS.md

# Industrial Claw Agent Tools

## Skills

- [hello-world](skills/hello-world/SKILL.md)

## Purpose

Minimal Industrial Claw sub-agent used to validate Skill invocation and Task execution.

SKILL.md

View the complete SKILL.md

# Hello World

## Description

A minimal Skill used to verify that Industrial Claw can invoke an installed Skill and execute its script.

Use this Skill when a Task requests a basic execution test or asks to confirm that Skill invocation is working.

## Behavior

Run the bundled script:

```bash
bash skills/hello-world/scripts/hello.sh
```

The script prints a single success message and does not modify system configuration or create background processes.

## Expected Result

```text
Industrial Claw skill executed successfully.
```

## Completion Criteria

The Skill is successful when the script exits with code 0 and prints the expected success message.

scripts/hello.sh

View the complete scripts/hello.sh

#!/usr/bin/env bash
set -euo pipefail

echo "Industrial Claw skill executed successfully."

Task: hello-world-task.md

For the rules of every section and Step field, see Task.md format. The Task is uploaded separately and does not belong in the Agent ZIP.

View the complete hello-world-task.md

---
schema_version: "1.0"
---

# Hello World Skill Execution Test

version: 1.0
author: Judy
date: 2026-08-20

## Goal

Verify that Industrial Claw can invoke the installed hello-world Skill and execute its bundled script successfully.

## General Setting

- cycle: 1
- retry: 0

## Expected Outputs

- `hello-world-result.txt`

## Execution Procedure

## Step 1

- name: Execute hello world skill
- prompt: Execute this step using the required hello-world Skill. Run the exact execute command. Do not only explain or summarize. The step is complete only after the command has actually executed.
- execute: `bash skills/hello-world/scripts/hello.sh > hello-world-result.txt`
- check: `test -s hello-world-result.txt && grep -q "Industrial Claw skill executed successfully." hello-world-result.txt`
- on failure: stop
- note: Do not modify system settings. Only create hello-world-result.txt in the current Task workspace.

## Final Verification

- execute: `test -s hello-world-result.txt && grep -q "Industrial Claw skill executed successfully." hello-world-result.txt`
- success condition: hello-world-result.txt exists and contains the expected Industrial Claw skill execution success message.

Step 3 — Make a small change

Change the success message to My first Agent ran successfully.. Change only the message and the ZIP name; the Skill name and script path stay the same.

3.1 Edit the script and Skill instructions

Rename the extracted folder my-first-agent and change skills/hello-world/scripts/hello.sh to:

#!/usr/bin/env bash
set -euo pipefail

echo "My first Agent ran successfully."

Change Expected Result in skills/hello-world/SKILL.md to the new message too. TOOLS.md stays the same.

3.2 Update the Task checks

Copy hello-world-task.md to my-first-task.md and replace every Industrial Claw skill executed successfully. with My first Agent ran successfully., including the Step's check and Final Verification.

hello-world-result.txt and execute stay the same. Missing any occurrence makes verification fail.

3.3 Package the new Agent

Inside the my-first-agent folder, run:

zip -r ../my-first-agent.zip TOOLS.md skills

An archive tool works too. TOOLS.md and skills/ must be at the ZIP root; leave the Task file out.

3.4 Import and verify the new message

Import an Agent (my-first-agent.zip), Create a Task (my-first-agent, my-first-task.md), and Start a run.

In Open a run, confirm the status is done and hello-world-result.txt contains:

My first Agent ran successfully.

Adapt it to your job

For example, for aoi-review-assistant: the input becomes inspection results, logs, or reports; the script, your analysis or lookup script; the output, a review report. For naming rules, see Common import problems.

Resume template

Item	Content	Note
Name		ZIP filename: lowercase letters, digits, and -
Object		What this Agent achieves
Skills		Each Skill's name, what it does, which script it runs; packages it needs
Task		Task title
Prerequisite		What must be true before the run; input data uploaded as a Material ZIP
Input / Output		Each Step's prompt and execute command; output filenames
Step		How many Steps and their names; how many rounds
Error Handling		How each Step is checked; stop or continue on failure; retry count
Verify		What counts as success after every Step has run

Agent structure

<agent-name>.zip
├── TOOLS.md
└── skills/
    ├── <skill-name>/
    │   ├── scripts/
    │   ├── references/
    │   └── SKILL.md
    └── <one directory per Skill>/

Item	Rule
<agent-name>.zip	The ZIP filename becomes the Agent name; one already in use gets a suffix. The root holds nothing but TOOLS.md and skills/.
TOOLS.md	One bullet per Skill under ## Skills, each starting with the Skill's directory name, which must match skills/ exactly. Suggested: - [name](skills/name/SKILL.md)
SKILL.md	Every Skill directory needs one, and it may not be empty.
Size	20 MB or smaller.
Model	Skills must be verified to run correctly on a small model.

TOOLS.md

# <Agent title>

## Skills

- [<skill-name>](skills/<skill-name>/SKILL.md)

## Purpose

<what this Agent is for>

SKILL.md

# <Skill title>

## Description

<what the Skill does and when to use it>

## Behavior

Run the bundled script:

```bash
<full command>
```

<what it does and does not do>

## Expected Result

<what the output looks like on success>

## Completion Criteria

<what counts as success>

Task.md format

---
schema_version: "1.0"
---

# <Task Title>
version:
author:
date:

## Goal
<what this Task is for>

## General Setting
- cycle: <integer>
- retry: <integer>

## Expected Outputs
- `outputs/<file-name>`

## Execution Procedure

## Step 1
- name: <step name, max 64 characters>
- prompt: <instruction for the Agent>
- on failure: stop | continue
- execute: `<full command — optional, but a step without one can only talk>`
- check: `<check command; needs an execute>`
- note: <extra rules>

## Final Verification
- execute: `<full command>`
- success condition: <what counts as success>

Item	Rule
cycle / retry	A failed cycle retries the whole procedure. If every retry fails, that cycle is failed and the next cycle still runs.
Expected Outputs	Optional workspace-relative paths created by the Task. A bare file name is resolved under outputs/, here and in every command that names it; write a path of your own to put it elsewhere. The platform only checks them; it never creates, copies, moves, or publishes them.
Model	Tasks must be verified to run on a small model.

Start with a small job that is easy to verify; put what it must not do (such as "never change equipment parameters") in the Step's note.

If the work needs extra packages, a GPU, or services, see When you need an additional runtime.

Next steps

• Split a larger workflow across roles: Agent Roles and Collaboration.
• Review detailed scan rules: Security Scanning Reference.