ClawHub Package Notes

This ClawHub build is self-contained. The installed skill folder includes:

bridges/ for the local bridge server and preflight scripts
apps/chrome-executor-extension/ for the bundled unpacked Chrome executor extension
package.json with the local bridge dependency

When this skill says <skill-folder>, use the installed ClawHub skill folder containing this SKILL.md file.

Do not symlink or modify OpenClaw configuration during setup. ClawHub/OpenClaw owns skill installation. The only manual browser step is loading the bundled Chrome executor extension once from the installed skill folder.

Bookmark Organize

这是一个“计划优先、显式确认、桥接执行”的技能，不是普通聊天提示。

Host Workflow

The host should treat this skill as an operational workflow, not just extra prose.

Invocation:

Preferred generic command: /skill bookmark-organize [自然语言整理需求]
If OpenClaw exposes a direct skill command, use /bookmark_organize ...; skill command names are sanitized, so /bookmark-organize ... may not exist.

User-facing modes:

setup or doctor: run the setup/doctor flow, open Chrome extension settings if needed, and report the next single user action
organize or any natural-language cleanup request: run doctor/preflight first, then preview a plan
apply: run bridge:ensure-live, validate the latest plan, then apply only after explicit confirmation
undo: run bridge:ensure-live, call POST /undo, and report the bridge result

Shortest safe path:

run the local preflight wrapper from this skill folder
fetch live bookmark context from POST /context
generate a conservative preview
wait for explicit confirmation
run bridge:ensure-live again before any apply or undo
call POST /validate
call POST /apply or POST /undo
report only bridge-verified results

Portable preflight command:

node <skill-folder>/scripts/run-repo-script.mjs bridge:preflight

Portable first-run setup command:

node <skill-folder>/scripts/run-repo-script.mjs setup

When installed from ClawHub, <skill-folder> is the installed skill folder containing this SKILL.md file.

For local end-to-end verification, prefer:

node <skill-folder>/scripts/run-repo-script.mjs test:e2e

Purpose

Help the user organize Chrome bookmarks through natural language.

The host AI should:

talk to the user in natural language
ask the Chrome executor extension for bookmark context
produce a structured action plan
preview the plan before any mutation
ask for explicit confirmation
apply the plan through the Chrome bridge
offer undo after a successful apply

Important Rules

Never mutate bookmarks on the first planning response
Always present a preview before apply
Keep actions limited to the supported schema
Surface low-confidence or ambiguous cases in warnings
If Chrome is not connected, distinguish first-run install from an already-installed but sleeping/disconnected extension
Never claim that bookmarks were changed unless you have verified success through the local bridge
Never invent folder counts, bookmark counts, or apply results
Never tell the user to restart Chrome unless a verified tool result requires it
If bridge verification fails, explicitly say the task is not yet executed
Do not use direct filesystem reads or writes of Chrome bookmark files as a substitute for execution
The only supported execution path is the local bridge plus Chrome executor extension
Do not rely on stale bridge health alone; require a live context check before planning or apply

Mandatory Preflight

Before planning, validation, apply, or undo, the host AI should run a local preflight.

Preferred command:

node <skill-folder>/scripts/run-repo-script.mjs bridge:preflight

The preflight is responsible for:

starting the local bridge server if it is not running
refreshing the unpacked Chrome extension when needed
verifying that live bookmark context can be fetched

If preflight fails, stop and explain that execution has not happened yet.

Preflight is not optional even if a previous turn said the bridge looked healthy.

Before POST /validate, POST /apply, or POST /undo, prefer the stronger live gate:

node <skill-folder>/scripts/run-repo-script.mjs bridge:ensure-live

If this command succeeds, continue the current operation. If it fails, stop and tell the user no mutation happened.

If this is the user's first run, or if preflight says needsManualInstall: true, run:

node <skill-folder>/scripts/run-repo-script.mjs setup

Then tell the user to load the unpacked Chrome extension folder printed by the setup command and reply 好了.

Do not show the first-run install instructions merely because executorConnected is false.

Use /health and preflight output to choose the recovery message:

If /health has executor.extensionVersion or executor.lastSeenAt, the extension is already installed or has checked in before. Treat this as a sleeping/disconnected MV3 worker. Run bridge:ensure-live or bridge:preflight; if recovery still fails, ask the user to reload the existing Bookmark Organize Executor card on chrome://extensions, not to click 加载已解压的扩展程序 again.
If /health does not have executor.extensionVersion and does not have executor.lastSeenAt, or preflight says needsManualInstall: true, treat it as first-run install and use the manual install prompt below.

Use this user-facing wording only when the extension is not installed:

我需要你完成唯一一步浏览器授权操作：
1. 在已打开的 chrome://extensions 页面开启「开发者模式」
2. 点击「加载已解压的扩展程序」
3. 选择 setup 输出的 Chrome executor extension 文件夹

加载完成后回复「好了」，我会自动继续检查连接并读取书签。

Use this user-facing wording when the extension was seen before but is currently disconnected:

Chrome executor 扩展已经安装过，但当前后台连接休眠/断开了。我会先自动唤醒并重连。
如果自动恢复仍失败，请在 chrome://extensions 里找到 `Bookmark Organize Executor`，点击该扩展卡片右下角的重新加载按钮，然后回复「好了」。
我还没有实际修改你的书签。

Mandatory Execution Guardrails

Before claiming any of the following:

"已整理完成"
"已创建文件夹"
"已移动书签"
"已重命名"
"已撤销"

you must first verify with the local bridge.

Required bridge checks:

Run node <skill-folder>/scripts/run-repo-script.mjs bridge:ensure-live
Check http://127.0.0.1:8787/health
Ensure executorConnected is true
Fetch live context from POST /context
Use bridge endpoints to validate actions, apply actions, or undo actions
Report only the results returned by the bridge

If the bridge is unavailable, say that execution has not happened yet.

Local Bridge

Preferred local bridge:

HTTP base URL: http://127.0.0.1:8787
Health endpoint: GET /health
Context endpoint: POST /context
Validate endpoint: POST /validate
Apply endpoint: POST /apply
Undo endpoint: POST /undo

The Chrome executor extension folder is:

<repo-root>/apps/chrome-executor-extension

The local bridge server can be started from:

<repo-root>

with:

npm run bridge:server

Preferred recovery command:

npm run bridge:preflight

Supported Actions

create_folder
move_bookmark
rename_bookmark
rename_folder

Planning Guidance

When generating a plan:

prefer conservative actions
avoid renaming when confidence is low
create folders before moving bookmarks into them
never emit deletion actions
never emit move-folder actions
if doing an E2E test, put create_folder, move_bookmark, and rename_bookmark in one single action list and one single POST /apply; do not split the test into multiple apply calls because only the latest apply has an undo token
for moves into a folder created earlier in the same plan, use targetPath with the newly-created folder path instead of waiting for a folder id

When the user asks to organize bookmarks:

run preflight
if preflight fails, guide setup and stop
fetch live bookmark context
generate a conservative structured plan
preview the plan
wait for explicit confirmation
run bridge:ensure-live again before apply
apply only after confirmation
summarize actual bridge results

Confirmation Flow

After previewing a plan, allow the user to respond with short commands such as:

apply
apply moves only
exclude renames
regenerate more conservatively
undo last apply

Setup Guidance

If the Chrome executor extension is unavailable, first check whether it was seen before:

If /health includes executor.extensionVersion or executor.lastSeenAt, do not run first-run setup unless the user explicitly asks. Run bridge:ensure-live; if it still fails, ask the user to reload the existing extension card.
If /health has neither executor.extensionVersion nor executor.lastSeenAt, guide the user with first-run setup:

run node <skill-folder>/scripts/run-repo-script.mjs setup
tell the user to open the extension page if it did not open automatically
tell the user to enable Developer Mode
tell the user to choose Load unpacked
tell the user to select the extension folder printed by setup
ask the user to reply 好了
after the user replies, run node <skill-folder>/scripts/run-repo-script.mjs bridge:preflight

Then ask the user to reply with 已安装 or installed.

Verification Commands

Use these commands when you need to verify the environment instead of guessing:

node <skill-folder>/scripts/run-repo-script.mjs bridge:preflight
node <skill-folder>/scripts/run-repo-script.mjs bridge:ensure-live
node <skill-folder>/scripts/run-repo-script.mjs bridge:smoke
node <skill-folder>/scripts/run-repo-script.mjs test:local
node <skill-folder>/scripts/run-repo-script.mjs test:e2e

Output Contract

The host AI should generate a structured plan with:

summary
warnings
actions

Each action must include an actionId.

Response Style

Be explicit about whether you are previewing or executing
Use phrases like 我准备这样整理 before apply
Use phrases like 我已经通过本地桥接执行完成 only after verified bridge success
If execution has not happened, say 我还没有实际修改你的书签