large-file-write-heredoc
Reliable fallback technique for writing large file contents when write_file and shell_agent both fail with 'unknown error' due to payload size limits — uses run_shell with a Python heredoc to bypass tool constraints.
- License 许可
- MIT
- 所属仓库
- AG064/OpenSpace
- 最近更新
- 2026-10-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- large-file-write-heredoc
- description
- Reliable fallback technique for writing large file contents when write_file and shell_agent both fail with 'unknown error' due to payload size limits — uses run_shell with a Python heredoc to bypass tool constraints.
02 资源文件 1
- 其他.skill_id39 B
03 SKILL.md 正文
Large File Write Fallback
Problem
When writing large files (typically several KB or more), two common tools may
fail with unknown error due to internal payload size limits:
write_file— has a maximum content size it can handle in a single call.shell_agent— may also hit payload limits when the task description includes large inline content.
Solution
Use run_shell with a Python heredoc pattern. This streams the file
content through stdin directly into Python's open(), bypassing the payload
constraints of the other tools.
Template
python3 - << 'EOF'
content = """<FILE CONTENTS HERE>"""
with open("<TARGET PATH>", "w") as f:
f.write(content)
EOF
Pass this as the command parameter to run_shell.
Step-by-Step Instructions
-
Attempt the normal write using
write_filefirst. If it succeeds, you are done. -
If
write_filefails (especially withunknown erroror a timeout on large content), do NOT retry withshell_agentusing inline content — it will likely fail for the same reason. -
Use the
run_shellheredoc fallback:- Embed the full file content inside a Python triple-quoted string.
- Specify the target path inside the
open()call. - Pass the entire block as the
commandtorun_shell.
-
Escape carefully inside the heredoc:
- Backslashes that should be literal in the file must be doubled (
\\). - Triple-quotes inside the content must be escaped (
\"\"\"). - The heredoc delimiter
EOFmust not appear on a line by itself inside the content (rename it toPYEOForFILEEOFif needed).
- Backslashes that should be literal in the file must be doubled (
-
Verify the write by following up with a
run_shellcall such as:wc -l <TARGET PATH> && head -5 <TARGET PATH>
Full Example
Suppose you need to write a large TypeScript file to
src/components/Dashboard.ts:
python3 - << 'PYEOF'
content = """import { foo } from './foo';
export interface DashboardData {
title: string;
items: string[];
}
export function createDashboard(data: DashboardData): string {
return `<div>${data.title}</div>`;
}
"""
with open("src/components/Dashboard.ts", "w") as f:
f.write(content)
PYEOF
Pass the above (without the surrounding code fence) as the command
argument to run_shell.
When to Use This Pattern
| Situation | Recommended tool |
|---|---|
| Small file (< ~2 KB) | write_file |
| Medium file, no errors yet | write_file (try first) |
Large file or write_file failed |
run_shell + Python heredoc |
shell_agent also fails on large inline content |
run_shell + Python heredoc |
Notes
- This pattern works for any text-based file (TypeScript, Python, JSON, YAML, Markdown, etc.).
- For binary files, adapt the approach to use
base64decoding inside the Python script. - The heredoc delimiter (
EOF,PYEOF,FILEEOF) can be any string not present as a standalone line in your content — choose accordingly. - This technique is also useful when content contains characters that would
need heavy shell escaping in a plain
echoorprintfapproach.
04 同仓库更多 Skills
write-special-chars-ts-check
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, plus a reliable TypeScript type-checking step that filters output to only the newly-written files to avoid being misled by pre-existing errors.
write-special-chars-readback
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) using a Python heredoc script, with mandatory post-write verification via read_file and cleanup of /tmp helper scripts.
write-special-chars-heredoc
Workaround for write_file failures caused by special characters (apostrophes, backticks, template literals) by using a Python heredoc script executed via shell.
worldmonitor-reference
Curated architecture index of the WorldMonitor open-source dashboard. Reference for extracting patterns — vanilla TypeScript, Panel class hierarchy, service layer, CSS grid, API edge functions, refresh scheduler, and 60+ data source integrations.
virtual-list
Implement efficient virtual scrolling for rendering large lists with DOM recycling, chunk-based rendering, and performance optimizations
verify-directory-structure
Diagnose and resolve file access issues by first verifying the directory structure.