AGENT SKILL

cross-platform-paths

Critical patterns for cross-platform path handling in this VS Code extension. Windows vs POSIX path bugs are the #1 source of issues. Use this skill when reviewing or writing path-related code.

License 许可
MIT
最近更新
2026-08-31
Stars
★ 1
Forks
0

01 前言 Front Matter

name
cross-platform-paths
description
Critical patterns for cross-platform path handling in this VS Code extension. Windows vs POSIX path bugs are the #1 source of issues. Use this skill when reviewing or writing path-related code.
argument-hint
Review path handling in [file or component]
user-invocable
false

03 SKILL.md 正文

Cross-Platform Path Handling

CRITICAL: This extension runs on Windows, macOS, and Linux. Path bugs are the #1 source of issues.

Core Rules

Rule 1: Never Concatenate Paths with /

// ❌ WRONG: POSIX-style path concatenation
const envPath = homeDir + '/.venv/bin/python';

// ✅ RIGHT: Use path.join()
const envPath = path.join(homeDir, '.venv', 'bin', 'python');

Rule 2: Use path.resolve() for Comparisons, Not path.normalize()

// ❌ WRONG: path.normalize keeps relative paths relative on Windows
const normalized = path.normalize(fsPath);
// path.normalize('\test') → '\test' (still relative!)

// ✅ RIGHT: path.resolve adds drive letter on Windows
const normalized = path.resolve(fsPath);
// path.resolve('\test') → 'C:\test' (absolute!)

// When comparing paths, use resolve() on BOTH sides:
const pathA = path.resolve(fsPath);
const pathB = path.resolve(e.environmentPath.fsPath);
return pathA === pathB;

Rule 3: Use Uri.file().fsPath for VS Code Paths

// ❌ WRONG: Raw string comparison
if (filePath === otherPath) {
}

// ✅ RIGHT: Compare fsPath to fsPath
import { Uri } from 'vscode';
const fsPathA = Uri.file(pathA).fsPath;
const fsPathB = Uri.file(pathB).fsPath;
if (fsPathA === fsPathB) {
}

Platform-Specific Gotchas

Windows

Issue Details
Drive letters Paths start with C:\, D:\, etc.
Backslashes Separator is \, not /
Case insensitivity C:\Test equals c:\test
Long paths Paths >260 chars may fail
Mapped drives Z:\ may not be accessible
pyenv-win Uses pyenv.bat, not pyenv or pyenv.exe
Poetry cache %LOCALAPPDATA%\pypoetry\Cache\virtualenvs
UNC paths \\server\share\ format

macOS

Issue Details
Case sensitivity Depends on filesystem (usually insensitive)
Homebrew symlinks Complex symlink chains in /opt/homebrew/
Poetry cache ~/Library/Caches/pypoetry/virtualenvs
XCode Python Different from Command Line Tools Python

Linux

Issue Details
Case sensitivity Paths ARE case-sensitive
/bin symlinks /bin may be symlink to /usr/bin
XDG directories ~/.local/share/virtualenvs for pipenv
Poetry cache ~/.cache/pypoetry/virtualenvs
Hidden files Dot-prefixed files are hidden

Common Patterns

Getting Platform-Specific Paths

import * as os from 'os';
import * as path from 'path';

// Home directory
const home = os.homedir(); // Works cross-platform

// Construct paths correctly
const venvPath = path.join(home, '.venv', 'bin', 'python');
// Windows: C:\Users\name\.venv\bin\python
// macOS:   /Users/name/.venv/bin/python
// Linux:   /home/name/.venv/bin/python

Environment-Specific Executable Names

const isWindows = process.platform === 'win32';

// Python executable
const pythonExe = isWindows ? 'python.exe' : 'python';

// Activate script
const activateScript = isWindows
    ? path.join(venvPath, 'Scripts', 'activate.bat')
    : path.join(venvPath, 'bin', 'activate');

// pyenv command
const pyenvCmd = isWindows ? 'pyenv.bat' : 'pyenv';

Normalizing Paths for Comparison

import { normalizePath } from './common/utils/pathUtils';

// Use normalizePath() for map keys and comparisons
const key = normalizePath(filePath);
cache.set(key, value);

// But preserve original for user display
traceLog(`Discovered: ${filePath}`); // Keep original

Handling Uri | string Union Types

// ❌ WRONG: Assuming Uri
function process(locator: Uri | string) {
    const fsPath = locator.fsPath; // Crashes if string!
}

// ✅ RIGHT: Handle both types
function process(locator: Uri | string) {
    const fsPath = locator instanceof Uri ? locator.fsPath : locator;

    // Now normalize for comparisons
    const normalized = path.resolve(fsPath);
}

File Existence Checks

import * as fs from 'fs';
import * as path from 'path';

// Check file exists (cross-platform)
const configPath = path.join(projectRoot, 'pyproject.toml');
if (fs.existsSync(configPath)) {
    // File exists
}

// Use async version when possible
import { promises as fsPromises } from 'fs';
try {
    await fsPromises.access(configPath);
    // File exists
} catch {
    // File does not exist
}

Shell Path Escaping

// ❌ WRONG: Unescaped paths in shell commands
terminal.sendText(`python ${filePath}`);
// D:\path\file.py becomes "D:pathfile.py" in some shells!

// ✅ RIGHT: Quote paths
terminal.sendText(`python "${filePath}"`);

// For Git Bash on Windows, escape backslashes
const shellPath = isGitBash ? filePath.replace(/\\/g, '/') : filePath;

Testing Cross-Platform Code

When testing path-related code:

  1. Test on Windows (cmd, PowerShell, Git Bash)
  2. Test on macOS (zsh, bash)
  3. Test on Linux (bash, fish)

Pay special attention to:

  • Paths with spaces: C:\Program Files\Python
  • Paths with Unicode: ~/проекты/
  • Very long paths (>260 chars on Windows)
  • Paths with special characters: $, &, (, )

04 同仓库更多 Skills

nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

xcode-project-setup

Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

writing-skills

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

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

writing-plans

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

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

workflow-skill-creator

Distills a completed user workflow or interaction into a reusable agent skill. Use when the user asks to turn their workflow, interaction, or multi-step process into a skill, or when they say "make this a skill", "create a skill from what we just did", "package this workflow" or similar. Do not use for creating skills from scratch without an existing workflow (use a generic skill-creator for that).

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

verify-and-stop

Prove existing work meets acceptance conditions without expanding scope. Use for validation-only tasks, completion checks, focused gate runs, and last-mile proof.

★ 1
nguyenhungtran18
nguyenhungtran18/skill-and-tool-tracker

verification-before-completion

Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always

★ 1