Workspace Temp

SKILL.md

---
name: workspace_temp
description: Manage temporary files in workspace temp directory. All non-essential files must go to temp/, keeping workspace root clean. Auto-detects workspace from openclaw.json config.
metadata:
  {
    "openclaw":
      {
        "requires": { "config": ["agents.defaults.workspace"] },
        "tools": ["sessions_list", "read", "write"],
        "os": ["darwin", "linux", "win32"],
      },
  }
---

> **Note:** This skill requires access to `~/.openclaw/openclaw.json` (to read `agents.defaults.workspace`) and the `sessions_list` tool (to get current session ID). It is NOT enabled by default (`always: false`). Users must explicitly enable it in their config.

# Workspace Temp Skill

## Purpose

Ensure all temporary/cached files go to `<workspace>/temp/<session_id>/`, never pollute the workspace root.

## Required Permissions

This skill requires the following access:

| Resource | Purpose | Justification |
|----------|---------|---------------|
| `~/.openclaw/openclaw.json` | Read `agents.defaults.workspace` configuration | Required to determine the workspace path where temp/ directory will be created. Read-only access to single config file. |
| `sessions_list` tool | Get current session ID | Required to create isolated temp directories per session (prevents file conflicts between concurrent sessions). |
| External file system | Read user-specified files | Required when user asks to process files from outside the workspace. Files are only read and copied to temp directory. |

**Note:** The `sessions_list` tool and external file access are runtime capabilities documented here for transparency.

## Security & Privacy

### Skill Safety Guarantees

This skill operates under strict safety constraints:

- **No Code Execution:** Does not execute arbitrary code, shell commands, or external programs
- **Isolated Write Scope:** All write operations restricted to `<workspace>/temp/<session_id>/` only
- **Read-Only External Access:** External files are only read and copied, never modified in place
- **Temporary Only:** Files are designed to be deleted; no permanent storage outside workspace

### User Privacy & Security Notes

⚠️ **Sensitive Data:** Files processed through this skill may temporarily contain sensitive data in the temp directory. Avoid processing files with passwords, keys, or secrets.

⚠️ **Behavioral Guarantee:** The promise not to modify pre-existing workspace files is a **best-effort guarantee**, not technical enforcement. The instruction guides the agent but cannot prevent all edge cases.

## How It Works

1. Read `~/.openclaw/openclaw.json` to get `agents.defaults.workspace`
2. Get current session unique ID via `sessions_list`
3. Use `<workspace>/temp/<session_id>/` as the temp directory
4. Auto-create the directory if it doesn't exist

## File Classification Rules

### 🔒 Original Files (Existing Before Skill Installation)

**Definition:** All files and directories in the workspace root at the time this skill is installed.

These files **remain unchanged**:
- AGENTS.md, SOUL.md, USER.md, TOOLS.md
- MEMORY.md, HEARTBEAT.md, IDENTITY.md
- memory/ directory and its contents
- .git/ directory
- Any files existing before installation

**Additional Note:** Files manually added to the workspace root by the user after installation will also not be modified or deleted by this skill. However, users are encouraged to follow the principle: "Non-temporary files go in the root directory, temporary files go in temp/."

### 🗑️ Temporary Files (Must Go to temp/)

**Definition:** Files read from or downloaded from outside the workspace.

These files **must go to temp/**:
- Files read from user-specified external locations
- Downloaded files
- Intermediate files during conversion/processing

**Not Temporary Files:**
- Files generated by OpenClaw itself (e.g., session logs, internal caches)
- Files explicitly requested by the user to be saved to the workspace

## Dynamic Temp Directory Resolution

```
1. Read ~/.openclaw/openclaw.json
2. Extract agents.defaults.workspace
3. Get current session ID via sessions_list
4. Temp dir = <workspace>/temp/<session_id>/
```

Example:
- If workspace is `E:/OpenClaw/workspace`
- If session ID is `abc123`
- Then temp dir is `E:/OpenClaw/workspace/temp/abc123/`

## Procedures

### Step 1: Get Temp Directory

Always determine temp dir dynamically:
```javascript
// Pseudocode
const config = readFile('~/.openclaw/openclaw.json');
const workspace = config.agents.defaults.workspace;

// Get current session ID via sessions_list tool
const sessions = sessions_list();
const currentSession = sessions.find(s => s.key.includes('main'));
const sessionId = currentSession ? currentSession.sessionId : generateFallbackId();

const tempDir = path.join(workspace, 'temp', sessionId);

// Error handling: ensure directory creation succeeds
try {
  ensureDirExists(tempDir);
} catch (error) {
  throw new Error(`Failed to create temp directory: ${tempDir}. Reason: ${error.message}. Please check permissions or disk space.`);
}
```

**Error Handling Principles:**
- If `temp/` or `<session_id>/` directory cannot be created (e.g., insufficient permissions, disk full), a clear error message must be provided
- **Never** fall back to writing files to the workspace root directory
- Operation terminates; retry after user resolves the issue

### Step 2: Handle External Files

1. Copy files to `<workspace>/temp/<session_id>/`
2. Read/process from temp
3. Optionally clean up after processing

### Step 3: Handle Downloads

1. Download directly to `<workspace>/temp/<session_id>/`
2. Optionally clean up after processing

### Step 4: Handle Generated Files

1. Write to `<workspace>/temp/<session_id>/`
2. Delete after use

## Examples

**User says: "Read the report.txt from my desktop"**
- ❌ Wrong: Read desktop path directly
- ✅ Correct:
  1. Read `~/.openclaw/openclaw.json` to get workspace
  2. Copy to `<workspace>/temp/<session_id>/report.txt`
  3. Read content from temp

**User says: "Download this image"**
- ❌ Wrong: Download to workspace root
- ✅ Correct: Download to `<workspace>/temp/<session_id>/image.jpg`

**User says: "Convert this PDF"**
- ❌ Wrong: Generate intermediate files in root directory
- ✅ Correct: Generate in `<workspace>/temp/<session_id>/`, clean up after conversion

## Cleanup Policy

When the user explicitly requests cleanup assistance (e.g., "Check my temp directory", "Clean up temp files"), evaluate the following conditions and offer appropriate actions:

### Cleanup Triggers & Actions

| Trigger | Condition | Action | User Options |
|---------|-----------|--------|--------------|
| **Large Directory** | Temp directory > 500MB | Alert: "Your temp directory is using X GB. Clean up?" | "Clean up" (delete) / "Keep" / "I'll do it myself" (provide path) |
| **Old Files** | Files older than 7 days | Alert: "Found X files older than 7 days. Clean up?" | Same as above |
| **Session Residuals** | Current session temp not empty | Alert: "This session created X temporary files. Keep or clean up?" | Same as above |
| **Status Check** | User asks for temp status | Report: size, file count, oldest files, then offer cleanup | Same as above |

### Cleanup Scope

- **Skill-Initiated:** Intermediate files should be deleted immediately after use
- **Session-End:** Current session's `<session_id>/` directory should be cleaned when session ends
- **Manual:** Users can clear any subdirectory under `temp/` at any time
- **Safety:** `temp/` only contains temporary files; cleanup never affects original workspace files

**Important:** Do NOT proactively interrupt users with cleanup reminders. Only check and offer cleanup when explicitly requested.

## Notes

- Temp directory follows workspace configuration and adapts automatically
- If workspace changes, temp directory follows automatically
- Always use absolute paths to avoid ambiguity
- **Never touch original files existing before installation**
- This skill is **NOT enabled by default** - users must explicitly enable it in `~/.openclaw/openclaw.json`