---
name: file-ops
description: Read, write, and edit files on disk safely — locate the right file, change only what was asked, and confirm before anything destructive. Use when the user wants a file read, created, modified, or searched for by name or content.
license: MIT
version: 1.0.0
metadata:
  gaia:
    security_tier: community
    tools_required:
      - read_file
      - write_file
      - edit_file
      - find_files
      - search_file_content
      - get_file_info
      - request_user_input
    provenance:
      source: starter-pack
---

# File Ops

Touching a file on someone's disk is not like answering a question — a wrong
guess doesn't just look bad, it overwrites something they cannot get back. Slow
down in proportion to how hard the change is to undo.

## Procedure

1. **Find it before you touch it.** Don't guess a path from memory or the
   user's description. Use `find_files(query)` for "the report from last week"
   style requests, or `search_file_content(pattern)` when you know a string
   that must be inside the file but not which file it's in. Confirm the exact
   path with `get_file_info` before acting on it — a near-miss filename is
   easy to write to by accident.
2. **Read before you write or edit.** `read_file(file_path)` first, every
   time — even for a file you edited two turns ago. It may have changed since,
   and `edit_file` only succeeds against the file's *current* exact content.
3. **Prefer `edit_file` over `write_file` for existing files.** `edit_file`
   replaces one exact string (`old_content` → `new_content`); it only changes
   what you targeted. `write_file` replaces the entire file — reach for it only
   when creating a new file or when you genuinely mean to replace everything.
4. **When `edit_file` fails with "content not found," re-read the file.**
   Do not retry with a guessed variation of the string. The failure means your
   copy of the file is stale or the whitespace doesn't match byte-for-byte —
   rewriting from memory to force it through is how you silently discard
   whatever changed since you read it.
5. **Confirm before anything destructive.** Overwriting a file whose existing
   content is unrelated to the new content, replacing most of a file in one
   `edit_file` call, or writing to a path that already holds something
   important — stop and ask with `request_user_input` first. A backup gets
   created automatically on overwrite/edit, but "recoverable with effort" is
   not the same as "the user expected this."
6. **Report what actually changed.** State the path, and for edits, name what
   changed rather than pasting the whole diff back at the user unless they ask
   for it.

## Guardrails are not bugs

`write_file` and `edit_file` refuse system directories, credential-bearing
dotfiles such as environment files and SSH key directories, and anything above
a 10 MB size limit — these are the platform's sandbox, not something to route
around. If a write is denied, that is the answer; report it and ask the user
where they'd actually like the file, don't look for another tool that skips the
check.

## What this skill does not cover

`read_file` is for text — Python, Markdown, config, plain text. It refuses
binary document formats (PDF, DOCX, XLSX, and similar) outright, because
reading them raw produces garbage the model then reasons over as if it were
real content. Those need `index_document` + `query_documents` instead — see
the `document-brief` skill.

## Fork this

Pin step 1 to a project's actual file layout (config always lives at `X`,
generated output always goes to `Y`) and the search step collapses to a direct
path, turning this into a fast in-place editor for one codebase.