Skill: chaobs/super-session-cleanup (version 1.4.0)

--- name: session-cleanup author: Chaobs version: 1.4.0 description: > Session cleanup skill for Claw-family agents (OpenClaw, WorkBuddy, QClaw, etc.). This skill should be used when the user wants to track and clean up temporary files, scripts, installed skills, libraries, and software generated during a conversation session. Trigger phrases include: "开启清理追踪", "session cleanup", "会话清理", "清理垃圾文件", "清理对话文件", "清理临时文件", "结束清理", "列出临时文件", "清理 Skill", "卸载多余库", "clean up session", "cleanup now", "帮我清理". --- # Session Cleanup Skill ## Purpose Track and clean up all artifacts produced during a Claw-family agent session: - Temporary files, demo scripts, and test outputs written to disk - Python packages, npm packages, system software installed via pip/npm/brew/apt/winget - Skills installed into `~/.workbuddy/skills/` or `.workbuddy/skills/` - Any other transient resources that are no longer needed after the session ## Lifecycle — Two Phases ### Phase 1 · Tracking (activated at session start or on demand) **Trigger words (start tracking):** `开启清理追踪` | `启动会话清理` | `session cleanup start` | `track session files` | `开始记录临时文件` | `enable cleanup tracking` **On activation:** 1. Announce: "✅ 会话清理追踪已开启。我将记录本次对话中生成的所有临时文件、安装的库与 Skill。" 2. Create a persistent tracking file at `<workspace>/.workbuddy/session-track.json` with the following structure. If the file already exists from a previous interrupted session, load it and announce: "✅ 发现上一次会话的追踪记录，已恢复。" ```json { "started_at": "ISO-8601 timestamp", "workspace": "path/to/workspace", "items": { "temp_files": [], "pip_packages": [], "npm_packages": [], "system_software": [], "skills": [], "other": [] }, "skip_list": [] } ``` 3. After each subsequent tool call that produces a tracked artifact, append the item to the relevant array in `session-track.json` using `replace_in_file` or `write_to_file`. This ensures the tracking log survives token overflow, session resets, or unexpected interruptions. Do NOT announce each individual append. **What to track — detection rules:** | Category | Detection signal | |---|---| | Temp files | `write_to_file` / `execute_command` that creates a file in a temp path (`%TEMP%`, `/tmp`, session scratch dirs, `generated-images/`), OR any file where the explanation contains keywords: "temporary", "demo", "test", "example", "scratch", "临时", "演示", "测试" | | Pip packages | `pip install`, `pip3 install`, `uv pip install` | | npm packages | `npm install`, `npx ... --save` | | System software | `winget install`, `choco install`, `apt install`, `brew install`, `scoop install` | | Skills | `init_skill.py`, `use_skill`, manually writing a new `SKILL.md` to a skills folder | | Other | Any item the user explicitly asks to track | **Auto-tracking enforcement (critical — prevents missed items):** After EVERY tool call while tracking is active, perform a quick post-check on the tool call result. This is mandatory and must not be skipped: 1. **`write_to_file`** — Check if the `filePath` is in a temp/scratch/generated path OR if the `explanation` contains keywords: "temporary", "demo", "test", "example", "scratch", "临时", "演示", "测试". If yes → append to `temp_files` in `session-track.json`. 2. **`execute_command`** — Scan the command string for: - `pip install` / `pip3 install` / `uv pip install` → extract package name, append to `pip_packages` - `npm install` / `npm i` → extract package name, append to `npm_packages` - `winget install` / `choco install` / `apt install` / `brew install` / `scoop install` → extract package name, append to `system_software` - Any command that creates a file in a temp path (redirect to `%TEMP%`, `/tmp`, etc.) → append to `temp_files` 3. **`use_skill`** or `init_skill.py`** — If a new skill is being installed or initialized, append the skill path to `skills`. 4. **User's explicit instruction** — If the user says "track this" / "记录这个" / "add to cleanup", append to `other`. This post-check should be a silent, automatic step — do NOT announce it to the user. Simply update `session-track.json` in the background. ### Phase 2 · Cleanup (triggered on demand or session end) **Trigger words (run cleanup):** `清理垃圾文件` | `结束清理` | `清理对话文件` | `cleanup now` | `clean session` | `清理临时文件` | `会话清理` | `帮我清理` | `删除临时文件` | `clean up` **Cleanup workflow — follow these steps in order:** #### Step A · Display the session log Read `session-track.json` from `<workspace>/.workbuddy/`. Print the full tracked list as a Markdown checklist grouped by category. Format each category array as a checklist. Example output: ``` ## 本次会话产生的资源清单 ### 🗂 临时文件 - [ ] C:\Users\<user>\AppData\Local\Temp\demo_script.py - [x] C:\Users\<user>\AppData\Local\Temp\keep_this.py (保留) - [ ] /path/to/workspace/generated-images/test.png ### 📦 安装的 Python 包 - [ ] requests==2.31.0 ### 🧩 安装的 Skills - [ ] ~/.workbuddy/skills/my-test-skill/ ``` If the tracked list is empty (excluding skip_list items), say: "📭 本次会话未检测到可清理的资源。" and stop. When classifying, check `skip_list` in `session-track.json` — any item in `skip_list` should be excluded from cleanup and shown as "保留" in the summary. #### Step B · Classify items For each tracked item, classify it as either: - **A: Safe to auto-delete** — files with no dependencies (temp files, demo scripts, test outputs, generated images). These are deleted without asking. - **B: Requires confirmation** — installed packages, Skills, or system software that may have dependencies or ongoing utility. These require explicit user consent. #### Step C · Auto-delete safe items (Class A) 1. List all Class A items and announce: "以下临时文件将直接清除：" 2. **Choose deletion strategy based on item count:** - **5 items or fewer** → Agent deletes each item individually using `delete_file` (workspace files) or `execute_command` (non-workspace files). This gives step-by-step visibility and is token-efficient for small lists. - **6+ items** → Agent runs `cleanup.py` in two phases: 1. **Preview**: `python "<skill_dir>/scripts/cleanup.py" --track-file "<workspace>/.workbuddy/session-track.json" --dry-run` 2. **Execute**: `python "<skill_dir>/scripts/cleanup.py" --track-file "<workspace>/.workbuddy/session-track.json"` This leverages the script's built-in safety checks, trash-first logic, and batch efficiency. - **User explicitly requests one-click cleanup** → Use `cleanup.py` regardless of item count. 3. **Deletion method per file (when deleting individually):** - **Files inside the workspace** → use `delete_file` tool directly. - **Files outside the workspace** (e.g. `%TEMP%`, `/tmp`, home directory) → use `execute_command` with a **trash-first** strategy: - **Windows** — Move to Recycle Bin first; only hard-delete if trash fails: ```powershell # Try Recycle Bin first (safe, reversible) $shell = New-Object -ComObject Shell.Application $item = $shell.NameSpace(0).ParseName('<file_path>') $item.InvokeVerb('delete') ``` If the above fails or the item doesn't appear in Recycle Bin, fall back to: `Remove-Item "<file_path>" -Force` - **macOS** — `osascript -e 'tell app "Finder" to delete POSIX file "<file_path>"'` Fallback: `rm "<file_path>"` - **Linux** — `gio trash "<file_path>"` or `trash-put "<file_path>"` Fallback: `rm "<file_path>"` 4. Confirm deletion result for each item (✅ deleted / ⚠️ failed). 5. **For temp directory files** (`%TEMP%`, `/tmp`), hard-delete is acceptable since these are OS-managed scratch spaces. For all other paths, always prefer trash. #### Step D · Confirm before removing dependencies (Class B) For each Class B item, present a grouped confirmation prompt: ``` 以下资源涉及依赖关系，需要您确认是否删除/卸载： 📦 Python 包: • requests==2.31.0 → pip uninstall requests 🧩 Skills: • ~/.workbuddy/skills/my-test-skill/ → 将永久删除 请回复： 全部删除 / 全部保留 / 逐一确认 ``` - If user replies **全部删除** → uninstall/remove all Class B items. - If user replies **全部保留** → skip all, close the log. - If user replies **逐一确认** → iterate through each item and ask individually. For package uninstalls: - Pip: `pip uninstall -y <package>` via `execute_command` - npm: `npm uninstall -g <package>` via `execute_command` - winget: `winget uninstall --id <id>` via `execute_command` - choco: `choco uninstall <package> -y` via `execute_command` - brew: `brew uninstall <formula>` via `execute_command` - apt: `sudo apt remove -y <package>` via `execute_command` - scoop: `scoop uninstall <app>` via `execute_command` For Skills uninstall: - Delete the skill directory via `execute_command`: - Windows: `Remove-Item -Path "<skill_dir>" -Recurse -Force` - macOS/Linux: `rm -rf "<skill_dir>"` - Do NOT use `delete_file` for skill directories as they are typically outside the workspace. - **Always warn**: "⚠️ Skill 删除是永久性的，目录下所有文件将被移除。" For system_software uninstall: - Always treat as Class B (requires confirmation). - Present the exact uninstall command that will be run so the user can verify. - If the package was installed via `winget`, try `winget list <name>` first to find the exact ID before uninstalling. #### Step E · Session log cleanup After cleanup is complete, print a summary: ``` ✅ 会话清理完成 已删除临时文件: N 项 已卸载 Python 包: N 项 已删除 Skills: N 项 跳过/保留: N 项 ``` Reset the in-memory session log and delete `<workspace>/.workbuddy/session-track.json`. ## Additional Commands | Command | Action | |---|---| | `列出临时文件` / `show session log` | Print current tracked list from `session-track.json` without deleting | | `清除记录` / `clear log` | Delete `<workspace>/.workbuddy/session-track.json` via `delete_file` and reset tracking state. Does NOT delete any actual files. **Note:** The safety rule "never delete `.workbuddy/` folder" protects the directory itself, not transient session files within it — `session-track.json` is explicitly designed to be deleted by this command. | | `手动添加 <path>` / `add to cleanup <path>` | Append a path to the relevant array in `session-track.json` | | `跳过 <path_or_name>` / `skip <path_or_name>` | Add an item to `skip_list` in `session-track.json`, excluding it from future cleanup. Accepts partial matches (e.g. `跳过 demo_script.py` matches the full path). Confirm to user: "✅ 已标记保留: <item>" | **`跳过` command detail:** When the user says `跳过 <X>`: 1. Search all arrays in `session-track.json > items` for entries containing `<X>` as a substring. 2. If exactly one match → add the full matched string to `skip_list`, confirm to user. 3. If multiple matches → list them and ask user which one to skip. 4. If no match → tell user "未找到匹配项" and suggest `列出临时文件` to review. Items in `skip_list` are displayed with `(保留)` tag in the cleanup list and excluded from actual deletion/uninstall. ## Safety Rules (Non-negotiable) 1. **Never auto-delete files outside temp/scratch/generated paths without explicit confirmation.** 2. **Never delete workspace source code, project configuration, or the `.workbuddy/` directory itself.** Exception: `session-track.json` inside `.workbuddy/` is a transient session file and may be deleted by the `清除记录` command or Step E cleanup. 3. **Never use `rm -rf` or `del /S /Q` on home, desktop, downloads, or project roots.** 4. **Skills deletion is permanent** — always warn before removing Skills. 5. **If a deletion fails, stop and report the error. Do NOT retry with broader paths.** 6. **Max 10 file deletions per batch.** Verify after each batch. ## Bundled Resources - `scripts/cleanup.py` — Command-line cleanup utility; can be run directly to remove a list of paths. - `references/cleanup-guide.md` — Full reference of uninstall commands by package manager and OS. ## Changelog ### v1.4.0 (2026-04-17) - **Fix**: `track_init()` shallow copy bug — nested `items` dict now uses `copy.deepcopy()` to prevent cross-session reference sharing (P2-6) - **Fix**: `uninstall_pip()` / `uninstall_npm()` now pre-check whether the package is actually installed before attempting uninstall (P2-9) - **Added**: Changelog section to SKILL.md (P2-8) ### v1.3.0 (2026-04-16) - **Fix**: Windows path safety bug — `Path("/")` resolving to `\` on Windows, incorrectly flagging all paths as unsafe - **Fix**: `skip_list` partial matching — added `_is_skipped()` helper for substring-based matching - **Fix**: `send_to_trash()` silent hard-delete fallback — now requires `allow_hard_delete=True` (only set for temp paths) - **Fix**: PowerShell single-quote escaping for paths with special characters - **Added**: `--workspace` CLI argument for `--manifest` mode - **Added**: `ALLOWED_SUBDIRS` list for workspace-aware safety checks (`generated-images`, `node_modules`) - **Added**: Step C decision logic in SKILL.md (≤5 items → individual delete; 6+ → script; one-click → script) - **Added**: Safety Rule #2 exception for `session-track.json` - **Added**: `(保留)` skip marker in Step A example output - **Added**: Duplicate detection rule row fix in SKILL.md table ### v1.2.0 (2026-04-15) - Initial public release with tracking and cleanup workflows - Trash-first deletion with OS-specific implementations - Session-track.json with skip_list support - cleanup.py CLI utility with `--init`, `--add`, `--skip-add`, `--show`, `--dry-run`


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)