From abe516f73900dbd3fa5080842fe81353a82606a1 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 10:32:25 +0000
Subject: [PATCH] feat: add uwf skill bootstrap subcommand, update BOOTSTRAP.md
 to use it

---
 BOOTSTRAP.md                                  | 11 ++----
 packages/cli-workflow/src/cli.ts              |  8 ++++
 packages/cli-workflow/src/commands/skill.ts   |  3 +-
 .../workflow-util/src/bootstrap-reference.ts  | 39 +++++++++++++++++++
 packages/workflow-util/src/index.ts           |  1 +
 5 files changed, 54 insertions(+), 8 deletions(-)
 create mode 100644 packages/workflow-util/src/bootstrap-reference.ts

diff --git a/BOOTSTRAP.md b/BOOTSTRAP.md
index 5df97c0..84313ae 100644
--- a/BOOTSTRAP.md
+++ b/BOOTSTRAP.md
@@ -90,12 +90,9 @@ uwf skill author     # prints 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
+uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md
 ```
 
 ✅ **Check:** `cat ~/.hermes/skills/devops/uwf/SKILL.md` shows the skill content with triggers `uwf`, `workflow`, `工作流`.
@@ -166,13 +163,13 @@ cat ~/.hermes/skills/devops/uwf/SKILL.md
 Verify the skill is up to date:
 
 ```bash
-diff skills/uwf-skill.md ~/.hermes/skills/devops/uwf/SKILL.md
+uwf skill bootstrap | diff - ~/.hermes/skills/devops/uwf/SKILL.md
 ```
 
-If `diff` produces any output, the local skill is outdated. Re-copy:
+If `diff` produces any output, the local skill is outdated. Update:
 
 ```bash
-cp skills/uwf-skill.md ~/.hermes/skills/devops/uwf/SKILL.md
+uwf skill bootstrap > ~/.hermes/skills/devops/uwf/SKILL.md
 ```
 
 ### Functional Check
diff --git a/packages/cli-workflow/src/cli.ts b/packages/cli-workflow/src/cli.ts
index 05c563d..c6f14d4 100755
--- a/packages/cli-workflow/src/cli.ts
+++ b/packages/cli-workflow/src/cli.ts
@@ -19,6 +19,7 @@ import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
 import {
   cmdSkillAdapter,
   cmdSkillAuthor,
+  cmdSkillBootstrap,
   cmdSkillDeveloper,
   cmdSkillList,
   cmdSkillUser,
@@ -516,6 +517,13 @@ skill
     console.log(cmdSkillUser());
   });
 
+skill
+  .command("bootstrap")
+  .description("Print the bootstrap skill YAML for Hermes agents")
+  .action(() => {
+    console.log(cmdSkillBootstrap());
+  });
+
 skill
   .command("list")
   .description("List all available skill names")
diff --git a/packages/cli-workflow/src/commands/skill.ts b/packages/cli-workflow/src/commands/skill.ts
index ab540fe..5e53485 100644
--- a/packages/cli-workflow/src/commands/skill.ts
+++ b/packages/cli-workflow/src/commands/skill.ts
@@ -1,11 +1,12 @@
 export {
+  generateBootstrapReference as cmdSkillBootstrap,
   generateAdapterReference as cmdSkillAdapter,
   generateAuthorReference as cmdSkillAuthor,
   generateDeveloperReference as cmdSkillDeveloper,
   generateUserReference as cmdSkillUser,
 } from "@uncaged/workflow-util";
 
-const SKILL_NAMES = ["user", "author", "developer", "adapter"] as const;
+const SKILL_NAMES = ["user", "author", "developer", "adapter", "bootstrap"] as const;
 
 export function cmdSkillList(): ReadonlyArray<string> {
   return [...SKILL_NAMES];
diff --git a/packages/workflow-util/src/bootstrap-reference.ts b/packages/workflow-util/src/bootstrap-reference.ts
new file mode 100644
index 0000000..4ec9d4e
--- /dev/null
+++ b/packages/workflow-util/src/bootstrap-reference.ts
@@ -0,0 +1,39 @@
+export function generateBootstrapReference(): string {
+  return `---
+name: uwf
+description: "Uncaged Workflow (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。"
+tags: [workflow, uwf, uncaged]
+triggers:
+  - uwf
+  - workflow
+  - 工作流
+---
+
+# uwf (Uncaged Workflow)
+
+YAML 状态机工作流引擎。当用户提到「workflow」「工作流」时，指的是 **uwf workflow**（YAML 定义的状态机），不是 Hermes skill。用 \`uwf\` CLI 操作，不要混淆。
+
+## 首次使用
+
+运行以下命令获取完整用法：
+
+\`\`\`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）。
+`;
+}
diff --git a/packages/workflow-util/src/index.ts b/packages/workflow-util/src/index.ts
index 6711b61..6eac6ce 100644
--- a/packages/workflow-util/src/index.ts
+++ b/packages/workflow-util/src/index.ts
@@ -1,4 +1,5 @@
 export { generateActorReference } from "./actor-reference.js";
+export { generateBootstrapReference } from "./bootstrap-reference.js";
 export { generateAdapterReference } from "./adapter-reference.js";
 export { generateArchitectureReference } from "./architecture-reference.js";
 export { generateAuthorReference } from "./author-reference.js";