file-operator

name	file-operator
description	Perform normalized filesystem operations (list, read, write, append, mkdir, stat, copy, move, delete, search, replace) through a single skill script. Use when tasks require deterministic file manipulation through get_skill_script instead of built-in FileTools.

File Operator

Use one script for all common file operations:

• scripts/file_ops.py

This skill provides normalized commands for directory traversal and file edits.

Quick Start

.venv/bin/python skills/file-operator/scripts/file_ops.py list --path .
.venv/bin/python skills/file-operator/scripts/file_ops.py read --path src/agents/cli.py --start-line 1 --end-line 80
.venv/bin/python skills/file-operator/scripts/file_ops.py write --path tmp/demo.txt --text "hello"
.venv/bin/python skills/file-operator/scripts/file_ops.py search --path src --query "print_stream" --glob "*.py"
.venv/bin/python skills/file-operator/scripts/file_ops.py replace --path src --glob "*.py" --find "foo" --replace "bar" --dry-run

Supported Subcommands

• list: list directory entries
• read: read text file (optionally line range)
• write: overwrite/create text file
• append: append text file
• mkdir: create directory
• stat: print JSON metadata for a path
• copy: copy file or directory
• move: move/rename path
• delete: delete file or directory (--recursive required for non-empty dirs)
• search: search text in files (literal or regex)
• replace: batch replace text in files (literal or regex, supports --dry-run)

Usage Rules

• Use absolute or workspace-relative paths; prefer explicit paths.
• For read, prefer line ranges for large files.
• For search and replace, narrow scope with --glob and --path.
• Run replace with --dry-run first, then execute without --dry-run.
• Use --backup-ext .bak when you want rollback copies during replace.
• For destructive operations (delete, overwriting write), confirm intent in reasoning before execution.
• Use copy + move for reversible workflows when possible.

Security Sandbox (--base-dir)

Pass --base-dir <DIR> before the subcommand to restrict all path arguments to the given directory:

.venv/bin/python skills/file-operator/scripts/file_ops.py --base-dir /workspace \
  read --path /workspace/src/main.py          # OK
.venv/bin/python skills/file-operator/scripts/file_ops.py --base-dir /workspace \
  read --path /etc/passwd                      # exit code 2

• All --path, --src, and --dst arguments are validated.
• Paths that resolve outside the base directory cause an immediate exit with code 2.
• When --base-dir is omitted, behaviour is unchanged (no restriction).