From 97a7d89debb326d86d50791e87614877292ebd9a Mon Sep 17 00:00:00 2001 From: lyn Date: Fri, 17 Apr 2026 13:44:20 +0000 Subject: [PATCH] rewrite all docs in English --- claw-skills/SKILL.md | 22 +++---- claw-skills/workflows/create-skills.md | 77 +++++++++++++------------ claw-skills/workflows/fix-skills.md | 56 +++++++++--------- claw-skills/workflows/improve-skills.md | 62 ++++++++++---------- 4 files changed, 109 insertions(+), 108 deletions(-) diff --git a/claw-skills/SKILL.md b/claw-skills/SKILL.md index 79f3340..200d44c 100644 --- a/claw-skills/SKILL.md +++ b/claw-skills/SKILL.md @@ -1,6 +1,6 @@ # claw-skills -ClawSkills 管理和协作套件，提供 scripts 和 workflows 来规范 skill 的使用和改进流程。 +ClawSkills management and collaboration suite — scripts and workflows for using and improving skills. ## Scripts @@ -24,23 +24,23 @@ claw-skills/scripts/promote-improvements ### fix-skills -如果使用某个 skill 或其脚本没有达到预期效果，或脚本报错： +When a skill or its scripts fail to produce expected results, or throw errors: -> **不要轻易使用 workaround。** -> 参考 `{baseDir}/workflows/fix-skills.md`，按该流程定位根因并修复。 +> **Do not resort to workarounds lightly.** +> Follow `{baseDir}/workflows/fix-skills.md` — identify the root cause first, then fix properly. ### improve-skills -如果使用 skill 的过程中发现现有 skill 或 workflow 存在以下问题： +When using a skill and you find: -- 有误导或歧义 -- 没有覆盖到你的使用情景 -- 效果不理想 +- Misleading or ambiguous descriptions +- Missing coverage for your use case +- Suboptimal or confusing behavior -> 参考 `{baseDir}/workflows/improve-skills.md` 进行改进。 +> Follow `{baseDir}/workflows/improve-skills.md` to improve it. ### create-skills -如果工作过程中发现某些模式或流程可以显著提高效率，但目前没有 skill 覆盖： +When you notice patterns or workflows that could improve efficiency but have no skill covering them: -> 参考 `{baseDir}/workflows/create-skills.md` 创建新的 skill。 +> Follow `{baseDir}/workflows/create-skills.md` to create a new skill. diff --git a/claw-skills/workflows/create-skills.md b/claw-skills/workflows/create-skills.md index e1c5b5e..7052242 100644 --- a/claw-skills/workflows/create-skills.md +++ b/claw-skills/workflows/create-skills.md @@ -1,55 +1,56 @@ # create-skills -当工作过程中发现某些模式或流程可以显著提高效率，但目前没有 skill 覆盖时使用。 +Used when you notice patterns or workflows that could improve efficiency but have no skill covering them. -## 原则 +## Principle -不是所有重复操作都需要变成 skill。先问：这个模式是否通用到值得抽象？ +Not every repetitive task needs to become a skill. Ask first: is this pattern general enough to warrant abstraction? -## 流程 +## Process -### 1. 识别模式 +### 1. Identify the Pattern -- 记录重复出现的操作序列 -- 分析：每次都在做类似的什么事情？ -- 评估：这个操作是否有通用性，还是只是当前任务的特例？ +- Record the repeating sequence of operations +- Analyze: what are you doing repeatedly across tasks? +- Evaluate: is this operation general-purpose or a one-off特例? -### 2. 评估是否值得做成 skill +### 2. Assess Whether It's Worth Making a Skill -- **值得做的特征**： - - 同一个操作在不同 agent/workspace 中重复出现 - - 操作步骤固定，结果可预期 - - 涉及外部系统调用（git、keycloak、文件操作等） -- **不值得做的特征**： - - 一次性任务 - - 步骤不固定，依赖上下文判断 - - 纯对话/分析类工作 +**Worth doing when:** +- The same operation recurs across different agents/workspaces +- The steps are fixed, results are predictable +- Involves external system calls (git, keycloak, file ops, etc.) -### 3. 设计 skill +**Not worth doing when:** +- One-off task +- Steps vary depending on context +- Purely conversational/analytical work -- **名称**：`{action}-{target}`（如 `git-clone-repo`、`keycloak-create-user`） -- **SKILL.md 内容**： - - 描述：这个 skill 做什么 - - 使用场景：什么时候用 - - 脚本列表：所有相关脚本及其调用方式 -- **脚本**： - - 放在 `scripts/` 下 - - 每个脚本单一职责 - - 提供 `--help` 或 `-h` 支持 +### 3. Design the Skill -### 4. 实现 +- **Name:** `{action}-{target}` (e.g., `git-clone-repo`, `keycloak-create-user`) +- **SKILL.md contents:** + - Description: what this skill does + - Use cases: when to use it + - Scripts: all related scripts and how to call them +- **Scripts:** + - Place under `scripts/` + - Each script has a single responsibility + - Provide `--help` or `-h` support -- 编写脚本，测试通过 -- 编写 SKILL.md -- 本地验证 +### 4. Implement -### 5. 提交 +- Write the scripts, verify they work +- Write the SKILL.md +- Test locally -- 按 promote-improvements 流程提交到自己的分支 -- commit message 包含：skill 名称、功能描述、使用示例 -- 通知 hang，说明新增 skill 的用途 +### 5. Submit -### 6. 上线 +- Follow promote-improvements to push to your branch +- Commit message includes: skill name, what it does, usage example +- Notify hang with the new skill's purpose -- hang merge 后，skill 进入 ClawSkills 正式列表 -- 其他 agent 通过 learn.sh 自动获取 +### 6. Ship + +- hang merges it; skill enters the official ClawSkills list +- Other agents pull it automatically via learn.sh diff --git a/claw-skills/workflows/fix-skills.md b/claw-skills/workflows/fix-skills.md index 9e7a94c..411b097 100644 --- a/claw-skills/workflows/fix-skills.md +++ b/claw-skills/workflows/fix-skills.md @@ -1,46 +1,46 @@ # fix-skills -当 skill 或脚本未达到预期效果，或脚本报错时使用。 +Used when a skill or its scripts fail to produce expected results, or throw errors. -## 原则 +## Principle -**不要轻易使用 workaround。** 先定位根因，再决定修复方式。 +**Do not resort to workarounds lightly.** Identify the root cause first, then fix properly. -## 流程 +## Process -### 1. 收集信息 +### 1. Gather Information -- 记录触发场景：怎么调用的，期望什么结果，实际什么结果 -- 记录错误信息：完整输出（含 stack trace 或脚本调试输出） -- 确认环境：模型版本、节点、skill 版本（git log 有帮助） +- Record the triggering scenario: how it was called, expected result, actual result +- Record the error output in full (stack traces, debug output) +- Confirm the environment: model version, node, skill version (git log helps) -### 2. 分析根因 +### 2. Analyze Root Cause -按以下顺序排查： +Investigate in this order: -1. **输入/参数是否正确** — 传给脚本或工具的参数是否符合预期？ -2. **依赖是否满足** — 所需 secret、token、配置文件是否存在？ -3. **脚本逻辑是否有 bug** — 读源码，必要时加 `set -x` 调试 -4. **skill 设计是否有缺陷** — 逻辑本身是否覆盖了这个场景？ +1. **Are inputs/parameters correct?** — Do they match what the script or tool expects? +2. **Are dependencies satisfied?** — Are required secrets, tokens, config files present? +3. **Is there a bug in the script logic?** — Read the source, add `set -x` if needed +4. **Is there a design flaw in the skill?** — Does the logic actually cover this scenario? -### 3. 定位到文件 +### 3. Pinpoint the File -- 确认问题出在哪个文件的哪一行 -- 如果是 skill 本身的问题 → 进入 [improve-skills](./improve-skills.md) 流程 -- 如果是脚本执行环境问题 → 记录在 memory/ 并提给 hang +- Identify which file and which line the problem is in +- If it's a skill issue → follow the [improve-skills](./improve-skills.md) workflow +- If it's an execution environment issue → document in memory/ and escalate to hang -### 4. 修复 +### 4. Fix -- 在本地测试修复方案 -- 如果需要修改 skill 文件 → 按 improve-skills 流程提交 PR 或直接 push 到分支 -- 避免引入新的 side effect +- Test the fix locally +- If skill files need to be modified → follow improve-skills process to PR or push to a branch +- Avoid introducing new side effects -### 5. 验证 +### 5. Verify -- 复现原场景，确认问题已解决 -- 记录修复内容到 memory/YYYY-MM-DD.md +- Reproduce the original scenario; confirm the issue is resolved +- Log the fix in memory/YYYY-MM-DD.md -### 6. 上报（如需要） +### 6. Escalate if Needed -- 如果问题需要 hang 或其他 agent 介入 → 在 report channel 记录 -- 包含：场景、期望/实际结果、根因、修复方案 +- If the issue requires hang or another agent → post in report channel +- Include: scenario, expected/actual result, root cause, fix applied diff --git a/claw-skills/workflows/improve-skills.md b/claw-skills/workflows/improve-skills.md index 1562946..c84cbae 100644 --- a/claw-skills/workflows/improve-skills.md +++ b/claw-skills/workflows/improve-skills.md @@ -1,49 +1,49 @@ # improve-skills -当发现现有 skill 或 workflow 存在以下问题时使用： +Used when a skill or workflow has one of these problems: -- 有误导或歧义 -- 没有覆盖到你的使用情景 -- 效果不理想 +- Misleading or ambiguous +- Missing coverage for your use case +- Suboptimal or confusing behavior -## 原则 +## Principle -改进比 work-around 更好。发现问题时及时修正，避免后续其他人踩同样的坑。 +Improvement is better than workaround. Fix problems when you find them, so others don't hit the same坑. -## 流程 +## Process -### 1. 识别问题 +### 1. Identify the Problem -- 记录哪个 skill 的哪个部分有问题 -- 具体描述：哪里误导、哪里缺失、哪里效果差 -- 记录触发场景：什么情况下发现这个问题 +- Record which skill and which part has the issue +- Describe specifically: what's misleading, what's missing, what's not working well +- Record the scenario where you encountered it -### 2. 评估影响范围 +### 2. Assess Impact -- 这个问题会影响多少人？ -- 是 skill 设计问题还是描述/文档问题？ -- 修复复杂度如何？ +- How many people will this affect? +- Is it a design issue or a documentation issue? +- What's the complexity of the fix? -### 3. 确定改进方案 +### 3. Design the Fix -- **文档问题** → 改 SKILL.md 或相关描述 -- **逻辑缺陷** → 修改脚本或 skill 逻辑 -- **覆盖缺失** → 新增流程或脚本 -- **流程不顺** → 重新设计 workflow +- **Documentation issue** → update SKILL.md or related descriptions +- **Logic flaw** → modify the script or skill logic +- **Missing coverage** → add a new workflow or script +- **Process issue** → redesign the workflow -### 4. 执行改进 +### 4. Implement -- 在本地或分支上修改 -- 更新 SKILL.md（如果改了描述） -- 如果改动较大，先在本地测试 +- Make changes locally or on a branch +- Update SKILL.md if behavior changed +- Test if the change is significant -### 5. 提交 +### 5. Submit -- 按 promote-improvements 流程提交到自己的分支 -- commit message 说明改进内容 -- 附上问题描述和解决思路（便于 hang review） +- Follow promote-improvements to push to your branch +- Commit message should describe what was changed and why +- Include problem description and fix rationale for hang's review -### 6. 通知 hang +### 6. Notify hang -- 完成后告知 hang，说明改了什么、为什么改 -- 让 hang 决定是 merge 还是继续调整 +- After completion, tell hang what was changed and why +- Let hang decide whether to merge or iterate further