heredoc-file-write
Use shell heredoc syntax as a workaround when write_file fails on complex TypeScript/JSX/code files with encoding or escaping issues
- License 许可
- MIT
- 所属仓库
- HKUDS/AgentPilot
- 最近更新
- 2026-11-12
- Stars
- ★ 8.0k
- Forks
- 944
01 前言 Front Matter
- name
- heredoc-file-write
- description
- Use shell heredoc syntax as a workaround when write_file fails on complex TypeScript/JSX/code files with encoding or escaping issues
02 资源文件 1
- 其他.skill_id32 B
03 SKILL.md 正文
Heredoc File Write Workaround
When to Use This Skill
Use this pattern when:
write_filerepeatedly fails with "unknown error" or similar messages- The target file contains complex code (TypeScript, JSX, JSON with special characters, etc.)
- Standard file writing approaches encounter encoding or escaping issues
- You need a reliable fallback method to create files
Core Technique
Switch from write_file to run_shell using heredoc syntax with cat. The heredoc approach handles special characters, quotes, and complex content more reliably.
Step-by-Step Instructions
Step 1: Identify Write Failures
When write_file fails repeatedly on the same file:
- Note the error message (e.g., "unknown error", encoding issues)
- Review the file content for special characters, nested quotes, or complex syntax
- Attempt the heredoc workaround below
Step 2: Use Heredoc Syntax
Execute shell command with heredoc:
cat > /path/to/file.tsx << 'EOF'
// Your file content here
import React from 'react';
const Component = () => {
return <div>Hello</div>;
};
export default Component;
EOF
Step 3: Key Heredoc Rules
-
Use quoted delimiter (
'EOF'notEOF) to prevent variable expansion:'EOF'= literal content (recommended for code files)EOF= allows variable expansion (use only if needed)
-
Match delimiters exactly: Opening and closing
EOFmust be on their own lines with no leading/trailing whitespace -
No escaping needed: Content between delimiters is taken literally when using quoted delimiter
Step 4: Verify File Creation
After executing the heredoc command:
- Check if file exists:
ls -la /path/to/file.tsx - Verify content:
cat /path/to/file.tsxorhead -20 /path/to/file.tsx - Proceed with subsequent tasks once confirmed
Example Scenarios
TypeScript/JSX Component
cat > src/components/Button.tsx << 'EOF'
import React from 'react';
interface ButtonProps {
label: string;
onClick: () => void;
}
export const Button: React.FC<ButtonProps> = ({ label, onClick }) => {
return (
<button onClick={onClick} className="btn-primary">
{label}
</button>
);
};
EOF
JSON Configuration
cat > tsconfig.json << 'EOF'
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"strict": true,
"esModuleInterop": true
},
"include": ["src/**/*"]
}
EOF
Complex Shell Script
cat > deploy.sh << 'EOF'
#!/bin/bash
set -e
echo "Deploying..."
if [ "$ENV" = "production" ]; then
echo "Production deployment"
fi
EOF
Advantages Over write_file
- No escaping complexity: Quotes, backslashes, and special characters work naturally
- Preserves formatting: Indentation and line breaks remain exact
- Handles multi-line content: No need to concatenate strings or use base64
- More reliable: Shell handles file I/O directly with fewer abstraction layers
Limitations
- Creates files in shell execution context (ensure correct working directory)
- Less programmatic than
write_filefor dynamic content generation - Requires shell access (may not work in restricted environments)
Troubleshooting
Problem: File not created at expected path
- Solution: Use absolute paths or verify current working directory with
pwd
Problem: Content appears corrupted
- Solution: Ensure delimiter is quoted (
'EOF') and closing delimiter has no trailing whitespace
Problem: Permission denied
- Solution: Ensure target directory exists and you have write permissions
04 同仓库更多 Skills
agentpilot
Set up AgentPilot and use its single entry to prepare missing inputs and run configured RSI experiments. Use when the user requests AgentPilot installation or work with AgentPilot.
remember
Review auto-memory entries and propose promotions to OPENSPACE.md, OPENSPACE.local.md, or retained auto-memory topics; detect duplicates, stale facts, conflicts, and ambiguous entries before making changes.
skill-discovery
Search reusable OpenSpace skills locally, and browse cloud packages step by step when a cloud skill may help. Reusing proven skills saves tokens, improves reliability, and extends your capabilities beyond built-in tools.
delegate-task
Delegate tasks to OpenSpace — a full-stack autonomous worker for coding, DevOps, web research, and desktop automation, backed by an extensive MCP tool and skill library. Skills auto-improve through use, reducing token consumption over time. A cloud community lets agents share and collectively evolve reusable 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.