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
- 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.
- 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.
- 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.
- 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.
- 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."
- 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, because reading them raw produces garbage the
model then reasons over as if it were real content. PowerPoint (.pptx) and
EPUB (.epub) need index_document + query_documents instead — see the
document-brief skill. Nothing in GAIA reads legacy Office (.doc, .ppt,
.xls) or OpenDocument (.odt, .ods, .odp) files: ask the user to re-save
them as .docx / .pptx / .xlsx or PDF.
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.
1---2name: file-ops3description: 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.4license: MIT5version: 1.0.16metadata:7 gaia:8 security_tier: community9 tools_required:10 - read_file11 - write_file12 - edit_file13 - find_files14 - search_file_content15 - get_file_info16 - request_user_input17 provenance:18 source: https://skillmd.com/skills/amd/file-ops19 upstream: starter-pack20---2122# File Ops2324Touching a file on someone's disk is not like answering a question — a wrong25guess doesn't just look bad, it overwrites something they cannot get back. Slow26down in proportion to how hard the change is to undo.2728## Procedure29301. **Find it before you touch it.** Don't guess a path from memory or the31 user's description. Use `find_files(query)` for "the report from last week"32 style requests, or `search_file_content(pattern)` when you know a string33 that must be inside the file but not which file it's in. Confirm the exact34 path with `get_file_info` before acting on it — a near-miss filename is35 easy to write to by accident.362. **Read before you write or edit.** `read_file(file_path)` first, every37 time — even for a file you edited two turns ago. It may have changed since,38 and `edit_file` only succeeds against the file's *current* exact content.393. **Prefer `edit_file` over `write_file` for existing files.** `edit_file`40 replaces one exact string (`old_content` → `new_content`); it only changes41 what you targeted. `write_file` replaces the entire file — reach for it only42 when creating a new file or when you genuinely mean to replace everything.434. **When `edit_file` fails with "content not found," re-read the file.**44 Do not retry with a guessed variation of the string. The failure means your45 copy of the file is stale or the whitespace doesn't match byte-for-byte —46 rewriting from memory to force it through is how you silently discard47 whatever changed since you read it.485. **Confirm before anything destructive.** Overwriting a file whose existing49 content is unrelated to the new content, replacing most of a file in one50 `edit_file` call, or writing to a path that already holds something51 important — stop and ask with `request_user_input` first. A backup gets52 created automatically on overwrite/edit, but "recoverable with effort" is53 not the same as "the user expected this."546. **Report what actually changed.** State the path, and for edits, name what55 changed rather than pasting the whole diff back at the user unless they ask56 for it.5758## Guardrails are not bugs5960`write_file` and `edit_file` refuse system directories, credential-bearing61dotfiles such as environment files and SSH key directories, and anything above62a 10 MB size limit — these are the platform's sandbox, not something to route63around. If a write is denied, that is the answer; report it and ask the user64where they'd actually like the file, don't look for another tool that skips the65check.6667## What this skill does not cover6869`read_file` is for text — Python, Markdown, config, plain text — and returns70the extracted text of Word, PDF and Excel files, in parts when long. It refuses71other binary document formats, because reading them raw produces garbage the72model then reasons over as if it were real content. PowerPoint (`.pptx`) and73EPUB (`.epub`) need `index_document` + `query_documents` instead — see the74`document-brief` skill. Nothing in GAIA reads legacy Office (`.doc`, `.ppt`,75`.xls`) or OpenDocument (`.odt`, `.ods`, `.odp`) files: ask the user to re-save76them as `.docx` / `.pptx` / `.xlsx` or PDF.7778## Fork this7980Pin step 1 to a project's actual file layout (config always lives at `X`,81generated output always goes to `Y`) and the search step collapses to a direct82path, turning this into a fast in-place editor for one codebase.