rewrite all docs in English
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user