---
name: heredoc-file-write-8fb7422645c4
description: Use shell heredoc syntax as a workaround when write_file fails on complex TypeScript/JSX/code files with encoding or escaping issues
---

# Heredoc File Write Workaround

## When to Use This Skill

Use this pattern when:
- `write_file` repeatedly 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:
1. Note the error message (e.g., "unknown error", encoding issues)
2. Review the file content for special characters, nested quotes, or complex syntax
3. Attempt the heredoc workaround below

### Step 2: Use Heredoc Syntax

Execute shell command with heredoc:

```bash
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

1. **Use quoted delimiter** (`'EOF'` not `EOF`) to prevent variable expansion:
   - `'EOF'` = literal content (recommended for code files)
   - `EOF` = allows variable expansion (use only if needed)

2. **Match delimiters exactly**: Opening and closing `EOF` must be on their own lines with no leading/trailing whitespace

3. **No escaping needed**: Content between delimiters is taken literally when using quoted delimiter

### Step 4: Verify File Creation

After executing the heredoc command:
1. Check if file exists: `ls -la /path/to/file.tsx`
2. Verify content: `cat /path/to/file.tsx` or `head -20 /path/to/file.tsx`
3. Proceed with subsequent tasks once confirmed

## Example Scenarios

### TypeScript/JSX Component

```bash
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

```bash
cat > tsconfig.json << 'EOF'
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"]
}
EOF
```

### Complex Shell Script

```bash
cat > deploy.sh << 'EOF'
#!/bin/bash
set -e

echo "Deploying..."
if [ "$ENV" = "production" ]; then
  echo "Production deployment"
fi
EOF
```

## Advantages Over write_file

1. **No escaping complexity**: Quotes, backslashes, and special characters work naturally
2. **Preserves formatting**: Indentation and line breaks remain exact
3. **Handles multi-line content**: No need to concatenate strings or use base64
4. **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_file` for 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

---
Source attribution: AG064
Original project: https://github.com/AG064/OpenSpace/blob/ff671ef61ed6587c49bd54c81cdc751c0b99e363/gdpval_bench/skills/heredoc-file-write/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 ✨Data Intelligence Lab@HKU✨

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: AG064
Original project: https://github.com/AG064/OpenSpace/blob/ff671ef61ed6587c49bd54c81cdc751c0b99e363/gdpval_bench/skills/heredoc-file-write/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering
Roles: Backend Developer, DevOps / SRE, Frontend Developer
Specialties: Backend
Tools: Shell
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 3a9aa24636e4c6435e35d1c979b8da12026ef459e987e746b96e1a2e8cebfec2