File Inbox

Bidirectional file management system for OpenClaw workspaces. Organizes, indexes, and retrieves files exchanged with users via any channel. Use when: a user...

Security Scan

The skill's code and runtime instructions match its stated purpose (indexing/moving/searching files in an inbox directory); it has no network calls, no extra credentials, and no install steps — but it does modify workspace files (moves/copies) so review before use.

Purpose & Capability

Name/description align with the provided scripts: init_inbox.sh, register_file.py, search_inbox.py, and inbox_stats.py implement directory initialization, registering (move/copy + index update), searching, and stats. There are no unrelated binaries, credentials, or external services requested.

Instruction Scope

SKILL.md restricts behavior to inbox operations and instructs running the included scripts. The scripts only operate on local filesystem (create inbox/, move/copy files, update INDEX.md and .meta.json). Caveat: register_file.py will move or copy whatever path is supplied and does not strictly validate that the source path is inside a trusted workspace — if an agent is given an arbitrary sensitive path it could be moved into the inbox. This is expected for a file-registration tool but is a potential misuse vector to consider.

Install Mechanism

No install spec or remote downloads; the skill is instruction-only with bundled scripts. Nothing is fetched from external URLs or installed to the system.

Credentials

The skill declares no required env vars or credentials. init_inbox.sh accepts an optional INBOX_DIR env var (sensible). No secrets or unrelated service tokens are requested or referenced.

Persistence & Privilege

Skill is not always-enabled and does not modify other skills or global agent configs. It does persist state inside the workspace (inbox/, INDEX.md, .meta.json) — which is normal for this purpose. Users should be aware the scripts will write/move files in the workspace and increment persistent IDs.

Assessment

This skill appears coherent for managing files in a workspace inbox. Before installing: (1) Review the register_file.py behavior because it will move/copy any file path you give it — avoid registering sensitive system files; (2) Ensure the workspace where the skill will run is trusted and backed up (INDEX.md and .meta.json will be modified); (3) If you want stricter protection, add input validation (e.g., require source paths be under the workspace) or run the script with --copy rather than move; (4) There are no network calls or credential requests in the code, but always review bundled scripts before granting an agent autonomous invocation.

Manage all files exchanged with users in inbox/ with a human-readable INDEX.md. Inbound = files received from user. Outbound = files generated by agent.

Setup

Run once to initialize the directory structure:

bash skills/file-inbox/scripts/init_inbox.sh

Creates inbox/, subdirectories, inbox/INDEX.md, and inbox/.meta.json. Idempotent — safe to re-run.

File Registration Workflow

When the user sends a file (inbound)

1. Determine the file's current path in workspace.
2. Run the registration script:

   python3 skills/file-inbox/scripts/register_file.py \
     --path <filepath> \
     --direction in \
     --sender "<name or channel>" \
     --tags "#tag1 #tag2" \
     --notes "Brief context"
   

3. Script moves file to inbox/inbound/YYYY-MM/ and updates INDEX.md.
4. Confirm the assigned ID to the user (e.g., "Saved as F-007").

When the agent generates a file (outbound)

1. Save the file to its destination first, then register:

   python3 skills/file-inbox/scripts/register_file.py \
     --path <filepath> \
     --direction out \
     --dest "<recipient name or channel>" \
     --tags "#tag1 #tag2" \
     --notes "What this file contains"
   

2. Script copies file to inbox/outbound/YYYY-MM/ and updates INDEX.md.

Auto-tagging

Tags are auto-assigned from file extension before the script runs. You may append additional context tags. See tagging-guide.md.

File Search & Retrieval

# Search by tag
python3 skills/file-inbox/scripts/search_inbox.py --tag research

# Search by file type
python3 skills/file-inbox/scripts/search_inbox.py --type pdf

# Search by direction
python3 skills/file-inbox/scripts/search_inbox.py --direction in

# Search by date range
python3 skills/file-inbox/scripts/search_inbox.py --date-from 2026-04-01 --date-to 2026-04-30

# Free-text search (matches ID, filename, notes, tags, sender)
python3 skills/file-inbox/scripts/search_inbox.py --query "논문"

# Combine filters
python3 skills/file-inbox/scripts/search_inbox.py --direction in --type csv --query "실험"

For quick lookups, read inbox/INDEX.md directly — it's a markdown table, grep-friendly.

INDEX.md Structure

# File Inbox

> Total: N files | Inbound: N | Outbound: N
> Last updated: YYYY-MM-DD

## Recent Files

| ID | Direction | Filename | Type | Tags | Sender/Dest | Date | Notes |
|----|-----------|----------|------|------|-------------|------|-------|
| F-007 | ⬇️ in | report.pdf | pdf | #research #논문 | Kim | 2026-04-11 | IEEE revision |
| F-006 | ⬆️ out | results.csv | csv | #experiment | → Kim | 2026-04-10 | Phase 2 |

• Rows are sorted newest-first.
• Keep the 50 most recent rows inline; older entries remain in the archive note at the bottom.

Inbox Statistics

python3 skills/file-inbox/scripts/inbox_stats.py

Shows: total counts, breakdown by type and direction, recent activity, storage size.

Maintenance

• Orphan check: Files in inbox/ not listed in INDEX.md are orphans. Register or remove them.
• Old file cleanup: Files older than 90 days may be archived. Ask user before moving.
• Index rebuild: If INDEX.md is corrupted, re-run register_file.py for each file in inbox/.

Integration with Channels

See integration-guide.md for:

• Telegram file handling (document vs. photo messages)
• How to extract sender name from channel context
• Recommended AGENTS.md additions

Best Practices

1. Register files immediately after receiving or generating them.
2. Always include --notes with enough context to identify the file months later.
3. Use Korean tags naturally — the index is bilingual-ready.
4. When the user asks for a file, search INDEX.md first before scanning the filesystem.
5. Never delete registered files without user confirmation; use notes to mark as obsolete.