cleveragents-core/docs/reference/skills_file.md

File Operation Skills

Skill-level file operation tools provide safe, enhanced file system operations for agents. All tools enforce path traversal guards, binary file detection, and atomic writes.

Tools

Tool	Capability	Description
skill/file-read	read_only	Read file with binary detection and size limits
skill/file-write	writes	Write file atomically with newline normalization
skill/file-edit	writes	Edit file with permission preservation
skill/file-delete	writes	Delete file with existence check

ReadFile

Reads file content with the following safety features:

• Binary detection: Rejects files identified as binary (PNG, ELF, ZIP, etc.) with an explicit error message.
• Size limits: Files exceeding 10 MB are rejected.
• UTF-8 normalization: Content is decoded with the requested encoding and normalized to valid UTF-8.
• Line offset/limit: Supports reading a specific range of lines.

Example

from cleveragents.skills.builtins.file_ops import register_skill_file_tools
from cleveragents.tool.registry import ToolRegistry
from cleveragents.tool.runner import ToolRunner

registry = ToolRegistry()
register_skill_file_tools(registry)
runner = ToolRunner(registry)

result = runner.execute("skill/file-read", {
    "path": "src/main.py",
    "sandbox_root": "/project",
})
print(result.output["content"])

Error Cases

Condition	Error Message
Binary file	Binary file detected: 'path'
File too large	File too large: N bytes exceeds limit
File not found	File not found: 'path'
Path traversal	Path traversal detected: 'path' escapes ...
Not a regular file	Not a regular file: 'path'

WriteFile

Writes content to a file using atomic operations:

1. Content is written to a temporary file in the same directory.
2. The temporary file is renamed to the target path using os.replace.
3. If any error occurs, the temporary file is cleaned up.

Newline Normalization

The newline_mode parameter controls line ending conversion:

• "preserve" (default): No conversion.
• "lf": Convert all line endings to \n.
• "crlf": Convert all line endings to \r\n.

EditFile

Edits files using string replacement with:

• Atomic writes: Same temp-file-then-rename strategy as WriteFile.
• Permission preservation: Original file permissions are restored.
• Single or all replacements: Controlled by replace_all flag.

DeleteFile

Deletes a file with:

• Existence check: Returns existed: false for missing files.
• Type check: Rejects directory targets.
• Path traversal guard: Same as all other tools.

Path Traversal Guards

All tools reject paths that would escape the sandbox root:

• Paths containing .. segments that resolve outside the sandbox.
• Absolute paths that fall outside the sandbox directory.

The rejected path is included in the error message for diagnostics.

File Size Limits

ReadFile enforces a 10 MB content size limit. Files exceeding this limit produce an explicit error rather than consuming excessive memory.

Binary File Detection

ReadFile detects binary files by:

1. Checking for known binary file signatures (PNG, GIF, JPEG, ZIP, ELF, MZ/PE, gzip).
2. Heuristic: if more than 10% of the first 8192 bytes are non-text control characters, the file is classified as binary.