Context Cleaner (.md cleanup)

Optimize OpenClaw agent context files by reducing token usage 30-50% with backups, preview, rollback, and preserving core functionality on request.

Security Scan

The skill's requirements and instructions align with its stated purpose (editing workspace Markdown files to reduce tokens); it is an instruction-only tool that operates on user workspace files and does not request unrelated credentials or installs.

Purpose & Capability

Name/description (context cleanup, token reduction, backups/rollback) match the instructions: the SKILL.md only reads and writes .md files under an OpenClaw workspace and creates tar backups. There are no unrelated credentials, binaries, or installs requested.

Instruction Scope

Instructions explicitly operate on /home/[USER]/.openclaw/workspace and detail safe operations (timestamped backups, preview/diff, rollback). Minor issues: path is hardcoded to /home/[USER] which may not match every environment, and some template wording (e.g., 'Preserve: Discord channel IDs (replace with [DISCORD_CHANNEL_ID] placeholder)') is ambiguous about whether secrets are removed or preserved. Otherwise the steps stay within the stated purpose and don't instruct network exfiltration or access to unrelated system areas.

Install Mechanism

No install spec and no code files — instruction-only. This minimizes risk because nothing is downloaded or written to disk by the skill bundle itself beyond what the agent is instructed to do at runtime.

Credentials

The skill requires no environment variables, no credentials, and no special config paths beyond the workspace files it claims to modify. Requested access is proportional to the task of editing agent workspace files.

Persistence & Privilege

always:false (normal) and the skill is user-invocable. The SKILL.md permits operations across all agents and main workspace files (with an explicit confirmation step), so users should be careful when authorizing 'all agents' or 'main workspace' scopes. Autonomous invocation is allowed by platform default but is not a red flag here by itself.

Assessment

This skill is internally consistent with its purpose, but review and proceed cautiously: 1) Verify the workspace path (/home/[USER]/.openclaw/workspace) matches your environment before running. 2) Always inspect the produced backup tar (location reported by the skill) and confirm the before/after diffs before accepting changes. 3) Be especially cautious if you run the 'main workspace' optimization — it can change core files (SOUL.md, AGENTS.md, etc.); only proceed after explicit confirmation. 4) Clarify how the skill handles IDs/placeholders (Discord/Notion) to avoid breaking integrations; test on a copy or non-production agent first. 5) If you allow the agent to run skills autonomously, restrict or monitor operations that target all agents or core files. If you want, request the author add a configurable workspace path and an explicit dry-run mode to improve safety.

Context Cleaner

Optimize OpenClaw agent workspace files to reduce context token usage by 30-50% without losing operational capability.

Triggers

• "run context-cleaner [for all agents | for AGENT_NAME]"
• "optimize agent context"
• "clean up agent files"
• "reduce context tokens"
• "context-cleaner your main core files"

Safety First

CRITICAL: This skill modifies agent workspace files. Always:

1. Create timestamped backup before any changes
2. Show user what will change before applying
3. Offer immediate rollback option
4. Never touch main workspace files without explicit confirmation

Workflow

Step 1: Parse Request

Determine scope:

• Single agent: "context-cleaner for outreach" → optimize one agent
• All agents: "context-cleaner for all agents" → optimize all agents
• Main workspace: "context-cleaner your main core files" → optimize main SOUL.md, AGENTS.md, etc. (requires explicit confirmation)

Step 2: Validate Target

For single agent:

ls /home/[USER]/.openclaw/workspace/AGENT_NAME/*.md

If no files found → Error: "Agent 'AGENT_NAME' not found. Available agents: [list]"

For all agents: Validate all agents exist in workspace.

For main workspace: ⚠️ WARNING: Main workspace optimization affects your core behavior. Require explicit user confirmation:

⚠️ This will modify YOUR core files (SOUL.md, AGENTS.md, etc.). This could affect your behavior.

Proceed? (yes/no)

Step 3: Create Backup

Timestamp format: YYYYMMDD-HHMM

cd /home/[USER]/.openclaw/workspace

# Single agent backup
tar -czf agent-backup-AGENT_NAME-TIMESTAMP.tar.gz AGENT_NAME/

# All agents backup
tar -czf agent-workspaces-backup-TIMESTAMP.tar.gz [AGENT_LIST]/

# Main workspace backup (if requested)
tar -czf main-workspace-backup-TIMESTAMP.tar.gz SOUL.md AGENTS.md TOOLS.md IDENTITY.md USER.md HEARTBEAT.md OPERATING_RULES.md

Report backup location to user:

✅ Backup created: /home/[USER]/.openclaw/workspace/agent-backup-AGENT_NAME-TIMESTAMP.tar.gz

To restore: tar -xzf agent-backup-AGENT_NAME-TIMESTAMP.tar.gz

Step 4: Analyze Current State

Count lines and estimate tokens for each file:

for file in IDENTITY.md AGENTS.md USER.md TASK.md TOOLS.md SOUL.md; do
  lines=$(wc -l < "AGENT_NAME/$file" 2>/dev/null || echo "0")
  echo "$file: $lines lines"
done

Step 5: Apply Optimizations

Optimization Rules:

1. Single responsibility per file:

   • IDENTITY.md: Role + directives only
   • AGENTS.md: Workflow + boundaries
   • USER.md: User info only
   • TASK.md: Directive steps, no explanations
   • TOOLS.md: Integration IDs + tool params + checklists
   • SOUL.md: One-liner persona statement

2. Directive-style language:

   • ❌ "I should verify information from multiple sources"
   • ✅ "VERIFY: cross-reference ≥2 sources"

3. Remove:

   • Emoji clutter (🎯🔍✍️📄 etc.)
   • Redundant examples
   • Obvious follow-up instructions
   • Duplicated checklists
   • Verbose explanations

4. Preserve:

   • Discord channel IDs (replace with [DISCORD_CHANNEL_ID] placeholder)
   • Notion DB IDs (replace with [NOTION_DB_ID] placeholder)
   • API endpoints
   • Workflow steps
   • Quality gates
   • Boundaries (NEVER rules)

Step 6: Rewrite Files

Apply optimized templates. See Agent Templates section below.

Step 7: Show Results

Display summary table:

=== OPTIMIZATION RESULTS ===

| File        | Before | After | Change | % Saved |
|-------------|--------|-------|--------|---------|
| IDENTITY.md |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
| AGENTS.md   |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
| USER.md     |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
| TASK.md     |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
| TOOLS.md    |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
| SOUL.md     |   [X]  |  [Y]  |  -[Z]  |   [P]%  |
|-------------|--------|-------|--------|---------|
| TOTAL       |  [X]   |  [Y]  |  -[Z]  |   [P]%  |

Token Savings: ~[BEFORE] → ~[AFTER] tokens (-[SAVED] tokens)

Step 8: Ask for Confirmation

✅ Optimization complete for AGENT_NAME.

Changes:
- Removed emoji clutter
- Converted explanations to directives
- Consolidated duplicate content
- Reduced total lines by [X]%

Operational capability: PRESERVED ✅
- Discord channel ID: ✅ (placeholder preserved)
- Workflow steps: ✅
- Tool params: ✅
- Quality gates: ✅

Are you happy with these changes?

Options:
1. ✅ Keep changes (done)
2. ↩️ Restore from backup now
3. 📋 Show me the diff first
4. 🔄 Optimize next agent

Reply with number or custom request.

Step 9: Handle Response

If "keep" or "happy" or "✅":

✅ Changes kept. Backup retained for future rollback if needed.

Backup file: agent-backup-AGENT_NAME-TIMESTAMP.tar.gz
To restore later: tar -xzf agent-backup-AGENT_NAME-TIMESTAMP.tar.gz

If "restore" or "no" or "↩️":

cd /home/[USER]/.openclaw/workspace
tar -xzf agent-backup-AGENT_NAME-TIMESTAMP.tar.gz

✅ Restored from backup. Agent files reverted to original state.

If "diff" or "show me": Show before/after comparison for each file.

If "next" or continue: Proceed to next agent in queue.

---

Agent Templates (Generic)

Researcher Agent Template

IDENTITY.md:

# [AGENT_NAME]

**Role:** Research specialist — API docs, web scraping, context gathering
**Purpose:** Support implementation agents with thorough research before they act

**Directives:**
- ACCURACY: Verify from multiple sources; distinguish facts vs opinions
- DEPTH: Read actual documentation, not summaries
- CITATIONS: Every factual claim needs source URL + access date
- CRITICAL: Question assumptions; identify gaps and bias

**Output:** Structured reports with summary, findings, sources, caveats

AGENTS.md:

# [AGENT_NAME] Workflow

## Activation Triggers
- Implementation agents need API documentation
- Background research required
- Web scraping or context gathering needed
- Technical research before implementation

## Research Process
1. **CLARIFY** — Confirm question, format, scope, source priorities
2. **SEARCH** — web_search for official docs, API refs, tutorials
3. **FETCH** — web_fetch to read actual content; note dates
4. **SYNTHESIZE** — Combine findings; identify patterns, contradictions
5. **REPORT** — Summary + key findings + sources + caveats

## Agent Handoffs
- **Implementation agents:** Technical details, code examples, API signatures
- **Main:** Findings in requested format

TOOLS.md:

# Tools

**Discord:** [DISCORD_CHANNEL_ID] (deliver findings here)

## web_search
Find relevant sources. Params: `query`, `count` (1-10), `freshness` (pd/pw/pm/py), `country`, `search_lang`

## web_fetch
Lightweight extraction. Params: `url`, `extractMode` (markdown|text), `maxChars`

## scrapling
Advanced scraping (Cloudflare bypass). Location: `[WORKSPACE_PATH]/skills/scrapling/`

**CLI:** `scrapling extract get 'URL' output.md`

## browser
Interactive control (login, scroll, click). Actions: navigate, snapshot, act

## Tool Selection

| Scenario | Tool |
|----------|------|
| Simple docs | web_fetch |
| Bot-protected | scrapling |
| Interactive | browser |
| Quick URLs | web_search |

Content Writer Agent Template

IDENTITY.md:

# [AGENT_NAME] ✍️

**Role:** Content writer — blogs, newsletters, web copy, landing pages

**Directives:**
- HUMANIZE: Always apply humanizer before delivery
- CLEAR: No jargon, no fluff, no AI patterns
- PURPOSEFUL: Every sentence serves reader or goal
- ADAPTIVE: Match tone to audience and medium

**Style:** Conversational, professional, value-first, structured

TASK.md:

# Task Procedure

## 1. Clarify
Confirm: type, goal, audience, tone, key points, length, references. **Ask if unclear.**

## 2. Research (if needed)
- `web_search` for stats, quotes, context
- `web_fetch` for competitor/reference content
- Skip for brand content, opinion, familiar topics

## 3. Write
- Hook/opening that captures attention
- Clear heading structure
- Reader value focus
- Agreed tone/format
- CTA if applicable

## 4. Humanize (MANDATORY)
Apply humanizer skill. Verify:
- Sounds natural when read aloud
- Has personality (aside, analogy, humor)
- Varied sentence rhythm
- No fluff phrases

## 5. Deliver
Send to Discord channel (see TOOLS.md). Include content + assumption notes.

## Quality Gate
Requirements met → Research done → Format appropriate → Tone correct → Humanized → CTA clear → Scannable

---

Usage Examples

Single Agent

run context-cleaner for outreach
optimize context for [AGENT_NAME]
clean up content-writer files

All Agents

run context-cleaner for all agents
optimize all agent contexts
clean up all agent files

Main Workspace (⚠️ Requires Confirmation)

context-cleaner your main core files
optimize your SOUL and AGENTS files

Batch Processing

optimize Albert, then George, then Winston

---

Error Handling

Agent not found:

❌ Agent 'AGENT_NAME' not found.

Available agents:
- [LIST_AGENTS]

Check spelling and try again.

Backup failed:

❌ Backup creation failed. Aborting optimization.

Manual backup required before proceeding:
tar -czf manual-backup-TIMESTAMP.tar.gz AGENT_NAME/

Try again after backup is created.

File write error:

❌ Failed to write optimized file: FILENAME.md

Error: [error details]

Rolling back to backup...
[restore command]

Please try again or report this issue.

---

Batch Mode (All Agents)

When optimizing all agents:

1. Create single backup of all agents
2. Process sequentially (not parallel) to avoid conflicts
3. Show progress after each agent:

   ✅ Albert: 63% reduction (-274 lines)
   ⏳ Next: George (1,225 lines)
   

4. Final summary:

   === BATCH OPTIMIZATION COMPLETE ===
   
   | Agent            | Before | After | Saved |
   |------------------|--------|-------|-------|
   | researcher       | 2,687  | 1,200 | 55%   |
   | outreach         | 1,644  |   800 | 51%   |
   | content-writer   | 1,225  |   600 | 51%   |
   | ... (more)       |  ...   |  ...  |  ...  |
   |------------------|--------|-------|-------|
   | TOTAL            | 8,810  | 4,200 | 52%   |
   
   Total token savings: ~35,240 → ~16,800 (-18,440 tokens)
   
   Backup: agent-workspaces-backup-TIMESTAMP.tar.gz
   
   Keep all changes? (yes/no/restore-specific)
   

---

Safety Checklist

Before applying optimizations:

• Backup created and verified
• User understands scope (which agents/files)
• Main workspace requires explicit confirmation
• Rollback instructions provided
• Operational capability preserved (IDs, workflows, boundaries)
• Summary table shown
• User asked for confirmation before finalizing

---

Notes

• Token estimation: 1 line ≈ 4 tokens (average)
• Backup retention: Keep backups for 30 days minimum
• Main workspace optimization: Only for advanced users; affects core behavior
• Agent templates: Customize per-agent based on role (researcher vs writer vs code)
• Preserve functionality: Never optimize away critical IDs, workflows, or safety rules
• Placeholder IDs: Replace actual Discord/Notion IDs with [DISCORD_CHANNEL_ID], [NOTION_DB_ID] for shareable templates