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)

On activation:

Announce: "✅ 会话清理追踪已开启。我将记录本次对话中生成的所有临时文件、安装的库与 Skill。"

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: "✅ 发现上一次会话的追踪记录，已恢复。"

{
  "started_at": "ISO-8601 timestamp",
  "workspace": "path/to/workspace",
  "items": {
    "temp_files": [],
    "pip_packages": [],
    "npm_packages": [],
    "system_software": [],
    "skills": [],
    "other": []
  },
  "skip_list": []
}

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:

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.
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
use_skill or init_skill.py** — If a new skill is being installed or initialized, append the skill path to skills.
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)

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)

List all Class A items and announce: "以下临时文件将直接清除："
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.
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:
```
# 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>"
Confirm deletion result for each item (✅ deleted / ⚠️ failed).
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>:

Search all arrays in session-track.json > items for entries containing <X> as a substring.
If exactly one match → add the full matched string to skip_list, confirm to user.
If multiple matches → list them and ask user which one to skip.
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)

Never auto-delete files outside temp/scratch/generated paths without explicit confirmation.
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.
Never use rm -rf or del /S /Q on home, desktop, downloads, or project roots.
Skills deletion is permanent — always warn before removing Skills.
If a deletion fails, stop and report the error. Do NOT retry with broader paths.
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