smart-file-writer Skill

Automatically diagnoses and resolves file write errors through systematic investigation rather than blind retries. Prevents common write failures proactively.

When to Use This Skill

Use this skill when any of these occurs:

• "Error writing file" messages
• "Permission denied" or "Access denied" errors
• "No space left on device" errors
• "File exists" conflicts
• "Path too long" errors (Windows)
• "Read-only file system" errors
• Any file write operation failure (Python, CLI, any language)
• Before critical file writes (proactive mode)

Not For / Boundaries

This skill does NOT:

• Handle network file system issues (NFS, SMB) beyond basic diagnostics
• Modify system-level permissions without user confirmation
• Bypass security policies or antivirus software
• Handle database write operations (different error domain)

Required inputs:

• Target file path
• Intended operation (write, append, create, etc.)
• Error message (if reactive mode)

Quick Reference

Diagnostic Checklist (Run Before Retry)

1. Path Validation

python
import os
# Check path length (Windows: 260 char limit)
if len(filepath) > 260 and os.name == 'nt':
    print(f"Path too long: {len(filepath)} chars")

# Check parent directory exists
parent = os.path.dirname(filepath)
if not os.path.exists(parent):
    print(f"Parent directory missing: {parent}")

2. Permission Check

python
import os
# Check directory write permission
parent = os.path.dirname(filepath) or '.'
if not os.access(parent, os.W_OK):
    print(f"No write permission: {parent}")

# Check file permissions if exists
if os.path.exists(filepath):
    if not os.access(filepath, os.W_OK):
        print(f"File not writable: {filepath}")

3. Disk Space Check

python
import shutil
# Check available disk space
stat = shutil.disk_usage(os.path.dirname(filepath) or '.')
free_gb = stat.free / (1024**3)
if free_gb < 0.1:  # Less than 100MB
    print(f"Low disk space: {free_gb:.2f} GB free")

4. File Lock Detection

python
import os
# Try to open with exclusive access
try:
    with open(filepath, 'a') as f:
        pass
except PermissionError:
    print(f"File locked by another process: {filepath}")

5. Windows-Specific Checks

bash
# Check if file is in use (Windows)
handle.exe -a "filepath"

# Check file attributes
attrib "filepath"

Resolution Patterns

Pattern 1: Create Missing Directories

python
import os
os.makedirs(os.path.dirname(filepath), exist_ok=True)

Pattern 2: Atomic Write (Temp + Rename)

python
import os
import tempfile

# Write to temp file first
temp_fd, temp_path = tempfile.mkstemp(dir=os.path.dirname(filepath))
try:
    with os.fdopen(temp_fd, 'w') as f:
        f.write(content)
    # Atomic rename
    os.replace(temp_path, filepath)
except Exception as e:
    os.unlink(temp_path)
    raise

Pattern 3: Exponential Backoff for Transient Issues

python
import time

def write_with_retry(filepath, content, max_retries=3):
    for attempt in range(max_retries):
        try:
            with open(filepath, 'w') as f:
                f.write(content)
            return True
        except (PermissionError, OSError) as e:
            if attempt < max_retries - 1:
                wait = 2 ** attempt  # 1s, 2s, 4s
                time.sleep(wait)
            else:
                raise

Pattern 4: Alternative Path (Shorten Long Paths)

python
import os
import hashlib

def shorten_path(long_path):
    """Use hash for long filenames"""
    dir_path = os.path.dirname(long_path)
    filename = os.path.basename(long_path)

    if len(long_path) > 260:
        # Hash the filename
        name, ext = os.path.splitext(filename)
        hash_name = hashlib.md5(name.encode()).hexdigest()[:16]
        return os.path.join(dir_path, f"{hash_name}{ext}")
    return long_path

Pattern 5: Permission Fix Suggestions

bash
# Linux/Mac: Add write permission
chmod u+w filepath

# Windows: Remove read-only attribute
attrib -r filepath

# Windows: Take ownership (admin required)
takeown /f filepath
icacls filepath /grant %username%:F

Pattern 6: Detect Antivirus Interference

python
import time
import os

def is_antivirus_blocking(filepath):
    """Detect if antivirus is scanning file"""
    try:
        # Try to open exclusively
        with open(filepath, 'r+b') as f:
            pass
        return False
    except PermissionError:
        # Wait and retry
        time.sleep(0.5)
        try:
            with open(filepath, 'r+b') as f:
                pass
            return True  # Was temporarily blocked
        except:
            return False  # Persistent block

Proactive Pre-Write Validation

Before Any Critical Write

python
def validate_write_conditions(filepath):
    """Run before writing important files"""
    issues = []

    # 1. Path length
    if len(filepath) > 260 and os.name == 'nt':
        issues.append(f"Path too long: {len(filepath)} chars")

    # 2. Parent directory
    parent = os.path.dirname(filepath) or '.'
    if not os.path.exists(parent):
        issues.append(f"Parent missing: {parent}")
    elif not os.access(parent, os.W_OK):
        issues.append(f"No write permission: {parent}")

    # 3. Disk space
    stat = shutil.disk_usage(parent)
    if stat.free < 100 * 1024 * 1024:  # 100MB
        issues.append(f"Low disk space: {stat.free / 1024**2:.1f} MB")

    # 4. File exists and writable
    if os.path.exists(filepath):
        if not os.access(filepath, os.W_OK):
            issues.append(f"File not writable: {filepath}")

    return issues

Integration with Claude Code Tools

Wrap Write Tool

python
# Before using Write tool, validate:
issues = validate_write_conditions(target_path)
if issues:
    print("Pre-write validation failed:")
    for issue in issues:
        print(f"  - {issue}")
    # Take corrective action
else:
    # Proceed with Write tool

Wrap Edit Tool

python
# Before editing, check file is writable
if not os.access(filepath, os.W_OK):
    print(f"Cannot edit: {filepath} is read-only")
    # Suggest: chmod u+w or attrib -r

Wrap Bash File Operations

bash
# Before redirecting output
if [ ! -w "$(dirname "$output_file")" ]; then
    echo "Cannot write to directory"
    exit 1
fi

Examples

Example 1: Reactive - Handle "Error writing file"

Input:

• Error: "Error writing file: results/model_checkpoint.pth"
• Operation: torch.save(model.state_dict(), filepath)

Steps:

1. Run diagnostic checklist:

• Path length: 45 chars ✓
• Parent exists: No ✗
• Permissions: N/A (parent missing)
• Disk space: 50GB ✓

1. Root cause: Parent directory doesn't exist
2. Resolution: os.makedirs('results', exist_ok=True)
3. Retry write operation
4. Success

Expected output:

Diagnosis: Parent directory 'results' does not exist
Resolution: Created directory 'results'
Retry: torch.save() succeeded

Example 2: Proactive - Prevent Long Path Error

Input:

• Target: D:\very\long\path\with\many\subdirectories\...\extremely_long_filename_that_exceeds_windows_limit.csv
• Operation: pandas.to_csv()

Steps:

1. Pre-write validation detects path length: 285 chars
2. Suggest shortened path using hash
3. Create mapping file for reference
4. Write to shortened path
5. Log original -> shortened mapping

Expected output:

Warning: Path length 285 chars exceeds Windows limit (260)
Alternative: D:\very\long\path\...\a3f5e8b2c1d4.csv
Mapping saved to: path_mappings.json
Write succeeded to alternative path

Example 3: Reactive - Permission Denied on Windows

Input:

• Error: "PermissionError: Errno 13] Permission denied: 'data.csv'"
• Operation: Writing CSV file

Steps:

1. Run diagnostic checklist:

• File exists: Yes
• File attributes: Read-only ✗
• File lock: Not locked
• Permissions: Read-only attribute set

1. Root cause: File has read-only attribute
2. Resolution: Suggest attrib -r data.csv
3. After user confirms, remove attribute
4. Retry write

Expected output:

Diagnosis: File 'data.csv' has read-only attribute
Resolution: Run 'attrib -r data.csv' to remove read-only flag
[After user confirmation]
Attribute removed. Retry succeeded.

Example 4: Reactive - File Locked by Another Process

Input:

• Error: "PermissionError: Errno 13] Permission denied: 'report.xlsx'"
• Operation: Writing Excel file

Steps:

1. Run diagnostic checklist:

• File exists: Yes
• Permissions: Writable
• File lock test: Locked ✗

1. Root cause: File open in Excel
2. Resolution: Cannot proceed, inform user
3. Suggest: Close Excel or write to alternative filename

Expected output:

Diagnosis: File 'report.xlsx' is locked by another process
Likely cause: File is open in Microsoft Excel
Resolution options:
  1. Close Excel and retry
  2. Write to alternative: 'report_new.xlsx'
  3. Use atomic write with temp file
Cannot proceed automatically. User action required.

Example 5: Proactive - Low Disk Space

Input:

• Target: Large model checkpoint (2GB)
• Operation: torch.save()

Steps:

1. Pre-write validation checks disk space
2. Detects only 500MB free
3. Warns before attempting write
4. Suggests cleanup or alternative location

Expected output:

Warning: Insufficient disk space
Required: ~2.0 GB
Available: 0.5 GB
Recommendations:
  1. Clean up temporary files
  2. Write to alternative drive: E:\
  3. Compress checkpoint before saving
Write operation blocked to prevent failure.

References

• references/diagnostic-procedures.md: Detailed diagnostic workflows
• references/platform-specific.md: Windows/Linux/Mac specific issues
• references/integration-guide.md: Integrating with Claude Code tools
• references/error-catalog.md: Common error messages and solutions

Maintenance

• Sources: Python os/shutil docs, Windows file system limits, POSIX standards
• Last updated: 2026-01-20
• Known limits:
• Network file systems (NFS/SMB) require specialized handling
• Some antivirus software cannot be reliably detected
• System-level permission changes require admin rights