| 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:
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
.venv/bin/python skills/file-operator/scripts/file_ops.py --base-dir /workspace \
read --path /etc/passwd
- 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).