repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

add Windows filename guidance skill

e2f5d802f8d97948835b41b960eedcd33f60539b

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

pi/agent/skills/windows-filename-guidance/SKILL.md

Added
new file mode 100644
1 +---
2 +name: windows-filename-guidance
3 +description: "Use for Windows filename rules and failures involving reserved DOS device names such as NUL, invalid or trailing characters, inaccessible cross-platform names, long paths, or files that Windows cannot inspect, rename, or delete normally."
4 +compatibility: "Windows with cmd.exe"
5 +---
7 +# Windows Filename Guidance
9 +## Model
11 +Separate three layers:
13 +1. the filesystem's on-disk rules
14 +2. Windows path namespace and normalization
15 +3. the application's API and path handling
17 +A name can exist on NTFS yet be unreachable through an ordinary Win32 path.
18 +This commonly happens when another operating system, namespace, share, or tool
19 +created it. It does not by itself prove corruption or bad permissions.
21 +## Normal Windows Names
23 +For portable Windows names:
25 +- Do not use control characters U+0000 through U+001F or `<>:"/\|?*`.
26 +- Do not end a component with a space or period; Win32 normally strips them.
27 +- Do not use `.` or `..` as components.
28 +- Do not use `CON`, `PRN`, `AUX`, `NUL`, `COM1` through `COM9`, or `LPT1`
29 + through `LPT9`, regardless of case. An extension does not help: `NUL.txt`
30 + still resolves as `NUL`.
31 +- Treat `:` as the drive/alternate-data-stream separator, not filename text.
32 +- Assume case-insensitive lookup even though case is preserved.
33 +- Keep each component within the filesystem limit. Path-length support depends
34 + on the filesystem, API, application, and whether long paths are enabled.
36 +Use these rules when generating archives, repositories, build output, or shared
37 +files intended for Windows.
39 +## Diagnose
41 +1. Get the exact absolute path, error text, filesystem, and whether the target
42 + is a file or directory.
43 +2. Enumerate the parent rather than probing the suspect name directly:
45 + ```cmd
46 + cmd.exe /d /c dir /a /x "C:\absolute\parent"
47 + ```
49 +3. Classify the failure:
50 + - reserved device name
51 + - trailing space/period or other Win32-invalid name
52 + - path too long for the current tool
53 + - open handle
54 + - ACL/ownership denial
55 + - filesystem corruption supported by disk or event-log errors
56 +4. Prefer the same namespace, share, or program that created the entry when it
57 + can safely rename or remove it.
59 +Never use `Test-Path NUL` or `if exist NUL` to prove a file exists; those can
60 +address the device.
62 +## Extended Paths
64 +For an existing local entry that ordinary Win32 normalization cannot address,
65 +use an exact absolute extended path:
67 +```text
68 +\\?\C:\absolute\path
69 +```
71 +For UNC paths, convert `\\server\share\path` to:
73 +```text
74 +\\?\UNC\server\share\path
75 +```
77 +The `\\?\` prefix bypasses ordinary Win32 parsing; it does not bypass the
78 +filesystem's rules, ACLs, locks, or corruption. Do not combine it with a
79 +relative path.
81 +## Delete Problem Entries
83 +Show the exact target and obtain explicit confirmation first. Reject wildcards,
84 +relative paths, drive/share roots, and ambiguous targets.
86 +File:
88 +```cmd
89 +cmd.exe /d /c del "\\?\C:\absolute\path\NUL"
90 +```
92 +Read-only file, only after reporting why:
94 +```cmd
95 +cmd.exe /d /c del /f "\\?\C:\absolute\path\NUL"
96 +```
98 +Empty directory:
100 +```cmd
101 +cmd.exe /d /c rd "\\?\C:\absolute\path\NUL"
102 +```
104 +Nonempty directory: enumerate its contents and obtain separate recursive-delete
105 +confirmation before running:
107 +```cmd
108 +cmd.exe /d /c rd /s /q "\\?\C:\absolute\path\NUL"
109 +```
111 +Preserve exact spelling, extension, spaces, and periods. Enumerate the parent
112 +again; report success only when the literal entry is absent.
114 +If the extended path still fails, use `dir /a /x` on the parent. Verify the 8.3
115 +short name maps to the exact target before proposing deletion through that name.
117 +## Other Causes
119 +- Open handle: identify and close the owning process before retrying.
120 +- ACL denial: inspect ownership and permissions; request elevation or ownership
121 + changes only when confirmed necessary.
122 +- Deep path: use an extended path, shorten a parent, map a deeper drive/share,
123 + or use a tool that supports the full path.
124 +- Corruption: run filesystem repair only when independent evidence supports it;
125 + an odd filename alone is insufficient.
126 +- Missing parent entry: stop. A successful reference to `NUL` alone is the
127 + null device, not evidence of a file.
129 +## Sources
131 +- [Super User: removing a file named NUL](https://superuser.com/questions/282194/how-do-i-remove-a-file-named-nul-on-windows)
132 +- [Microsoft KB 320081: undeletable NTFS entries](https://learn.microsoft.com/en-us/troubleshoot/windows-server/backup-and-storage/cannot-delete-file-folder-on-ntfs-file-system)
133 +- [Microsoft: Naming Files, Paths, and Namespaces](https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file)
134 +- [Wikipedia: filename limitations](https://en.wikipedia.org/wiki/Filename#Comparison_of_filename_limitations)