refactor: move bundled skills tree to repo root skills/

- Relocate runtime/skills -> skills/; runtime_skills_root() prefers oclaw/skills
  with fallback to legacy runtime/skills for unmigrated trees.
- session-bootstrap hook handler resolves repo root via PROJECT_ROOT.
- Update architecture/migration docs and in-tree skill references.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/ARCHITECTURE_OVERVIEW.md

@@ -16,7 +16,7 @@
 - `runtime/core/`：可复用执行内核（如 agent 执行管线聚合入口）。
 - `runtime/app/`：应用侧入口组织（面向外部流程的 runtime 编排）。
 - `runtime/agents|chat|orchestration|workers`：领域能力模块。
-- `runtime/skills|hooks|extensions`：可扩展能力载体。
+- `skills/`、`runtime/hooks`、`runtime/extensions`：可扩展能力载体（技能包在仓库根 `skills/`）。
 - `runtime/operations/scripts`：运维脚本与生成器。
 
 ## 路径规范

docs/OCLAW_COMPAT_REMOVAL_CHECKLIST.md

@@ -20,8 +20,8 @@ Use this checklist to verify readiness and post-delete safety for `oclaw/app_ser
 - [x] Runtime role context now loads from `oclaw/runtime/workspaces/*`.
 - [x] Skill root priority still effective:
   - [x] `AIA_SKILLS_ROOT`
-  - [x] `oclaw/runtime/skills`
+  - [x] `oclaw/skills`（仓库根）
-  - [x] `skills/` fallback
+  - [x] `oclaw/runtime/skills`（旧路径回退）
 
 ## Extension policy checks
 - [x] Primary extension source remains `oclaw/extensions/`.

docs/OCLAW_MIGRATION_GUIDE.md

@@ -74,6 +74,6 @@ This repository now uses **repo-root relative** runtime wiring.
 - Role context is loaded from `oclaw/runtime/workspaces/*`.
 - Skills root priority:
   1. `AIA_SKILLS_ROOT`
-  2. `oclaw/runtime/skills`
+  2. `oclaw/skills`（仓库根）
-  3. `skills/` (legacy fallback)
+  3. `oclaw/runtime/skills`（旧布局，若仍存在则 `runtime_skills_root()` 会回退）
 

interfaces/http/fastapi_app.py

@@ -196,7 +196,7 @@ def _run_startup_hooks(app: FastAPI) -> None:
 
     # NOTE: skill role binding is an optional feature. For ops, we rely on:
     # - role workspace system prompt (ROLE_SYSTEM.md) requiring the playbook
-    # - skill being present under runtime/skills/_workspace/ops/
+    # - skill being present under skills/_workspace/ops/
     try:
         warm_expert_workspace_cache()
     except Exception:

platform/config/runtime_paths.py

@@ -14,7 +14,14 @@ def runtime_root() -> Path:
 
 
 def runtime_skills_root() -> Path:
-    return (runtime_root() / "skills").resolve()
+    """Canonical skills tree lives at repo ``skills/``; ``runtime/skills`` remains a migration fallback."""
+    root_skills = (oclaw_root() / "skills").resolve()
+    legacy_runtime_skills = (runtime_root() / "skills").resolve()
+    if root_skills.is_dir():
+        return root_skills
+    if legacy_runtime_skills.is_dir():
+        return legacy_runtime_skills
+    return root_skills
 
 
 def runtime_hooks_root() -> Path:

runtime/hooks/README.md

@@ -32,7 +32,7 @@ Each hook directory needs `HOOK.md` (YAML frontmatter with `metadata.oclaw.event
 
 `session-bootstrap` is wired into the hooks runtime and loads on `agent:bootstrap`.
 
-- Hook package path: `runtime/skills/session-bootstrap/hooks/runtime/`
+- Hook package path: `skills/session-bootstrap/hooks/runtime/`
 - Manifest: `HOOK.md` (`metadata.oclaw.events: ["agent:bootstrap"]`)
 - Handler: `handler.py` (`handle(event)`)
 - Runtime source type: `oclaw-managed` (skill `hooks/` dirs are merged into `hooks.internal.load.extraDirs`)

runtime/skills/_workspace/public/README.md

@@ -1,16 +0,0 @@
-本目录用于 **公共 skills**。
-
-约定：
-- 路径：`oclaw/runtime/skills/_workspace/public/<skill_name>/SKILL.md`
-- 放在这里的 skill **默认对所有人可用**，不需要在 Admin 里做角色绑定。
-
-注意：
-- 仍会受 skill 本身的 `disable_model_invocation`、租户禁用列表等策略影响。
-本目录用于 **公共 skills**。
-
-约定：
-- 路径：`oclaw/runtime/skills/_workspace/public/<skill_name>/SKILL.md`
-- 放在这里的 skill **默认对所有人可用**，不需要在 Admin 里做角色绑定。
-
-注意：
-- 仍会受 skill 本身的 `disable_model_invocation`、租户禁用列表等策略影响。

skills/README.md

@@ -8,25 +8,25 @@
 - 技能说明正文请优先使用中文，便于团队统一维护。
 
 ## 示例结构
-- `oclaw/runtime/skills/<skill_name>/SKILL.md`
+- `oclaw/skills/<skill_name>/SKILL.md`
 
 ## 目录分层（重要）
-- **主目录**：`oclaw/runtime/skills/<skill_name>/`  
+- **主目录**：`oclaw/skills/<skill_name>/`  
   用于官方/手工管理的稳定技能（安装、维护、评审都在这层）。
-- **自写目录（扁平）**：`oclaw/runtime/skills/_workspace/<skill_name>/`  
+- **自写目录（扁平）**：`oclaw/skills/_workspace/<skill_name>/`  
   兼容旧行为；新装技能优先按角色分桶（见下）。
-- **公共目录**：`oclaw/runtime/skills/_workspace/public/<skill_name>/`  
+- **公共目录**：`oclaw/skills/_workspace/public/<skill_name>/`  
-  与 **按专家/角色目录** `oclaw/runtime/skills/_workspace/<role>/<skill_name>/`（如 `generalist`、`ops`）**平级**；`public` 下技能默认全员可用，不需角色绑定。
+  与 **按专家/角色目录** `oclaw/skills/_workspace/<role>/<skill_name>/`（如 `generalist`、`ops`）**平级**；`public` 下技能默认全员可用，不需角色绑定。
-- **遗留会话桶**：`oclaw/runtime/skills/_workspace/_agent/<segment>/` 仅用于无绑定角色时的回退（如旧会话 id），新逻辑不应依赖该层。
+- **遗留会话桶**：`oclaw/skills/_workspace/_agent/<segment>/` 仅用于无绑定角色时的回退（如旧会话 id），新逻辑不应依赖该层。
 
 说明：
 - `auto_install_skill_from_payload` 产物默认落在 `_workspace` 下。
 - 这样可以把“生产稳定技能”和“实验/自写技能”分开治理，便于审计与回滚。
 
 ## 兼容说明
-- 运行时优先读取 `oclaw/runtime/skills`。
+- 运行时默认读取仓库根 `oclaw/skills`（见 `platform.config.runtime_paths.runtime_skills_root`）。
 - 若设置了环境变量 `AIA_SKILLS_ROOT`，以该变量为准。
-- 为兼容旧工程，仍可回退读取旧路径 `oclaw/runtime/skills/`（如存在）。
+- 若根目录 `skills/` 不存在而仍存在旧布局 `oclaw/runtime/skills/`，会自动回退到后者。
 
 ## 技能市场（安装来源）
 

skills/_workspace/public/README.md

@@ -0,0 +1,8 @@
+本目录用于 **公共 skills**。
+
+约定：
+- 路径：`oclaw/skills/_workspace/public/<skill_name>/SKILL.md`
+- 放在这里的 skill **默认对所有人可用**，不需要在 Admin 里做角色绑定。
+
+注意：
+- 仍会受 skill 本身的 `disable_model_invocation`、租户禁用列表等策略影响。

skills/oclaw-skill-manager/SKILL.md

@@ -5,13 +5,13 @@ description: Oclaw 官方 Skill 生命周期手册：安装、更新、卸载、
 
 # Oclaw Skill 管理器（官方手册）
 
-本技能是 **Oclaw 自有** 的 Skill 运维说明，用于指导模型与运维在**同一套契约**下管理 `runtime/skills` 下的技能包。
+本技能是 **Oclaw 自有** 的 Skill 运维说明，用于指导模型与运维在**同一套契约**下管理仓库根 `skills/` 下的技能包。
 
 ## 系统强约束（模型必须遵守）
 
 - 规范优先：安装决策只依据本文件，不依据临时推断或“经验性排障说法”。
 - 路径约束：当任务目标是“为当前会话/用户安装 skill”时，**只允许**走 `skill_auto_install`（`_workspace` lane）。
-- 禁止绕路：不得调用任何非 auto 安装路径（包括但不限于 `skill_market_install`、`skill_registry_install`、Admin 安装 API、手写下载/解压脚本落盘到 `runtime/skills`）。
+- 禁止绕路：不得调用任何非 auto 安装路径（包括但不限于 `skill_market_install`、`skill_registry_install`、Admin 安装 API、手写下载/解压脚本落盘到仓库根 `skills/`）。
 - 失败处理：`skill_auto_install` 失败后，**不得继续安装**；只报告 `error_code/detail` 与最小下一步，等待用户指示。
 - 禁止臆测前置条件：未在本规范显式声明的环境变量/端口/服务状态，不得被表述为“安装必经条件”。
 
@@ -28,7 +28,7 @@ description: Oclaw 官方 Skill 生命周期手册：安装、更新、卸载、
 | 人工 / Admin 市场或 registry 安装 | `<skills_root>/<manifest_name>/` |
 | 智能体 payload 自动安装 | `<skills_root>/_workspace/<manifest_name>/` |
 
-`<skills_root>` 默认 `runtime/skills/`，可被 **`AIA_SKILLS_ROOT`** 覆盖。
+`<skills_root>` 默认仓库根 `skills/`，可被 **`AIA_SKILLS_ROOT`** 覆盖。
 
 ## 技能市场提供方（ClawHub + CocoLoop）
 

skills/oclaw-skill-manager/references/install-guide.md

@@ -10,7 +10,7 @@
 
 ## 1. 技能根目录
 
-- 默认：`runtime/skills/`（或环境变量 `AIA_SKILLS_ROOT` 指向的目录）
+- 默认：仓库根 `skills/`（或环境变量 `AIA_SKILLS_ROOT` 指向的目录）
 - **主目录**：`<skills_root>/<name>/` — Admin 市场 / registry / 本地目录安装默认落点
 - **智能体自写目录**：`<skills_root>/_workspace/<name>/` — `skill_auto_install` / `auto_install_skill_from_payload` 等
 

skills/oclaw-skill-manager/references/uninstall-guide.md

@@ -7,7 +7,7 @@
 1. `<skills_root>/<name>/`
 2. `<skills_root>/_workspace/<name>/`
 
-其中 `<skills_root>` 为 `AIA_SKILLS_ROOT` 或默认 `runtime/skills/`。
+其中 `<skills_root>` 为 `AIA_SKILLS_ROOT` 或默认仓库根 `skills/`。
 
 `<name>` 为 **`SKILL.md` frontmatter 中的 `name`**（与 `skill_list` 中 `name` 字段一致），不一定等于 ClawHub **slug**。
 

skills/self-improvement/assets/SKILL-TEMPLATE.md

@@ -117,7 +117,7 @@ description: "What this skill does and when to use it."
 ### Automated (Recommended)
 
 \`\`\`bash
-./runtime/skills/skill-name/scripts/helper.sh [args]
+./skills/skill-name/scripts/helper.sh [args]
 \`\`\`
 
 ### Manual Steps

skills/self-improvement/references/hooks-setup.md

@@ -23,7 +23,7 @@ Create `.claude/settings.json` in your project root:
         "hooks": [
           {
             "type": "command",
-            "command": "./runtime/skills/self-improvement/scripts/activator.sh"
+            "command": "./skills/self-improvement/scripts/activator.sh"
           }
         ]
       }
@@ -34,7 +34,7 @@ Create `.claude/settings.json` in your project root:
         "hooks": [
           {
             "type": "command",
-            "command": "./runtime/skills/self-improvement/scripts/error-detector.sh"
+            "command": "./skills/self-improvement/scripts/error-detector.sh"
           }
         ]
       }
@@ -78,7 +78,7 @@ For lower overhead, use only the UserPromptSubmit hook:
         "hooks": [
           {
             "type": "command",
-            "command": "./runtime/skills/self-improvement/scripts/activator.sh"
+            "command": "./skills/self-improvement/scripts/activator.sh"
           }
         ]
       }
@@ -100,7 +100,7 @@ Codex uses the same hook system as Claude Code. Create `.codex/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "./runtime/skills/self-improvement/scripts/activator.sh"
+            "command": "./skills/self-improvement/scripts/activator.sh"
           }
         ]
       }
@@ -145,7 +145,7 @@ For high-value learnings that would benefit other sessions, consider skill extra
 ### Dry Run Extract Script
 
 ```bash
-./runtime/skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
+./skills/self-improvement/scripts/extract-skill.sh test-skill --dry-run
 ```
 
 Expected output shows the skill scaffold that would be created.
@@ -162,9 +162,9 @@ Expected output shows the skill scaffold that would be created.
 ### Permission Denied
 
 ```bash
-chmod +x ./runtime/skills/self-improvement/scripts/activator.sh
+chmod +x ./skills/self-improvement/scripts/activator.sh
-chmod +x ./runtime/skills/self-improvement/scripts/error-detector.sh
+chmod +x ./skills/self-improvement/scripts/error-detector.sh
-chmod +x ./runtime/skills/self-improvement/scripts/extract-skill.sh
+chmod +x ./skills/self-improvement/scripts/extract-skill.sh
 ```
 
 ### Script Not Found
@@ -173,7 +173,7 @@ If using relative paths, ensure you're in the correct directory or use absolute
 
 ```json
 {
-  "command": "/absolute/path/to/runtime/skills/self-improvement/scripts/activator.sh"
+  "command": "/absolute/path/to/skills/self-improvement/scripts/activator.sh"
 }
 ```
 

skills/self-improvement/references/oclaw-integration.md

@@ -37,7 +37,7 @@ clawdhub install self-improving-agent
 Or copy manually:
 
 ```bash
-cp -r self-improving-agent ~/.oclaw/runtime/skills/
+cp -r self-improving-agent ~/.oclaw/skills/
 ```
 
 ### 2. Install the Hook (Optional)

skills/self-improvement/scripts/extract-skill.sh

@@ -31,7 +31,7 @@ usage() {
 示例:
   $(basename "$0") docker-m1-fixes
   $(basename "$0") api-timeout-patterns --dry-run
-  $(basename "$0") pnpm-setup --output-dir ./runtime/skills/custom
+  $(basename "$0") pnpm-setup --output-dir ./skills/custom
 
 技能将创建在: \$SKILLS_DIR/<skill-name>/
 EOF

skills/session-bootstrap/hooks/runtime/handler.py

@@ -26,8 +26,9 @@ def _workspace_dir(event: Any) -> Path | None:
 
 
 def _repo_root() -> Path:
-    # .../runtime/skills/session-bootstrap/hooks/runtime/handler.py
+    from oclaw.platform.config.paths import PROJECT_ROOT
-    return Path(__file__).resolve().parents[5]
+
+    return Path(PROJECT_ROOT).resolve()
 
 
 def _wiki_root(repo_root: Path) -> Path: