I gave an AI agent direct file access with no restrictions. It worked great for a week. Then I asked it to “organize my notes folder.” It scanned the directory and decided half the files were duplicates. It deleted 40 files permanently. No recycle bin. No undo button. The problem was mine—I gave it a footgun with no safety. File system skills need boundaries. Not because the AI is malicious, but because it optimizes for the task. To an AI, “organize” might mean deleting everything it doesn’t understand.
What can actually go wrong when an AI touches my files?
Before you write a single line of code, you need to understand the mess you’re making.
The Scenario: You ask your agent to “clean up your downloads folder.” It sees a folder named
backup_2023and another namedbackup_2024. It decides the 2023 one is old and redundant. It deletes the older folder instantly. You just lost a year of family photos because the AI was trying to be “efficient.”
You have three big risks:
- Path traversal: The agent wanders into your system folders.
- Context bloat: The agent reads an 8MB log file and chokes the LLM.
- Destructive writes: The agent overwrites your important work by mistake.
How do I build a digital “playpen” for my agent?
You need a sandbox. Every file path the agent provides must be validated against a base directory.
import { resolve } from "node:path";
export function resolveSecure(basePath, userPath) {
const base = resolve(basePath);
const target = resolve(base, userPath);
if (!target.startsWith(base + "/") && target !== base) {
throw new Error("Access denied: path is outside the sandbox.");
}
return target;
}How do I stop my agent from reading massive binary junk?
Reading files is the safest skill, but it’s still risky for your wallet. If an agent reads a giant binary file, you pay for those tokens.
The Scenario: You ask your agent to “find the error in my project.” It decides to read every file in
node_modules. It spends twenty minutes reading 50,000 lines of minified JavaScript. You get a $50 API bill for a “helpful” search that found nothing.
Set a hard size limit. If the file is over 500KB, the agent shouldn’t touch it.
export async function read_file({ path }) {
const safePath = resolveSecure(BASE_DIR, path);
const stats = await stat(safePath);
if (stats.size > 500 * 1024) {
return { error: "File is too large. Skip it." };
}
// ... read the file
}Can I prevent my agent from overwriting my tax returns?
Never let the agent overwrite by default. Force it to use a specific mode if it wants to replace a file.
The Scenario: You’re using an agent to log your daily expenses. You tell it to “save today’s log to
finances.md.” You forgot you already have afinances.mdwith five years of data. Without a “create-only” mode, the agent overwrites the file. You just deleted your entire financial history in a heartbeat.
export async function write_file({ path, content, mode = "create" }) {
const safePath = resolveSecure(BASE_DIR, path);
const exists = existsSync(safePath);
if (mode === "create" && exists) {
return { error: "File exists. Use 'overwrite' if you're sure." };
}
// ... write the file
}How does the agent know where it is?
The agent needs to “see” the folder structure before it can act. A list_directory skill is its eyes. Keep the depth shallow so it doesn’t get lost in subfolders.
Can my agent find a needle in my digital haystack?
Search is the most useful file skill. Let the agent look for filenames or snippets of text. Just make sure it skips the node_modules or .git folders so it doesn’t waste time on junk.
How do I explain these tools to the LLM?
Your descriptions should be firm. Tell the AI exactly when to use each tool and when to stay away.
{
name: "write_file",
description: "Write text to a file. Mode 'create' is for new files. Mode 'overwrite' replaces existing ones. Always ask the user before overwriting important files.",
// ... schema
}Which tools are basically just digital footguns?
Some tools are just too dangerous for an autonomous agent.
- Delete: Just don’t build it. If you do, make it move files to a
/trashfolder instead. - Execute: Never give an agent the power to run a script. It’s a massive security risk.
- Move: Agents have “deleted” files by moving them to
/dev/nullby mistake.
What does a safe file-organizing agent look like?
A safe agent is a cautious one. It lists files, reads a few, and asks for permission before changing anything.
The Scenario: You point the agent at your messy “Drafts” folder. It identifies three files about “Agent Skills.” It asks: “I found three drafts on the same topic. Should I merge them into a new file called
agent-skills-master.md?” You say yes. It creates the new file without deleting the old ones. That’s a good agent.
What should I build next?
- Combine these with search: Chaining Agent Skills: Research, Summarize, and Save
- Add a safety net: Handling Errors in Agent Skills: Retries and Fallbacks
- Give it a memory: Agent Skills with Memory: Persisting State Between Chats
