From fb72550eea8cf38016b5134b7fdbbaf619971d76 Mon Sep 17 00:00:00 2001
From: lyn <lyn@mt.hangman-lab.top>
Date: Fri, 17 Apr 2026 13:42:55 +0000
Subject: [PATCH] add workflows: fix-skills, improve-skills, create-skills

---
 claw-skills/SKILL.md                    | 45 +++++++++++++++++++-
 claw-skills/workflows/create-skills.md  | 55 +++++++++++++++++++++++++
 claw-skills/workflows/fix-skills.md     | 46 +++++++++++++++++++++
 claw-skills/workflows/improve-skills.md | 49 ++++++++++++++++++++++
 4 files changed, 194 insertions(+), 1 deletion(-)
 create mode 100644 claw-skills/workflows/create-skills.md
 create mode 100644 claw-skills/workflows/fix-skills.md
 create mode 100644 claw-skills/workflows/improve-skills.md

diff --git a/claw-skills/SKILL.md b/claw-skills/SKILL.md
index 1944f13..79f3340 100644
--- a/claw-skills/SKILL.md
+++ b/claw-skills/SKILL.md
@@ -1,3 +1,46 @@
 # claw-skills
 
-_placeholder skill_
+ClawSkills 管理和协作套件，提供 scripts 和 workflows 来规范 skill 的使用和改进流程。
+
+## Scripts
+
+### update-skills
+
+Pull latest ClawSkills from git-hangman-lab, then run learn.sh to install/update skills to `{AGENT_WORKSPACE}/skills`.
+
+```bash
+claw-skills/scripts/update-skills
+```
+
+### promote-improvements
+
+Create and force-push a branch named after the agent (via `ego-mgr get name`) from `{AGENT_WORKSPACE}`.
+
+```bash
+claw-skills/scripts/promote-improvements
+```
+
+## Workflows
+
+### fix-skills
+
+如果使用某个 skill 或其脚本没有达到预期效果，或脚本报错：
+
+> **不要轻易使用 workaround。**
+> 参考 `{baseDir}/workflows/fix-skills.md`，按该流程定位根因并修复。
+
+### improve-skills
+
+如果使用 skill 的过程中发现现有 skill 或 workflow 存在以下问题：
+
+- 有误导或歧义
+- 没有覆盖到你的使用情景
+- 效果不理想
+
+> 参考 `{baseDir}/workflows/improve-skills.md` 进行改进。
+
+### create-skills
+
+如果工作过程中发现某些模式或流程可以显著提高效率，但目前没有 skill 覆盖：
+
+> 参考 `{baseDir}/workflows/create-skills.md` 创建新的 skill。
diff --git a/claw-skills/workflows/create-skills.md b/claw-skills/workflows/create-skills.md
new file mode 100644
index 0000000..e1c5b5e
--- /dev/null
+++ b/claw-skills/workflows/create-skills.md
@@ -0,0 +1,55 @@
+# create-skills
+
+当工作过程中发现某些模式或流程可以显著提高效率，但目前没有 skill 覆盖时使用。
+
+## 原则
+
+不是所有重复操作都需要变成 skill。先问：这个模式是否通用到值得抽象？
+
+## 流程
+
+### 1. 识别模式
+
+- 记录重复出现的操作序列
+- 分析：每次都在做类似的什么事情？
+- 评估：这个操作是否有通用性，还是只是当前任务的特例？
+
+### 2. 评估是否值得做成 skill
+
+- **值得做的特征**：
+  - 同一个操作在不同 agent/workspace 中重复出现
+  - 操作步骤固定，结果可预期
+  - 涉及外部系统调用（git、keycloak、文件操作等）
+- **不值得做的特征**：
+  - 一次性任务
+  - 步骤不固定，依赖上下文判断
+  - 纯对话/分析类工作
+
+### 3. 设计 skill
+
+- **名称**：`{action}-{target}`（如 `git-clone-repo`、`keycloak-create-user`）
+- **SKILL.md 内容**：
+  - 描述：这个 skill 做什么
+  - 使用场景：什么时候用
+  - 脚本列表：所有相关脚本及其调用方式
+- **脚本**：
+  - 放在 `scripts/` 下
+  - 每个脚本单一职责
+  - 提供 `--help` 或 `-h` 支持
+
+### 4. 实现
+
+- 编写脚本，测试通过
+- 编写 SKILL.md
+- 本地验证
+
+### 5. 提交
+
+- 按 promote-improvements 流程提交到自己的分支
+- commit message 包含：skill 名称、功能描述、使用示例
+- 通知 hang，说明新增 skill 的用途
+
+### 6. 上线
+
+- hang merge 后，skill 进入 ClawSkills 正式列表
+- 其他 agent 通过 learn.sh 自动获取
diff --git a/claw-skills/workflows/fix-skills.md b/claw-skills/workflows/fix-skills.md
new file mode 100644
index 0000000..9e7a94c
--- /dev/null
+++ b/claw-skills/workflows/fix-skills.md
@@ -0,0 +1,46 @@
+# fix-skills
+
+当 skill 或脚本未达到预期效果，或脚本报错时使用。
+
+## 原则
+
+**不要轻易使用 workaround。** 先定位根因，再决定修复方式。
+
+## 流程
+
+### 1. 收集信息
+
+- 记录触发场景：怎么调用的，期望什么结果，实际什么结果
+- 记录错误信息：完整输出（含 stack trace 或脚本调试输出）
+- 确认环境：模型版本、节点、skill 版本（git log 有帮助）
+
+### 2. 分析根因
+
+按以下顺序排查：
+
+1. **输入/参数是否正确** — 传给脚本或工具的参数是否符合预期？
+2. **依赖是否满足** — 所需 secret、token、配置文件是否存在？
+3. **脚本逻辑是否有 bug** — 读源码，必要时加 `set -x` 调试
+4. **skill 设计是否有缺陷** — 逻辑本身是否覆盖了这个场景？
+
+### 3. 定位到文件
+
+- 确认问题出在哪个文件的哪一行
+- 如果是 skill 本身的问题 → 进入 [improve-skills](./improve-skills.md) 流程
+- 如果是脚本执行环境问题 → 记录在 memory/ 并提给 hang
+
+### 4. 修复
+
+- 在本地测试修复方案
+- 如果需要修改 skill 文件 → 按 improve-skills 流程提交 PR 或直接 push 到分支
+- 避免引入新的 side effect
+
+### 5. 验证
+
+- 复现原场景，确认问题已解决
+- 记录修复内容到 memory/YYYY-MM-DD.md
+
+### 6. 上报（如需要）
+
+- 如果问题需要 hang 或其他 agent 介入 → 在 report channel 记录
+- 包含：场景、期望/实际结果、根因、修复方案
diff --git a/claw-skills/workflows/improve-skills.md b/claw-skills/workflows/improve-skills.md
new file mode 100644
index 0000000..1562946
--- /dev/null
+++ b/claw-skills/workflows/improve-skills.md
@@ -0,0 +1,49 @@
+# improve-skills
+
+当发现现有 skill 或 workflow 存在以下问题时使用：
+
+- 有误导或歧义
+- 没有覆盖到你的使用情景
+- 效果不理想
+
+## 原则
+
+改进比 work-around 更好。发现问题时及时修正，避免后续其他人踩同样的坑。
+
+## 流程
+
+### 1. 识别问题
+
+- 记录哪个 skill 的哪个部分有问题
+- 具体描述：哪里误导、哪里缺失、哪里效果差
+- 记录触发场景：什么情况下发现这个问题
+
+### 2. 评估影响范围
+
+- 这个问题会影响多少人？
+- 是 skill 设计问题还是描述/文档问题？
+- 修复复杂度如何？
+
+### 3. 确定改进方案
+
+- **文档问题** → 改 SKILL.md 或相关描述
+- **逻辑缺陷** → 修改脚本或 skill 逻辑
+- **覆盖缺失** → 新增流程或脚本
+- **流程不顺** → 重新设计 workflow
+
+### 4. 执行改进
+
+- 在本地或分支上修改
+- 更新 SKILL.md（如果改了描述）
+- 如果改动较大，先在本地测试
+
+### 5. 提交
+
+- 按 promote-improvements 流程提交到自己的分支
+- commit message 说明改进内容
+- 附上问题描述和解决思路（便于 hang review）
+
+### 6. 通知 hang
+
+- 完成后告知 hang，说明改了什么、为什么改
+- 让 hang 决定是 merge 还是继续调整