mcpbeat Sign in

Smart File Writer Skill for Claude

Intelligent file write error handler: diagnoses permissions, disk space, path length, file locks before retrying. Use when you encounter 'Error writing file', 'Permission denied', 'Access denied', 'No space left', or related file write failures.

13k tokens
context cost
the whole folder, loaded on every use
8
files
ships runnable scripts
0
copies elsewhere
how many repositories repackaged it
2583
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository
npx skills add https://github.com/foryourhealth111-pixel/Vibe-Skills --skill smart-file-writer

What comes with it

43 450 bytes besides the instruction
QUALITY_CHECKLIST.md
README.md
references/diagnostic-procedures.md
references/index.md
references/integration-guide.md
references/platform-specific.md
scripts/validate.py

What it tells the agent to use

found in the instruction text
Write writes files
Edit edits files in place

The instruction itself

16 sections, as written by the author

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

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

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

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

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

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

# Check file attributes
attrib "filepath"

Resolution Patterns

Pattern 1: Create Missing Directories

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

Pattern 2: Atomic Write (Temp + Rename)

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

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)

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

# 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

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

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

# 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

# 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

# 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:

  • Run diagnostic checklist:
  • Path length: 45 chars ✓
  • Parent exists: No ✗
  • Permissions: N/A (parent missing)
  • Disk space: 50GB ✓
  • Root cause: Parent directory doesn't exist
  • Resolution: os.makedirs('results', exist_ok=True)
  • Retry write operation
  • 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:

  • Pre-write validation detects path length: 285 chars
  • Suggest shortened path using hash
  • Create mapping file for reference
  • Write to shortened path
  • 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:

  • Run diagnostic checklist:
  • File exists: Yes
  • File attributes: Read-only ✗
  • File lock: Not locked
  • Permissions: Read-only attribute set
  • Root cause: File has read-only attribute
  • Resolution: Suggest attrib -r data.csv
  • After user confirms, remove attribute
  • 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:

  • Run diagnostic checklist:
  • File exists: Yes
  • Permissions: Writable
  • File lock test: Locked ✗
  • Root cause: File open in Excel
  • Resolution: Cannot proceed, inform user
  • 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:

  • Pre-write validation checks disk space
  • Detects only 500MB free
  • Warns before attempting write
  • 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

Other skills for the same job

different authors, same section of the catalogue
Doc Coauthoring
by anthropics
vendor ×10

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

4k tokens
Changelog Generator
by frostant
×9

Automatically creates user-facing changelogs from git commits by analyzing commit history, categorizing changes, and transforming technical commits into clear, customer-friendly release notes. Turns hours of manual changelog writing into minutes of automated generation.

774 tokens
Test Driven Development
by w95
×7

Use when implementing any feature or bugfix, before writing implementation code

2k tokens
Writing Plans
by ZhanlinCui
×4

Use when you have a spec or requirements for a multi-step task, before touching code

816 tokens
Writing Skills
by ZhanlinCui
×4

Use when creating new skills, editing existing skills, or verifying skills work before deployment

26k tokens scripts
Crafting Effective Readmes
by softaworks
×3

Use when writing or improving README files. Not all READMEs are the same — provides templates and guidance matched to your audience and project type.

15k tokens
Humanizer
by softaworks
×3

| Remove signs of AI-generated writing from text. Use when editing or reviewing text to make it sound more natural and human-written. Based on Wikipedia's inflated symbolism, promotional language, superficial -ing analyses, vague attributions, em dash overuse, rule of three, AI vocabulary words, negative parallelisms, and excessive conjunctive phrases.

6k tokens
Opentrons Integration
by christophacham
×3

Official Opentrons Protocol API for OT-2 and Flex robots. Use when writing protocols specifically for Opentrons hardware with full access to Protocol API v2 features. Best for production Opentrons protocols, official API compatibility. For multi-vendor automation or broader equipment control use pylabrobot.

9k tokens scripts

How to use it

Copy the folder

Take foryourhealth111-pixel/smart-file-writer from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.