AGENT SKILL

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

03 SKILL.md 正文

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:

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

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

  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

04 同仓库更多 Skills

HKUDS
HKUDS/AgentPilot

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.

★ 8.0k
HKUDS
HKUDS/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.

★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

Skill与智能体开发
★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

Skill与智能体开发
★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

★ 8.0k
HKUDS
HKUDS/AgentPilot

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.

★ 8.0k