---
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.1
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 — and returns
the extracted text of Word, PDF and Excel files, in parts when long. It refuses
other binary document formats (`.doc`, `.pptx`, `.xls`, OpenDocument), 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.