Claw 内部治理方案

版本： v1.0
日期： 2026-05-16
范围： 技能（Skills）、工具（Tools/CLI）、资产（Assets）的存放与管理规范

一、治理目标

所有自定义技能统一在 workspace/skills/ 下管理
工具（CLI 二进制）与技能（SKILL.md 定义）分离
资产报告有固定存放位置
添加新技能/工具时有明确的决策路径

二、总体结构

~/workspace/                            ← 工作区根
├── AGENTS.md
├── SOUL.md
├── USER.md
├── MEMORY.md                           ← 长期记忆
├── TOOLS.md                            ← 工具速查 + API Token
├── memory/                             ← 每日记录
│
├── skills/                             ← ★ 统一技能目录
│   ├── knowledge-base/                 ← 知识库操作（已存在）
│   ├── storyteller/                    ← 讲故事（从 .agents 迁入）
│   ├── gh-project-health/              ← GitHub 项目评估（从 .agents 迁入）
│   ├── opencli-usage/                  ← OpenCLI（从 ~/.agents 迁入）
│   └── README.md                       ← 本目录说明
│
├── reports/                            ← 生成报告
│   ├── 2026-05-16-dong-e-e-jiao.html
│   └── github-health/
│
└── .agents/skills/                     ← ★ 废弃，不再手动管理

三、技能治理

3.1 技能存放原则

所有技能一律放在 workspace/skills/<技能名>/SKILL.md。

来源	原路径	目标路径	操作
已有	workspace/skills/knowledge-base	不动	—
自定义	workspace/.agents/skills/storyteller	→ workspace/skills/storyteller	迁移
自定义	workspace/.agents/skills/gh-project-health	→ workspace/skills/gh-project-health	迁移
npx skills 安装	~/.agents/skills/opencli-usage	→ workspace/skills/opencli-usage	迁移

3.2 技能添加流程

场景 A：手工编写技能

在 workspace/skills/ 下创建 <技能名>/SKILL.md
遵循 AgentSkills 格式（含 frontmatter: name / description）
技能名统一用小写英文，连字符分隔（如 knowledge-base，不用 KnowledgeBase）

场景 B：安装第三方技能

# 先装到工作区
openclaw skills install <slug>
# npx skills 安装的，移进去
npx skills add <包名> --skill <技能名> -g -y
cp -r ~/.agents/skills/<技能名> ~/workspace/skills/
rm -rf ~/.agents/skills/<技能名>

3.3 技能命名规范

skills/<类别>-<名称>/

类别	命名	示例
工具使用	工具名	opencli-usage
业务技能	功能描述	knowledge-base, gh-project-health
创作技能	创作类型	storyteller

3.4 禁止行为

❌ 不往 ~/.agents/skills/ 手动加技能
❌ 不修改 /app/skills/ 下的内容（是软件包，改不动的也无必要）
❌ 不把技能放到 workspace 根目录或散落在 memory/ 里

四、工具治理

4.1 CLI 工具与技能的关系

CLI 工具（二进制）           Skill 定义（SKILL.md）
─────────────────           ─────────────────────
opencli 命令                 opencli-usage/SKILL.md
装到 PATH 上                告诉 Agent 怎么用这个命令

工具本体和技能定义是两个东西。技能只是说明书，工具才是可执行文件。

4.2 工具安装位置

安装方式	存放路径	示例
npm -g（有 root）	/usr/local/bin/	—
npm -g（用户级）	~/.npm-global/bin/	opencli
pip install	/usr/local/bin/ 或系统 Python 目录	Python 工具
源码编译	/usr/local/bin/	Cargo 等

工具安装路径受技术限制，不可自由选定（npm -g 装到哪由 npm prefix 决定）。

4.3 工具注册到 TOOLS.md

安装完成后，在 TOOLS.md 中登记：

### CLI 工具清单

| 工具 | 路径 | 安装方式 | 用途 |
| --- | --- | --- | --- |
| opencli | ~/.npm-global/bin/opencli | npm -g @jackwener/opencli | 网站转 CLI 获取数据 |

这样无论你是自己用，还是通过 Agent 调用，都能查到装了哪些工具、在哪。

4.4 工具卸载

# npm 工具
npm uninstall -g @jackwener/opencli

# 同时删 TOOLS.md 里的记录

五、资产治理

5.1 报告存放

workspace/reports/
├── YYYY-MM-DD-<描述>.html        ← 交互报告
└── <项目名>/                      ← 多文件报告

5.2 知识库（SiYuan）与工作区的关系

内容	存哪	原因
调研报告文档	SiYuan 知识库	可搜索、可导出、可关联
原始 HTML 报告	workspace/reports/	文件较大，不适合存思源
技能与工具清单	SiYuan「claw 内部」目录	系统文档，跟知识库在一起方便查阅

六、实施步骤

□ 1. 迁移 storyteller 到 workspace/skills/
     cp -r workspace/.agents/skills/storyteller workspace/skills/
     （保留原 .agents 备份，确认无问题后删除）

□ 2. 迁移 gh-project-health 到 workspace/skills/
     同上

□ 3. 迁移 opencli-usage 到 workspace/skills/
     cp -r ~/.agents/skills/opencli-usage workspace/skills/
     删除原目录

□ 4. 清理 workspace/.agents/skills/
     只保留 gh-project-health.skill 绑定文件
     技能实体全部迁走

□ 5. 更新 workspace/skills/README.md
     写明目录规范

□ 6. 更新 TOOLS.md
     登记所有已安装的 CLI 工具

□ 7. 这个文档本身已存到 SiYuan「claw 内部」目录

七、示意图

迁移前                             迁移后
──────                             ──────

workspace/skills/                  workspace/skills/
├── knowledge-base/        →       ├── knowledge-base/
                                   ├── storyteller/
                                   ├── gh-project-health/
                                   ├── opencli-usage/
                                   └── README.md

workspace/.agents/skills/          workspace/.agents/skills/
├── storyteller/          →       （清空或只留 .skill 绑定文件）
├── gh-project-health/
└── gh-project-health.skill

~/.agents/skills/                  ~/.agents/skills/
└── opencli-usage/        →       （清空）

八、例外与特殊情况

情况	处理方式
`/app/skills/` 下的内置技能	不动，不覆盖，也不关心
`/app/extensions/*/skills/`	插件自带的，启用插件自动加载
`npx skills add` 默认装到 ~/.agents	装完后手工移入 workspace/skills/
openclaw skills install	默认装到 workspace/skills/，无需迁移
需要全局共享的 skill	当前单用户，不需要「全局」，统一放 workspace 即可