Diagnoses why a file write failed (permissions, disk space, path length, locks, read-only mounts) before retrying, instead of repeating the same call blindly.

Apache-2.0Auto-check passedDevelopment

Install Smart File Writer

skills CLI
$ npx skills add foryourhealth111-pixel/Vibe-Skills --skill smart-file-writer -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install foryourhealth111-pixel/Vibe-Skills smart-file-writer --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/foryourhealth111-pixel/Vibe-Skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/bundled/skills/smart-file-writer .claude/skills/smart-file-writer && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
smart-file-writer
GitHub stars
3.6k
Token cost
~2.6k tokens
SKILL.md length
528 words
Files
8 (incl. scripts, references)
Skills in repo
81
Repo updated
First seen
Licence
Apache-2.0

At a glance

Diagnoses why a file write failed (permissions, disk space, path length, locks, read-only mounts) before retrying, instead of repeating the same call blindly.

  • Works in 5 steps: Run diagnostic checklist → Root cause: Parent directory doesn't exist → Resolution: os.makedirs('results',… → …
  • A script or agent hits Permission denied or Access denied while saving a file
  • SKILL.md covers When to Use This Skill, Not For / Boundaries, Quick Reference and Examples, plus 2 more sections
  • Runs Python scripts from its folder

What it does

When a write fails with permission denied, no space left on device, file exists, path too long or read-only file system, this skill has the agent investigate before it retries. The quick-reference checklist covers path validation (including the 260 character limit on Windows), directory write permission, free disk space, file lock detection and Windows-specific checks.

It then offers resolution patterns: creating missing directories, atomic writes through a temp file and rename, exponential backoff for transient problems, shortening long paths, suggesting permission fixes and detecting antivirus interference. It can also run proactively before critical writes. Stated limits: no deep network file system handling, no database writes, no changing system permissions without your confirmation and no bypassing security software. A validate.py script and reference notes ship with it.

When your agent uses it

  • A script or agent hits Permission denied or Access denied while saving a file
  • Writes fail with No space left on device
  • Long Windows paths cause write errors
  • Before a critical write that must not fail halfway

Example prompts

  • “Writing to ./output/report.json keeps failing with Permission denied. Find out why.”
  • “Saving logs/app.log fails with No space left on device. Check the disk and suggest a fix.”
  • “Before overwriting config/settings.yaml, check that the write will work and do it atomically.”

Requirements

  • Python for the diagnostic snippets and validate.py

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit ddcaa2a. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Smart File Writer loads about 2.6k tokens when it runs, and up to ~10k if it reads all its reference files. Until then it costs about 66 tokens; SKILL.md has 528 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~66
When it runs · the whole SKILL.md, loaded when a task matches
~2.6k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~10k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from foryourhealth111-pixel/Vibe-Skills at commit ddcaa2a, republished under its Apache-2.0 licence (© foryourhealth111-pixel). 528 words, ~2,625 tokens.

Download SKILL.mdSave it as .claude/skills/smart-file-writer/SKILL.md (or your agent's skills folder). This skill also uses 7 other files; get the full folder from GitHub.
name
smart-file-writer
description
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.

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 ✓
  2. Root cause: Parent directory doesn't exist
  3. Resolution: os.makedirs('results', exist_ok=True)
  4. Retry write operation
  5. 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
Show full SKILL.md (216 more words)Show less
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
  2. Root cause: File has read-only attribute
  3. Resolution: Suggest attrib -r data.csv
  4. After user confirms, remove attribute
  5. 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 ✗
  2. Root cause: File open in Excel
  3. Resolution: Cannot proceed, inform user
  4. 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

© foryourhealth111-pixel, Apache-2.0. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (scripts, references) in bundled/skills/smart-file-writer of foryourhealth111-pixel/Vibe-Skills.

  • SKILL.md
  • QUALITY_CHECKLIST.md
  • README.md
  • references/diagnostic-procedures.md
  • references/index.md
  • references/integration-guide.md
  • references/platform-specific.md
  • scripts/validate.py

Open the folder on GitHubat commit ddcaa2a

Compare with similar skills

Smart File Writer next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Smart File Writer compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Smart File Writer this skillforyourhealth111-pixel/Vibe-Skills3.6k—~2.6kAutomated safety check: PassApache-2.0
Python Script Runnercongchuanling-dot/Cohort182—~577Automated safety check: NotesMIT
Sentry Error Capturejeremylongshore/tons-of-skills-marketplace2.8k—~3kAutomated safety check: PassMIT
Code Execution Fallback and Path AnchoringHKUDS/OpenSpace7.8k—~1.1kAutomated safety check: PassMIT
Browser Harness Agentloomlinora-u/AgentLoom168—~1.3kAutomated safety check: PassNone
Native Data FetchingCherryHQ/cherry-studio-app4k6 repos~2.9kAutomated safety check: NotesMIT

Similar skills

  • Python Script Runner

    congchuanling-dot/Cohort

    Runs a Python script with checks first: confirms the interpreter version, compiles it for syntax errors, verifies imports, then explains any traceback in plain language.

    182 GitHub stars~577 tokensUpdated 1 mo ago
    DevelopmentAuto-check: notes
  • Sentry Error Capture

    jeremylongshore/tons-of-skills-marketplace

    Implement advanced error capture and context enrichment with Sentry.

    2.8k GitHub stars~3k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Fallback ladder for failed sandboxed code runs, plus the habit of fixing the working directory first so generated files land in the right place.

    7.8k GitHub stars~1.1k tokensUpdated 1 mo ago
    Agent WorkflowsAuto-check passed
  • Browser Harness Agentloom

    linora-u/AgentLoom

    A skill your agent uses when working on AgentLoom browser-harness integration or debugging applications/browserharnessprobe: creating or updating the probe Application, installing the external…

    168 GitHub stars~1.3k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Native Data Fetching

    CherryHQ/cherry-studio-app

    A skill your agent uses when implementing or debugging ANY network request, API call, or data fetching.

    4k GitHub starsUsed in 6 repos~2.9k tokens
    DevelopmentAuto-check: notes
  • LangBot Plugin Development

    langbot-app/LangBot

    Guides building, debugging and testing LangBot plugins: components, SDK calls, README and locale rules, SDK pitfalls and WebSocket-based testing.

    18k GitHub stars~3.9k tokensUpdated today
    DevelopmentAuto-check passed

More from foryourhealth111-pixel/Vibe-Skills

All 81 skills in this repo
  • Market Research Reports

    foryourhealth111-pixel/Vibe-Skills

    Produces long consulting-style market research and industry reports covering market sizing, competitive landscape, market entry and investment theses.

    3.6k GitHub stars~2.5k tokensUpdated 1 mo ago
    Auto-check: notes
  • Academic Venue Templates

    foryourhealth111-pixel/Vibe-Skills

    Supplies venue-specific LaTeX templates and formatting rules for journals, conferences and posters, and checks a manuscript against page limits and submission requirements.

    3.6k GitHub stars~3.9k tokensUpdated 1 mo ago
    Auto-check: notes
  • Digital Brain

    foryourhealth111-pixel/Vibe-Skills

    This skill should be used when the user asks to "write a post", "check my voice", "look up contact", "prepare for meeting", "weekly review", "track goals", or mentions personal brand, content…

    3.6k GitHub stars~1.7k tokensUpdated 1 mo ago
    Auto-check passed
  • Automated Video Studio

    foryourhealth111-pixel/Vibe-Skills

    Turns footage, audio and a storyboard plan into a finished short video with FFmpeg jump-cuts, subtitle burn-in and a final polish pass.

    3.6k GitHub stars~838 tokensUpdated 1 mo ago
    Auto-check passed
  • Citation Management

    foryourhealth111-pixel/Vibe-Skills

    Turns DOIs, PMIDs and arXiv IDs into clean BibTeX, searches Google Scholar and PubMed, and checks and deduplicates a reference list.

    3.6k GitHub stars~7.6k tokensUpdated 1 mo ago
    Auto-check: notes
  • Creating Data Visualizations

    foryourhealth111-pixel/Vibe-Skills

    Create analytical charts and plots from existing data. An agent skill from foryourhealth111-pixel/Vibe-Skills.

    3.6k GitHub stars~403 tokensUpdated 1 mo ago
    Auto-check passed

Works with

Questions about Smart File Writer

What does Smart File Writer do?

Diagnoses why a file write failed (permissions, disk space, path length, locks, read-only mounts) before retrying, instead of repeating the same call blindly. When a write fails with permission denied, no space left on device, file exists, path too long or read-only file system, this skill has the agent investigate before it retries. The quick-reference checklist covers path validation (including the 260 character limit on Windows), directory write permission, free disk space, file lock detection and Windows-specific checks.

When should I use Smart File Writer?

Smart File Writer fits situations like: A script or agent hits Permission denied or Access denied while saving a file; writes fail with No space left on device; long Windows paths cause write errors; before a critical write that must not fail halfway.

How do I install Smart File Writer in Claude Code?

Run `npx skills add foryourhealth111-pixel/Vibe-Skills --skill smart-file-writer -a claude-code`. Or copy the skill folder (bundled/skills/smart-file-writer in foryourhealth111-pixel/Vibe-Skills) into .claude/skills/smart-file-writer in your project. Claude Code loads it when a task matches its description.

How do I install Smart File Writer in Codex?

Run `npx skills add foryourhealth111-pixel/Vibe-Skills --skill smart-file-writer -a codex`. Or copy the skill folder (bundled/skills/smart-file-writer in foryourhealth111-pixel/Vibe-Skills) into .agents/skills/smart-file-writer in your project. Codex loads it when a task matches its description.

Can I use Smart File Writer in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add foryourhealth111-pixel/Vibe-Skills --skill smart-file-writer -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/smart-file-writer, .gemini/skills/smart-file-writer, .github/skills/smart-file-writer and .opencode/skills/smart-file-writer in your project.

What does Smart File Writer need to run?

Going by SKILL.md and its folder, Smart File Writer needs Python for the scripts in its folder. Our summary lists: Python for the diagnostic snippets and validate.py.

Does Smart File Writer access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Smart File Writer safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does Smart File Writer use?

Smart File Writer is published under the Apache-2.0 licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Smart File Writer use?

About 2.6k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 7.8k tokens, read only when the agent opens those files.

What are the alternatives to Smart File Writer?

Skills that share tags, products or a category with Smart File Writer: Python Script Runner (congchuanling-dot/Cohort, 182 stars), Sentry Error Capture (jeremylongshore/tons-of-skills-marketplace, 2.8k stars), Code Execution Fallback and Path Anchoring (HKUDS/OpenSpace, 7.8k stars) and Browser Harness Agentloom (linora-u/AgentLoom, 168 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Smart File Writer?

foryourhealth111-pixel (a GitHub user) maintains it in foryourhealth111-pixel/Vibe-Skills, which has 3,627 GitHub stars. The repository holds 81 skills in this directory. The repository was last updated on August 31, 2026.

Source: foryourhealth111-pixel/Vibe-Skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.