跳至主要内容
版本：1.0.0

建立第一個 Agent

先執行範例 hello-world-agent，再修改訊息、打包成自己的 Agent。

先認識三個名詞：

名詞用途這次的範例
Agent執行任務的代理人，透過 ZIP 套件匯入平台hello-world-agent
SkillAgent 可使用的技能，描述做法並可附上腳本hello-world：執行腳本，印出成功訊息
Task指定這次要做什麼、怎樣才算完成的工單呼叫 Skill，把訊息存成檔案並檢查內容

完成的標準： Task Run 為 done，hello-world-result.txt 含成功訊息。

開始前​

確認已完成安裝，並準備 Administrator 帳號。

從 IndustrialClaw 儲存庫下載：

檔案用途
hello-world-agent.zipAgent。唯一的 hello-world Skill 會執行一支腳本、印出一行文字。
hello-world-task.mdTask。呼叫這個 Skill，並檢查結果檔是否寫入成功訊息。

Step 1 — 先跑一次範例​

1.1 匯入範例 Agent​

依照匯入 Agent匯入 hello-world-agent.zip（不用解壓縮）。掃描結果見掃描結果。

1.2 執行範例並確認結果​

依照建立 Task填入：

欄位值
Agenthello-world-agent（若有尾碼，選新的那個）
Task Markdown下載的 hello-world-task.md
Material ZIP留空

啟動執行後，在開啟一筆執行確認狀態為 done，hello-world-result.txt 內容為：

Industrial Claw skill executed successfully.

結果不符時見執行失敗。

Step 2 — 了解 Agent 套件與 Task​

建立 Agent 的三個階段​

自行建立 Agent 依這三個階段進行。Step 1 已完成「部署執行」，以下看前兩個階段：Agent 履歷與檔案。

  1. 1Object & Skills
    • Agent 履歷
    • 準備 Skill
    • 打包成 IC 格式的 ZIP
  2. 2Task
    • 前置條件
    • 準備 Material
    • 輸入／輸出
    • Steps
    • 錯誤處理
  3. 3Deploy & Run
    • 匯入 Agent
    • 建立 Task
    • 啟動執行
    • 驗證結果

Agent 履歷​

先用 Agent 履歷看整體，再對照下面各檔案。自行建立 Agent 時，先填履歷，再照著建立 agent.zip 與 Task.md，每一格對應檔案中的一個位置。

項目內容寫進哪裡
Namehello-world-agentZIP 檔名
Object驗證平台能呼叫已安裝的 Skill 並執行它的腳本Task 的 ## Goal、TOOLS.md 的 ## Purpose
Skillshello-world：執行 hello.sh，印出一行成功訊息；無額外套件skills/hello-world/SKILL.md、TOOLS.md 的 ## Skills；套件或 runtime 也寫在 SKILL.md
TaskHello World Skill Execution TestTask 的 H1 標題
 Prerequisite無，不需要輸入資料第一個 Step：execute 執行檢查，check 判斷是否通過
輸入資料：建立 Task 時以 Material ZIP 上傳，解開到 materials/
 Input / Output輸入：
prompt：要模型用 hello-world Skill 執行指令
execute：bash skills/hello-world/scripts/hello.sh > hello-world-result.txt
輸出：hello-world-result.txt		輸入：Step 的 prompt、execute
輸出：## Expected Outputs
 Step1 個 Step：Execute hello world skill
跑 1 輪		## Step N 的 name
輪數：## General Setting 的 cycle
 Error Handling檢查檔案內有成功訊息；失敗就停止，不重試Step 的 check、on failure
重試次數：## General Setting 的 retry
 Verify檔案存在，且內有成功訊息## Final Verification

套件內容​

解開 hello-world-agent.zip，內含三個檔案：

檔案用途
TOOLS.md列出 Agent 有哪些 Skill
skills/hello-world/SKILL.md告訴模型何時使用 Skill、執行什麼指令、怎樣算成功
skills/hello-world/scripts/hello.sh實際執行工作的腳本；這次只印出一行文字
hello-world-agent.zip
├── TOOLS.md
└── skills/
    └── hello-world/
        ├── SKILL.md
        └── scripts/
            └── hello.sh

TOOLS.md 與 skills/ 都直接放在壓縮檔最外層，不須包一層資料夾。

規則見建立 Agent 套件。

TOOLS.md​

查看 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​

查看 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​

查看 scripts/hello.sh 完整內容
#!/usr/bin/env bash
set -euo pipefail

echo "Industrial Claw skill executed successfully."

Task：hello-world-task.md​

每個區塊與 Step 欄位的規則見 Task.md 的格式。 Task 是另外上傳的工單，不放進 Agent ZIP。

查看 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 — 做一個小修改​

把成功訊息改成 My first Agent ran successfully.。只改訊息與 ZIP 名稱，Skill 名稱與腳本路徑不變。

3.1 修改腳本與 Skill 說明​

解開的資料夾改名為 my-first-agent，將 skills/hello-world/scripts/hello.sh 改成：

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

echo "My first Agent ran successfully."

skills/hello-world/SKILL.md 的 Expected Result 也改成新訊息。TOOLS.md 不變。

3.2 修改 Task 的驗證​

複製 hello-world-task.md 為 my-first-task.md，把所有 Industrial Claw skill executed successfully. 換成 My first Agent ran successfully.，包含 Step 的 check 與 Final Verification。

hello-world-result.txt 與 execute 不變。漏改任一處，驗證就會失敗。

3.3 打包成新的 Agent​

在 my-first-agent 資料夾內執行：

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

也可以用壓縮工具打包。TOOLS.md 與 skills/ 須在 ZIP 最外層；Task 檔不放進 ZIP。

3.4 匯入並確認新訊息​

依序匯入 Agent（my-first-agent.zip）、建立 Task（my-first-agent、my-first-task.md）、啟動執行。

在開啟一筆執行確認狀態為 done，hello-world-result.txt 內容為：

My first Agent ran successfully.

換成你的工作​

例如 aoi-review-assistant：輸入改為檢測結果、Log 或報表，腳本改為分析或查詢腳本，產出改為覆核報告。命名規則見常見的匯入問題。

履歷模板
項目內容備註
NameZIP 檔名：小寫英文、數字與 -
Object這個 Agent 要達成什麼
Skills每個 Skill 的名稱、做什麼、執行哪個腳本；需要的套件
TaskTask 標題
Prerequisite執行前要確認的事；需要的輸入資料（以 Material ZIP 上傳）
Input / Output每個 Step 的 prompt 與 execute 指令；產出的檔名
Step有幾個 Step、各叫什麼；跑幾輪
Error Handling每個 Step 怎麼檢查；失敗時停止或繼續；重試幾次
Verify全部 Step 跑完後，怎樣才算成功
Agent 結構
<agent-name>.zip
├── TOOLS.md
└── skills/
    ├── <skill-name>/
    │   ├── scripts/
    │   ├── references/
    │   └── SKILL.md
    └── <每個 Skill 一個資料夾>/
項目規則
<agent-name>.zipZIP 檔名就是 Agent 名稱；名稱已被使用時會自動加上尾碼。根目錄除了 TOOLS.md 與 skills/ 不放別的
TOOLS.md在 ## Skills 底下每個 Skill 一行，開頭是該 Skill 的目錄名，必須與 skills/ 底下完全一致。建議格式：- [name](skills/name/SKILL.md)
SKILL.md每個 Skill 目錄都要有一份，而且不能是空的
大小20 MB 以內
模型Skill 需小模型驗證過，可以正常運行

TOOLS.md

# <Agent 標題>

## Skills

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

## Purpose

<這個 Agent 的用途>

SKILL.md

# <Skill 標題>

## Description

<這個 Skill 做什麼、什麼時候該用>

## Behavior

Run the bundled script:

```bash
<完整指令>
```

<會做與不會做的事>

## Expected Result

<成功時的輸出>

## Completion Criteria

<怎樣才算成功>
Task.md 格式
---
schema_version: "1.0"
---

# <Task 標題>
version:
author:
date:

## Goal
<這個 Task 的目的>

## General Setting
- cycle: <整數>
- retry: <整數>

## Expected Outputs
- `outputs/<檔名>`

## Execution Procedure

## Step 1
- name: <Step 名稱，最多 64 字元>
- prompt: <給 Agent 的指示>
- on failure: stop | continue
- execute: `<完整指令；選填，但沒有 execute 的 Step 只能對話>`
- check: `<檢查指令；需搭配 execute>`
- note: <額外規則>

## Final Verification
- execute: `<完整指令>`
- success condition: <怎樣才算成功>
項目規則
cycle / retrycycle 失敗時會重跑整個流程；retry 全部失敗時只把該 cycle 記為失敗，下一個 cycle 仍會執行。
Expected Outputs選填且由 Task 自己產生的 workspace 相對路徑。只寫檔名會解析到 outputs/ 底下，這裡與指令裡的同名檔案一起改寫；要放別處就自己寫出路徑。平台只檢查；不建立、不複製、不搬移、不發布。
模型Task 需小模型驗證過可以執行。

從範圍小、容易驗收的工作開始；不該做的事（例如「不變更設備參數」）寫進 Step 的 note。

需要額外套件、GPU 或服務時，見需要額外執行環境時。

下一步​