From b4919aa921da0cea488e142b94fe500e23e28919 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= <xiaomooo@shazhou.work>
Date: Thu, 28 May 2026 09:42:28 +0000
Subject: [PATCH] docs: add BOOTSTRAP.md and uwf skill for agent onboarding

---
 BOOTSTRAP.md        | 113 ++++++++++++++++++++++++++++++++++++++++++++
 skills/uwf-skill.md |  36 ++++++++++++++
 2 files changed, 149 insertions(+)
 create mode 100644 BOOTSTRAP.md
 create mode 100644 skills/uwf-skill.md

diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md
new file mode 100644
index 0000000..04ad863
--- /dev/null
+++ b/BOOTSTRAP.md
@@ -0,0 +1,113 @@
+# UWF Bootstrap Guide
+
+This guide helps any AI agent set up `uwf` (Uncaged Workflow) from scratch.
+
+## Prerequisites
+
+- **bun** — `uwf` is built with bun. Install: `curl -fsSL https://bun.sh/install | bash`
+- **Network access** — to install npm packages
+
+## 1. Install uwf CLI
+
+```bash
+bun install -g @uncaged/cli-workflow
+```
+
+Verify:
+
+```bash
+uwf --version
+```
+
+## 2. Install Agent Adapter
+
+Install the adapter that matches your agent runtime. Pick **one**:
+
+| Agent | Package | Binary |
+|-------|---------|--------|
+| Hermes | `@uncaged/workflow-agent-hermes` | `uwf-hermes` |
+
+```bash
+# Example: Hermes agent
+bun install -g @uncaged/workflow-agent-hermes
+```
+
+## 3. Setup
+
+Run the interactive wizard:
+
+```bash
+uwf setup
+```
+
+Or configure non-interactively:
+
+```bash
+uwf setup \
+  --provider <name> \
+  --base-url <url> \
+  --api-key <key> \
+  --model <model-name> \
+  --agent hermes
+```
+
+This creates `~/.uncaged/workflow/config.yaml` with your provider, model, and default agent.
+
+### Config Structure
+
+```yaml
+providers:
+  my-provider:
+    baseUrl: https://api.example.com/v1
+    apiKey: sk-xxx
+models:
+  default:
+    provider: my-provider
+    name: my-model
+agents:
+  hermes:
+    command: uwf-hermes
+    args: []
+defaultAgent: hermes
+defaultModel: default
+```
+
+## 4. Verify Installation
+
+```bash
+# List workflows (should return empty or existing ones)
+uwf workflow list
+
+# Check built-in help
+uwf skill user     # usage guide
+uwf skill author   # workflow authoring guide
+```
+
+## 5. Add the uwf Skill
+
+Copy the skill file from this repo into your agent's skill library:
+
+```bash
+# For Hermes agents with skills at ~/.hermes/skills/
+mkdir -p ~/.hermes/skills/devops/uwf
+cp skills/uwf-skill.md ~/.hermes/skills/devops/uwf/SKILL.md
+```
+
+The skill teaches the agent to use `uwf skill user` and `uwf skill author` for detailed reference, keeping the skill itself minimal.
+
+## 6. Quick Smoke Test
+
+```bash
+# Register an example workflow
+uwf workflow add examples/analyze-topic.yaml
+
+# Start a thread
+uwf thread start analyze-topic -p "Analyze the concept of technical debt"
+
+# Execute it (runs one moderator → agent → extract cycle)
+uwf thread exec <thread-id>
+```
+
+## Done
+
+The agent now has `uwf` + agent adapter installed, configured, and a skill to guide future usage. For workflow authoring details, run `uwf skill author`.
diff --git a/skills/uwf-skill.md b/skills/uwf-skill.md
new file mode 100644
index 0000000..2c7d88f
--- /dev/null
+++ b/skills/uwf-skill.md
@@ -0,0 +1,36 @@
+---
+name: uwf
+description: "Uncaged Workflow (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。"
+tags: [workflow, uwf, uncaged]
+triggers:
+  - uwf
+  - workflow
+  - 工作流
+---
+
+# uwf (Uncaged Workflow)
+
+YAML 状态机工作流引擎。
+
+## 首次使用
+
+运行以下命令获取完整用法：
+
+```bash
+uwf skill user    # 用户使用手册（CLI 命令、thread 生命周期）
+uwf skill author  # workflow 编写指南（role 定义、graph 路由、schema）
+```
+
+## 快速参考
+
+```bash
+uwf workflow list                          # 查看已注册 workflow
+uwf workflow add <file.yaml>               # 注册 workflow
+uwf thread start <workflow> -p "prompt"    # 创建 thread
+uwf thread exec <thread-id> -c 10          # 执行最多 10 步
+uwf thread list                            # 查看所有 thread
+```
+
+## 示例 workflow
+
+参考项目 `examples/` 目录下的 YAML 文件（analyze-topic、debate、solve-issue）。