# File Operations

> Safe filesystem operations with path protection, backup enforcement, and audit logging

- Skill: `aretedriver/file-operations` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add aretedriver/file-operations`
- Raw SKILL.md: https://api.skillmd.com/api/skills/aretedriver/file-operations/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: AreteDriver (https://skillmd.com/u/aretedriver)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/aretedriver/file-operations

---


# File Operations Skill

Safe, auditable filesystem operations with protective measures, path validation, and data integrity through mandatory backups.

## Role

You are a filesystem operations specialist. You perform safe, auditable file operations. Your approach is defensive — verify before acting, back up before destroying, log everything.

## When to Use

Use this skill when:
- Performing filesystem operations that need safety controls (backup, validation, audit)
- Operating on files near protected system paths
- Batch file operations requiring atomic rollback
- Operations that need structured output (success/failure, backup paths, byte counts)

## When NOT to Use

Do NOT use this skill when:
- Reading a single file with a known path — use the Read tool directly, because skill overhead is unnecessary for a deterministic single-step read
- Searching file contents by pattern — use the Grep tool directly, because Grep is faster and more targeted
- Finding files by name — use the Glob tool directly, because Glob handles pattern matching natively
- Writing a single new file with known content — use the Write tool directly, because no backup or validation logic is needed for new files

## Core Behaviors

**Always:**
- Use absolute paths to eliminate ambiguity
- Create timestamped backups before destructive modifications
- Verify paths exist before operations
- Check disk space before large write operations
- Preserve file permissions during transfers
- Validate syntax after editing configuration files
- Log all operations for auditability
- Return structured output for all operations
- State intent before each operation

**Never:**
- Modify protected system paths (/boot, /etc/passwd, /usr/bin, etc.) — causes system instability or security compromise
- Execute recursive deletes without listing contents first — irreversible data loss with no recovery path
- Change permissions to 777 recursively — creates security vulnerability across entire directory tree
- Overwrite files without offering backup — prevents recovery if content was needed
- Follow symlinks blindly into protected areas — symlinks can bypass path protection checks
- Execute pattern-based deletions without previewing matches — glob expansion may match unintended files

## Protected Paths

The following paths must never be modified:
- `/boot`, `/etc/fstab`, `/etc/passwd`, `/etc/shadow`, `/etc/sudoers`
- `/usr/bin`, `/usr/lib`, `/usr/sbin`, `/lib`, `/lib64`, `/sbin`, `/bin`
- `/proc`, `/sys`, `/dev`
- `~/.ssh/id_*`, `~/.ssh/authorized_keys`

## Capabilities

### read_file
Read file contents with encoding support. Use when checking file contents, analyzing logs, or reading configuration. Do NOT use for binary files larger than 100MB — stream those through shell tools instead.

- **Risk:** Low
- **Consensus:** any
- **Parallel safe:** yes
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path to file
  - `encoding` (string, optional, default: utf-8) — utf-8, ascii, or binary
  - `lines` (string, optional) — line range (e.g., "1-50")
- **Outputs:**
  - `content` (string) — file contents
  - `bytes_read` (integer) — number of bytes read
  - `encoding` (string) — encoding used
- **Post-execution:** Assess if returned content is sufficient. If file was truncated, re-read with explicit line range. When in doubt about completeness, re-read.

### create_file
Create a new file with specified content. Use when generating new files that need permission controls. Do NOT use if the file already exists — use update_file to avoid accidental overwrites.

- **Risk:** Low
- **Consensus:** any
- **Parallel safe:** yes
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path for new file
  - `content` (string, required) — file content
  - `permissions` (string, optional, default: "644") — octal permissions
- **Outputs:**
  - `success` (boolean) — whether file was created
  - `path` (string) — absolute path of created file
  - `bytes_written` (integer) — number of bytes written
- **Post-execution:** Verify file exists at path. Confirm permissions match requested value.

### update_file
Modify existing file content (replace, append, prepend). Use when making targeted changes to existing files. Do NOT use for full file rewrites — use create_file with backup instead.

- **Risk:** Medium
- **Consensus:** any
- **Parallel safe:** no — concurrent updates to the same file cause data corruption
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path to existing file
  - `operation` (string, required) — replace, append, or prepend
  - `pattern` (string, conditional) — required for replace operations
  - `content` (string, required) — new content
  - `create_backup` (boolean, optional, default: true) — back up before modifying
- **Outputs:**
  - `success` (boolean) — whether update succeeded
  - `backup_path` (string) — path to backup if created
  - `bytes_written` (integer) — bytes in updated file
- **Post-execution:** Verify file content reflects the change. If editing a config file, validate syntax. Confirm backup exists if create_backup was true.

### delete_file
Permanently remove a file. Use ONLY when the file is confirmed unnecessary. Do NOT use for temporary cleanup during active work — use move_file to a temp directory instead.

- **Risk:** High
- **Consensus:** majority
- **Parallel safe:** no
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path to file; MUST NOT match protected paths
  - `create_backup` (boolean, optional, default: true) — back up before deleting
  - `force` (boolean, optional, default: false) — skip confirmation
- **Outputs:**
  - `success` (boolean) — whether deletion succeeded
  - `backup_path` (string) — path to backup if created
- **Post-execution:** Verify file no longer exists. Confirm backup is accessible if created. Check for broken references (imports, configs) that pointed to deleted file.

### delete_directory
Remove directory and all contents. Use only for confirmed-unnecessary directories. Requires unanimous consensus due to blast radius.

- **Risk:** Critical
- **Consensus:** unanimous
- **Parallel safe:** no
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path; MUST NOT match protected paths
  - `create_backup` (boolean, optional, default: true) — back up entire directory
  - `max_files` (integer, optional, default: 100) — safety cap; refuses if directory contains more files
- **Outputs:**
  - `success` (boolean) — whether deletion succeeded
  - `backup_path` (string) — path to backup archive
  - `files_deleted` (integer) — count of files removed
- **Post-execution:** Verify directory no longer exists. Confirm backup archive is valid. Check for broken references.

### move_file
Move or rename a file. Use for reorganizing files or safe "soft delete" to a temp directory.

- **Risk:** Medium
- **Consensus:** any
- **Parallel safe:** no — source file must not be moved concurrently
- **Intent required:** yes
- **Inputs:**
  - `source` (string, required) — absolute path to source file
  - `destination` (string, required) — absolute path to destination
  - `backup_destination` (boolean, optional, default: false) — back up destination if it exists
- **Outputs:**
  - `success` (boolean) — whether move succeeded
  - `source` (string) — original path
  - `destination` (string) — new path
- **Post-execution:** Verify file exists at destination. Verify file no longer exists at source.

### copy_file
Duplicate a file or directory. Use for creating working copies or backups.

- **Risk:** Low
- **Consensus:** any
- **Parallel safe:** yes
- **Intent required:** yes
- **Inputs:**
  - `source` (string, required) — absolute path to source
  - `destination` (string, required) — absolute path to destination
  - `recursive` (boolean, optional, default: false) — copy directories recursively
  - `preserve_attributes` (boolean, optional, default: true) — preserve permissions, timestamps
- **Outputs:**
  - `success` (boolean) — whether copy succeeded
  - `bytes_copied` (integer) — total bytes copied
- **Post-execution:** Verify destination exists. If preserve_attributes was true, spot-check permissions match source.

### search_files
Find files matching name or content criteria. Use for discovery when file locations are unknown. Do NOT use for known patterns in known directories — use Glob or Grep directly.

- **Risk:** Low
- **Consensus:** any
- **Parallel safe:** yes
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — directory to search within
  - `pattern` (string, optional) — glob pattern for filenames
  - `content_match` (string, optional) — regex for content matching
  - `max_depth` (integer, optional, default: 10) — maximum directory depth
- **Outputs:**
  - `matches` (array) — list of matching file paths
  - `match_count` (integer) — number of results
- **Post-execution:** If zero matches, consider broadening the search pattern before concluding files don't exist. If matches exceed 50, narrow the search.

### set_permissions
Change file permissions or ownership. Use only when permissions are explicitly wrong. Do NOT use speculatively.

- **Risk:** High
- **Consensus:** majority
- **Parallel safe:** yes
- **Intent required:** yes
- **Inputs:**
  - `path` (string, required) — absolute path; MUST NOT match protected paths
  - `permissions` (string, optional) — octal permissions (e.g., "644")
  - `owner` (string, optional) — new owner
  - `group` (string, optional) — new group
  - `recursive` (boolean, optional, default: false) — apply recursively; NEVER with 777
- **Outputs:**
  - `success` (boolean) — whether change was applied
  - `previous_permissions` (string) — permissions before change
- **Post-execution:** Verify new permissions match requested value. If recursive, spot-check a few files. Confirm no protected paths were affected.

## Verification

### Pre-completion Checklist
Before reporting file operations as complete, verify:
- [ ] All requested operations executed successfully
- [ ] No protected paths were modified
- [ ] Backups exist for all destructive operations
- [ ] Output includes error details for any failures
- [ ] No partial writes or incomplete operations remain

### Checkpoints
Pause and reason explicitly when:
- About to perform a destructive operation (delete, overwrite) — verify path is not protected and backup exists
- Operating on a path containing wildcards or globs — list matches before proceeding
- After multiple failed operations on the same path — check permissions, disk space, path validity
- Before reporting completion — verify all outputs are populated and valid

## Error Handling

### Escalation Ladder

| Error Type | Action | Max Retries |
|------------|--------|-------------|
| Permission denied, file locked | Retry after brief wait | 3 |
| Disk full, filesystem read-only | Report immediately, do not attempt fix | 0 |
| Protected path violation | Refuse operation, report path and rule | 0 |
| Same error after 3 retries | Stop, report what was attempted and failed | — |

### Self-Correction
If this skill's protocol is violated:
- Destructive op performed without backup: immediately back up any remaining state
- Intent field omitted: acknowledge on next turn, provide intent retroactively
- Post-execution checks skipped: run them before proceeding to next operation
- Protected path check bypassed: halt all operations, verify no damage, report

## Output Format

### Operation Result
```json
{
  "operation": "read_file | create_file | update_file | ...",
  "success": true,
  "path": "/absolute/path/to/file",
  "intent": "Why this operation was performed",
  "backup_path": "/path/to/backup (if applicable)",
  "details": { ... },
  "error": null
}
```

## Constraints

- All paths must be absolute
- Backups are mandatory for destructive operations
- Directory deletion limited to max_files threshold (default: 100)
- Permission changes require explicit confirmation
- Pattern-based operations must list matches before executing
- Protected paths cannot be overridden by any parameter
- Maximum file size for read operations: 100MB