What platforms are supported by this skill?

Windows, macOS, and Linux via Node's process.platform, with UNC path handling on Windows.

What problem does this solve for CLI apps?

It ensures consistent path normalization, tilde expansion, and OS-appropriate storage locations for config, data, and cache across platforms.

cross-platform-path-handler

npx machina-cli add skill a5c-ai/babysitter/cross-platform-path-handler --openclaw

Files (1)

SKILL.md

2.3 KB

Cross-Platform Path Handler

Generate cross-platform path handling utilities.

Capabilities

Normalize path separators
Handle home directory expansion
Create platform-specific path utilities
Configure config directory locations
Handle UNC paths on Windows
Generate path manipulation helpers

Generated Patterns

TypeScript Path Utilities

import path from 'path';
import os from 'os';
import fs from 'fs';

export function normalizePath(p: string): string {
  return p.replace(/\\/g, '/');
}

export function toPlatformPath(p: string): string {
  return p.split('/').join(path.sep);
}

export function expandHome(p: string): string {
  if (p.startsWith('~')) {
    return path.join(os.homedir(), p.slice(1));
  }
  return p;
}

export function getConfigDir(appName: string): string {
  const platform = process.platform;
  if (platform === 'win32') {
    return path.join(process.env.APPDATA || '', appName);
  }
  if (platform === 'darwin') {
    return path.join(os.homedir(), 'Library', 'Application Support', appName);
  }
  return path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), appName);
}

export function getDataDir(appName: string): string {
  const platform = process.platform;
  if (platform === 'win32') {
    return path.join(process.env.LOCALAPPDATA || '', appName);
  }
  if (platform === 'darwin') {
    return path.join(os.homedir(), 'Library', 'Application Support', appName);
  }
  return path.join(process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share'), appName);
}

export function getCacheDir(appName: string): string {
  const platform = process.platform;
  if (platform === 'win32') {
    return path.join(process.env.LOCALAPPDATA || '', appName, 'Cache');
  }
  if (platform === 'darwin') {
    return path.join(os.homedir(), 'Library', 'Caches', appName);
  }
  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), appName);
}

Target Processes

cross-platform-cli-compatibility
configuration-management-system
cli-application-bootstrap

Source

git clone https://github.com/a5c-ai/babysitter/blob/main/plugins/babysitter/skills/babysit/process/specializations/cli-mcp-development/skills/cross-platform-path-handler/SKILL.md

View on GitHub

Overview

Generates TypeScript utilities to normalize path separators, expand '~', and create OS-aware path helpers for CLI apps. It covers config, data, and cache directories across Windows, macOS, and Linux, including UNC path handling on Windows. These tools ensure consistent file access and storage locations across platforms.

How This Skill Works

Implements exported functions (normalizePath, toPlatformPath, expandHome, getConfigDir, getDataDir, getCacheDir) using Node's path, os, and process.platform to adapt behavior per OS. It normalizes separators, resolves tilde paths, and returns app-specific directories for each OS, including Windows UNC considerations when applicable.

When to Use It

Building a CLI tool that runs on Windows, macOS, and Linux and reads or writes files.
Storing app configuration, data, and caches in OS-appropriate directories using getConfigDir, getDataDir, and getCacheDir.
Accepting user-provided paths with mixed separators or tilde (~) expansion in cross-platform scripts.
Handling Windows UNC paths for network shares without breaking path operations.
Porting existing Unix-based scripts to Windows while preserving consistent path behavior.

Quick Start

Step 1: Import the utilities into your TypeScript project and reference the exported functions you plan to use.
Step 2: Use expandHome and normalizePath on user-provided paths, and convert paths with toPlatformPath if needed.
Step 3: Resolve app directories with getConfigDir(appName), getDataDir(appName), and getCacheDir(appName) to store config, data, and cache.

Best Practices

Apply expandHome and normalizePath at input validation before any file I/O.
Rely on getConfigDir/getDataDir/getCacheDir for platform-specific storage locations instead of hard-coding paths.
Test path utilities on all target OSes, including UNC paths on Windows.
Use toPlatformPath to convert Unix-style paths to the current platform format when needed.
Validate environment variables (APPDATA, XDG_CONFIG_HOME, etc.) and provide sensible fallbacks.

Example Use Cases

A backup CLI that resolves source/destination paths across Windows UNC shares and Linux/macOS mounts.
An installer/updater that writes logs and temp data into the user’s OS-appropriate cache directory.
A config-driven tool that stores preferences under AppData (Windows) or ~/.config (Linux/macOS).
A data-sync CLI that saves persistent state under XDG_DATA_HOME on Unix-like systems.
A bootstrap CLI that initializes app folders using getConfigDir, getDataDir, and getCacheDir for a consistent layout.

Frequently Asked Questions

Add this skill to your agents