Index of every page on this site: llms.txt
All skills
flutter avatar

/dart-use-path-package

@ff6d472 official
by flutterflutter/agent-plugins3.2k stars
193
Run it yourself

Cross-platform file and directory path manipulation, segment splitting, extension extraction, and context conversion using `package:path` and `package:file`. Use when writing, inspecting, joining, splitting, or refactoring file paths, directory names, or extensions, or replacing raw string path operations (`.split('/')`, `'$dir/$file'`, `.endsWith('.ext')`, `.replaceAll('\\', '/')`). Don't use for HTTP network URI routing, database query strings, or non-path string processing.

Use this Skill: https://skilld.dev/gh/flutter/agent-plugins/dart-use-path-package

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈126 tokens for metadata: the name and description. ≈2.7k when used: this file.

Description uses 6.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈505 characters, or 6.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Safe Cross-Platform Path Manipulation in Dart

Contents


1. Core Principles & Cross-Platform Rules

Avoid Treating File Paths as Raw Strings

  • Native file paths on Windows use backslashes (\), whereas macOS and Linux use forward slashes (/).
  • String operations like .contains('foo/'), .startsWith('foo/'), or .split('/') silently fail on Windows native paths.
  • String interpolation like '$dir/$file' injects forward slashes on Windows and produces duplicate slashes (//) when $dir ends with a trailing slash.

Rule: Always decompose paths into segments using p.split(path) before inspecting directory hierarchy or segment names, and always join path components using p.join(...).

Pragmatic Boundary Joining vs. Multi-Segment Decomposition (p.join)

  • Cross-Platform Libraries (Windows + POSIX): Pass individual path segments to p.join(dir, 'sub', 'file.json') so package:path inserts OS-native separators (\ on Windows, / on POSIX) between every component.
  • POSIX-Only Tools & Static Subpath Greppability: In codebases exclusively targeting Linux/macOS (or when joining a dynamic base path to a known static subpath), decomposing 5–6 static segments into separate arguments (p.join(home, '.local', 'share', 'app', 'bin', 'config.json')) causes dart format to wrap across 6–8 vertical lines and destroys substring greppability (grep / code_search for .local/share/app/bin).
  • Rule for POSIX Targets: Prefer 2-argument boundary joining (p.join(home, '.local/share/app/bin/config.json')). This prevents duplicate-slash bugs (//) at variable boundaries while preserving single-line readability and exact string searchability.

Normalization vs. Canonicalization (p.normalize vs. p.canonicalize)

  • p.normalize(path) resolves . and .. segments purely lexically without consulting the filesystem or standardizing case.
  • When deduplicating directory paths or comparing physical file identity across symlinks, relative roots, or case-insensitive filesystems, use p.canonicalize(path).

Strip Location Specifiers & Convert URIs Safely

  • Strings formatted as <path>:<line>-<col> or <path>:<line> are not pure file paths. Passing them directly to p.normalize or Uri.parse causes bugs (on Windows, Uri.parse mistakes C: for a URI scheme and :line for a port).
  • Extract the trailing :line-col suffix via regular expression (RegExp(r'^(.*?):(\d+(?:-\d+)?)$')) before passing the file path to package:path.
  • URI Boundary Conversions: When converting between file paths and Uri objects, always use p.toUri(path) and p.fromUri(uri) rather than Uri.parse(path) or manual string concatenation.

2. Recommended package:path Idioms vs. String Anti-Patterns

Path Joining

  • Prefer: p.join(dir, file)
  • Avoid: '$dir/$file' or 'a/$b'
  • Why: String interpolation injects / on Windows and creates duplicate slashes (//) when $dir ends with a trailing separator.

Segment Matching

  • Prefer: p.split(path).contains('foo')
  • Avoid: path.contains('foo/')
  • Why: String matching fails on Windows backslashes (foo\bar) and produces false positives on partial substring names (e.g. barfoo/).

Root and Directory Prefixes

  • Prefer: if (p.split(path) case ['foo', ...]) (or case ['foo', ...final rest] when extracting tail segments), or p.isWithin('foo', path)
  • Avoid: path.startsWith('foo/') or p.split(path).first == 'foo'
  • Why: String prefix matching fails on Windows separators (foo\bar). Calling p.split(path).first throws a StateError on empty lists and requires separate .skip(1) slicing, whereas list patterns safely check non-emptiness, match multi-segment prefixes, and optionally bind ...final rest in a single step. When unnormalized relative prefixes like ./foo/bar may appear, use p.isWithin('foo', path) (or p.split(p.normalize(path))).

File Extensions

  • Prefer: p.extension(path) == '.wasm'
  • Avoid: path.endsWith('.wasm')
  • Why: Substring suffix matching falsely matches directories (foo.wasm/) or non-extension suffixes.

Extension Slicing and Compound Extensions

  • Prefer: p.withoutExtension(path) and p.extension(path, 2)
  • Avoid: path.lastIndexOf('.') and manual substring slicing
  • Why: Manual arithmetic breaks on hidden dotfiles (.gitignore) and compound extensions (.js.map, .tar.gz).

POSIX and URL Path Conversion

  • Prefer: p.posix.joinAll(p.split(path)) or p.url.joinAll(p.split(path))
  • Avoid: path.replaceAll(r'\', '/')
  • Why: Ad-hoc separator replacement fails on root drives and mixes OS context with POSIX or URL targets.

URI Conversion

  • Prefer: p.toUri(path) and p.fromUri(uri)
  • Avoid: Uri.parse(path) and uri.path
  • Why: Direct URI parsing fails on Windows drive letters (C:) and leaks percent-encoding (e.g. %20 for spaces).

Directory Basename Helper

  • Prefer: String canonicalDirName(Directory d) => p.basename(p.normalize(d.absolute.path));
  • Avoid: Repeating p.basename(p.normalize(dir.absolute.path)) inline across files.
  • Why: Centralizes canonical directory naming logic and reduces boilerplate.

3. Bridging Native Paths to POSIX, Git, & URL Contexts

Avoid calling .replaceAll('\\', '/') or .replaceAll(r'\', '/') to convert OS-native paths into POSIX paths (for Git, YAML, archive manifests) or URL segments.

Rule: Split the relative native path using p.split(...), inspect segments with Dart 3 list pattern matching, and join using p.posix.joinAll(...) or p.url.joinAll(...). Always call p.relative(filePath, from: root) first so leading root segments ('/' on POSIX or r'C:\' on Windows) do not interfere with relative prefix patterns:

import 'package:path/path.dart' as p;

String computeWebAssetKey(String filePath, String projectRoot) {
  final relative = p.relative(filePath, from: projectRoot);
  final segments = p.split(relative);
  return switch (segments) {
    ['assets', ...] => p.posix.joinAll(segments),
    _ => p.posix.joinAll(['assets', ...segments]),
  };
}

Git Paths and Repository Metadata

  • Git repository tree objects, .gitignore pattern rules, .gitattributes, and git-tracked symlinks strictly use POSIX forward slashes (/), even on Windows.
  • Inserting native Windows backslashes (\) into .gitignore or git commands causes Git to treat \ as an escape character rather than a directory separator, silently breaking pattern matching.
  • When generating .gitignore entries, repository manifests, or symlink targets programmatically from native file paths, convert the relative native path using p.posix.joinAll(p.split(relativePath)) or p.posix.join(...).

4. Mockable File Systems (package:file vs. Global p.*)

In codebases that use package:file (e.g., CLI applications or services tested with MemoryFileSystem), avoid calling top-level p.* functions on File or Directory paths.

  • Top-level p.* functions bind to the host operating system running the test.
  • If a unit test creates a MemoryFileSystem(style: FileSystemStyle.windows) on a Linux or macOS runner, global p.split(file.path) will split on / instead of \, breaking the test.

Rule: Always use the Context attached to the FileSystem (file.fileSystem.path):

import 'package:file/file.dart';

List<String> listSubdirectoryNames(Directory dir) {
  final pathContext = dir.fileSystem.path;
  return dir
      .listSync()
      .whereType<Directory>()
      .map((d) => pathContext.basename(d.path))
      .toList();
}

5. Extensions, Compound Extensions & Stem Extraction

Avoid manual .lastIndexOf('.') and .substring() arithmetic when extracting file extensions or inserting content hashes. p.extension natively supports multi-level extensions via its optional level parameter.

  • Multi-Dot Stem Nuance: Calling p.extension('main.dart.wasm', 2) returns '.dart.wasm' because it blindly captures the last two dot-separated segments. When hashing or stripping extensions on files that may have multi-dot stems (e.g., main.dart.wasm vs. main.dart.js.map), check whether p.extension(filename, 2) matches a known compound extension (or .endsWith('.map')) before falling back to single-level p.extension(filename):
import 'package:path/path.dart' as p;

String insertContentHash(String filename, String hash) {
  final compoundExt = p.extension(filename, 2);
  // Only use the 2-level extension for true compound suffixes (e.g., '.js.map')
  final ext = compoundExt.endsWith('.map')
      ? compoundExt
      : p.extension(filename);
  final stem = filename.substring(0, filename.length - ext.length);
  return '$stem.$hash$ext';
}

6. Workflows & Audit Checklist

Path Refactoring Checklist

  • Replace string interpolation ('$dir/$file') with p.join(dir, file).
  • Replace .contains('dir/') and .startsWith('dir/') with p.split(path) list pattern checks (case ['dir', ...final rest]) or p.isWithin(parent, child).
  • Replace .replaceAll(r'\', '/') with p.posix.joinAll(p.split(path)) (or p.url.joinAll).
  • Replace .endsWith('.ext') on file paths with p.extension(path) == '.ext'.
  • Replace manual dot-index slicing with p.withoutExtension(path) and p.extension(path, [level]).
  • Verify that code using package:file accesses fileSystem.path instead of global p.*.
  • Ensure Git paths, .gitignore entries, and symlink targets use p.posix forward slashes.

References & Examples

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts1mo3 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    This skill provides best practices and architectural guidance for cross-platform file path manipulation in Dart. It promotes the use of standard libraries to prevent common OS-specific errors and contains no malicious code or behaviors.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

Signed by skilld at ff6d472. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago
Other metadata
metadata
{
  "model": "models/gemini-3.1-pro-preview",
  "last_modified": "Wed, 23 Sep 2026 22:10:00 GMT"
}

README badge

README badge for flutter/agent-plugins/dart-use-path-package