[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7BS1QSZF64CY9FCB8R161CF":3,"skill-same:01M7BS1QSZF64CY9FCB8R161CF":64},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7BS1QSZF64CY9FCB8R161CF","fhs-xdg-dirs",null,"Decide where files belong on Linux\u002FUnix: FHS spec, XDG base directory spec, and XDG user dirs. Use when writing or reviewing any code, script, package, systemd unit or dotfile setup that reads or writes config, data, state, cache, runtime, log or binary paths, or whenever XDG_* variables, ~\u002F.config, ~\u002F.local, \u002Fetc\u002Fxdg, user-dirs.dirs, home-directory clutter or FHS paths come up.","thimslugga\u002Fagent-plugins","thimslugga","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F285055?v=4","01M7BRYXXABGR31PBN8YW9YYD3","Adam Kaminski","01M7BRYXY1GHRY2VCK15WG8NCZ",0,"MIT","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: \"fhs-xdg-dirs\"\ndescription: \"Decide where files belong on Linux\u002FUnix: FHS spec, XDG base directory spec, and XDG user dirs. Use when writing or reviewing any code, script, package, systemd unit or dotfile setup that reads or writes config, data, state, cache, runtime, log or binary paths, or whenever XDG_* variables, ~\u002F.config, ~\u002F.local, \u002Fetc\u002Fxdg, user-dirs.dirs, home-directory clutter or FHS paths come up.\"\n---\n\n# FHS, XDG base dirs, and XDG user dirs skill\n\nThree standards answer the question \"where does this file go?\":\n\n| Standard                            | Scope                                                            | Current version                           |\n| ----------------------------------- | ---------------------------------------------------------------- | ----------------------------------------- |\n| Filesystem Hierarchy Standard (FHS) | System-wide layout (`\u002Fetc`, `\u002Fusr`, `\u002Fvar`, `\u002Frun`...)           | 3.0 (2015; now hosted by freedesktop.org) |\n| XDG Base Directory Specification    | Per-user application files (config, data, state, cache, runtime) | 0.8, 8 May 2021                           |\n| xdg-user-dirs                       | User-facing folders (Desktop, Downloads, Documents...)           | tool release 0.20 (2026)                  |\n\nNote: FHS 2.3 (2004) is the older baseline that many enterprise docs still cite. The differences that matter are in `references\u002Ffhs.md`.\n\n## How to use this skill\n\n1. Classify each file the software touches with the decision table.\n2. Resolve the path with the rules in \"Resolution rules\". Never hardcode `~\u002F.config` and never write a new dotfile or dot-directory directly in `$HOME`.\n3. For a system service or package, use the FHS column instead of the XDG column.\n4. When reviewing existing code, run the review checklist at the end.\n\n## Decision table\n\nAsk these questions in order. The first \"yes\" wins.\n\n| Question | Per-user (XDG) | System-wide (FHS) |\n|---|---|---|\n| Is it a socket, pid file, lock or named pipe that must not survive logout or reboot? | `$XDG_RUNTIME_DIR\u002F\u003Capp>\u002F` | `\u002Frun\u002F\u003Capp>\u002F` |\n| Can it be deleted at any time with only a speed penalty? | `$XDG_CACHE_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Fcache\u002F\u003Capp>\u002F` |\n| Does the user (or admin) edit it to change behaviour? | `$XDG_CONFIG_HOME\u002F\u003Capp>\u002F` | `\u002Fetc\u002F\u003Capp>\u002F` (vendor defaults: `\u002Fetc\u002Fxdg\u002F\u003Capp>\u002F` or `\u002Fusr\u002Fshare\u002F\u003Capp>\u002F`) |\n| Is it history, logs, undo data, window layout, recently-used lists, a resume position? | `$XDG_STATE_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Flib\u002F\u003Capp>\u002F`, logs in `\u002Fvar\u002Flog\u002F\u003Capp>\u002F` |\n| Is it data the user would want backed up or moved to a new machine (databases, saves, downloaded models, plugins, keys)? | `$XDG_DATA_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Flib\u002F\u003Capp>\u002F` (mutable), `\u002Fusr\u002Fshare\u002F\u003Capp>\u002F` (read-only, shipped) |\n| Is it an executable the user installed? | `$HOME\u002F.local\u002Fbin` | `\u002Fusr\u002Flocal\u002Fbin` (admin), `\u002Fusr\u002Fbin` (package) |\n| Is it a document the user created on purpose? | An XDG user dir (ask `xdg-user-dir DOCUMENTS`), or wherever the user chose | n\u002Fa |\n\nThe config\u002Fstate\u002Fdata split is the one people get wrong. A useful test: if you would commit it to a dotfiles repo it is config; if you would back it up but not commit it, it is data; if losing it is only an annoyance, it is state; if losing it costs nothing but time, it is cache.\n\n## XDG Base Directory variables\n\n| Variable | Default when unset **or empty** | Holds |\n|---|---|---|\n| `XDG_CONFIG_HOME` | `$HOME\u002F.config` | User config |\n| `XDG_DATA_HOME` | `$HOME\u002F.local\u002Fshare` | User data |\n| `XDG_STATE_HOME` | `$HOME\u002F.local\u002Fstate` | Persistent but non-portable state |\n| `XDG_CACHE_HOME` | `$HOME\u002F.cache` | Non-essential cached data |\n| `XDG_RUNTIME_DIR` | **no default** (systemd sets `\u002Frun\u002Fuser\u002F$UID`) | Sockets, locks, pipes |\n| `XDG_CONFIG_DIRS` | `\u002Fetc\u002Fxdg` | Ordered system config search path |\n| `XDG_DATA_DIRS` | `\u002Fusr\u002Flocal\u002Fshare\u002F:\u002Fusr\u002Fshare\u002F` | Ordered system data search path |\n| *(none)* | `$HOME\u002F.local\u002Fbin` | User executables |\n\n`XDG_BIN_HOME`, `XDG_LIB_HOME` and similar are **not** in the spec. Some libraries invent them (adrg\u002Fxdg has `BinHome`). Do not rely on other software honouring them.\n\n### Resolution rules\n\nThese come straight from the spec. Code that skips one of them is non-compliant.\n\n- **Unset and empty are the same.** Use `${VAR:-default}`, not `${VAR-default}`. In other languages test for the empty string as well as absence.\n- **Paths must be absolute.** A relative value is invalid; ignore it and use the default (or skip that entry in a `*_DIRS` list).\n- **`*_DIRS` are colon-separated and ordered**, most important first. The matching `*_HOME` directory outranks every entry.\n- **Lookup** of `app\u002Ffile` checks `$XDG_CONFIG_HOME` then each `$XDG_CONFIG_DIRS` entry (same pattern for data). The spec does not say whether to take the first hit or merge all hits. Decide, and document it. \"First hit wins\" is the common choice for config; layered merge (system defaults, then user overrides) is the friendlier one.\n- **Writes go to `*_HOME` only.** Never write to a `*_DIRS` entry.\n- **Create missing directories with mode `0700`.** Do not change the mode of a directory that already exists.\n- **On read, skip anything missing or unreadable** and carry on with the next directory.\n- **Namespace under an app subdirectory** (`$XDG_CONFIG_HOME\u002Fmyapp\u002Fconfig.toml`). A single bare file directly in `~\u002F.config` is tolerated but scales badly.\n\n### XDG_RUNTIME_DIR\n\n- Owned by the user, mode `0700`, on a local filesystem, created at first login and removed at last logout. Contents do not survive a reboot.\n- It is usually tmpfs, so it counts against RAM. Keep large files out of it.\n- Files can be reaped unless their access time is refreshed at least every 6 hours or they carry the sticky bit.\n- **Do not set it yourself in a shell profile.** `pam_systemd`\u002Flogind creates it, and it is the only XDG variable a typical distro sets by default. Pointing it somewhere else can break PipeWire and browser screen sharing. If it is unset (cron, `su` without a login session, minimal containers, macOS), fall back to a private `0700` directory such as `$(mktemp -d)` or `${TMPDIR:-\u002Ftmp}\u002F\u003Capp>-$UID`, verify ownership and mode before use, and print a warning. For long-running services on headless hosts, `loginctl enable-linger \u003Cuser>` keeps `\u002Frun\u002Fuser\u002F$UID` alive.\n\n### ~\u002F.local\u002Fbin\n\nDistributions should put it on `PATH`. Because `$HOME` may be shared between machines of different architectures, compiled binaries here can break on the other host; mention that when a user has an NFS or synced home.\n\n## Reference implementations\n\nRead `references\u002Fimplementations.md` before writing path-resolution code. It has tested POSIX sh and stdlib Python helpers that apply every rule above, the `github.com\u002Fadrg\u002Fxdg` Go API with its per-OS default table and a Koanf load-order note, and the Rust crate options. Reuse those instead of writing a quick `os.path.expanduser(\"~\u002F.config\")`.\n\n### macOS policy\n\nThe XDG variables are not set on macOS. Libraries disagree: adrg\u002Fxdg, `directories` and `platformdirs` map to `~\u002FLibrary\u002F...`, while most CLI tools (git, neovim, fish) use `~\u002F.config` there too. For a CLI tool, the least surprising behaviour is: honour `XDG_*` when set, otherwise use the Linux defaults on macOS as well. For a GUI app, use `~\u002FLibrary`. State which policy the tool follows in its README.\n\n## XDG user directories (xdg-user-dirs)\n\nThese are the visible folders in a home directory. They are a separate mechanism from the base dirs.\n\n| Name | Key in `user-dirs.dirs` | Default (English) |\n|---|---|---|\n| DESKTOP | `XDG_DESKTOP_DIR` | `~\u002FDesktop` |\n| DOWNLOAD | `XDG_DOWNLOAD_DIR` | `~\u002FDownloads` |\n| TEMPLATES | `XDG_TEMPLATES_DIR` | `~\u002FTemplates` |\n| PUBLICSHARE | `XDG_PUBLICSHARE_DIR` | `~\u002FPublic` |\n| DOCUMENTS | `XDG_DOCUMENTS_DIR` | `~\u002FDocuments` |\n| MUSIC | `XDG_MUSIC_DIR` | `~\u002FMusic` |\n| PICTURES | `XDG_PICTURES_DIR` | `~\u002FPictures` |\n| VIDEOS | `XDG_VIDEOS_DIR` | `~\u002FVideos` |\n| PROJECTS | `XDG_PROJECTS_DIR` | `~\u002FProjects` (created by default from 0.20) |\n\n**These are not environment variables.** They are lines in a file. A script that reads `$XDG_DOWNLOAD_DIR` from the environment gets an empty string on almost every system, and the folder names are translated per locale, so `~\u002FDownloads` is also wrong for many users. Ask the tool:\n\n```sh\ndownloads=$(xdg-user-dir DOWNLOAD)     # prints $HOME if the dir is disabled\n```\n\nIf the tool is missing, fall back to `$HOME`. In GLib code use `g_get_user_special_dir()`.\n\nRead `references\u002Fuser-dirs.md` when changing, disabling, localising or administering these directories. It covers the four config files (`user-dirs.dirs`, `user-dirs.locale`, `user-dirs.defaults`, `user-dirs.conf`), the `xdg-user-dirs-update` options, login-time behaviour, how to disable a directory, and the `eval` issue in `xdg-user-dir` before 0.20.\n\n## FHS and XDG side by side\n\n| Role | System (FHS) | User (XDG) | systemd directive | Specifier |\n|---|---|---|---|---|\n| Config | `\u002Fetc` | `$XDG_CONFIG_HOME` | `ConfigurationDirectory=` | `%E` |\n| State | `\u002Fvar\u002Flib` | `$XDG_STATE_HOME` | `StateDirectory=` | `%S` |\n| Cache | `\u002Fvar\u002Fcache` | `$XDG_CACHE_HOME` | `CacheDirectory=` | `%C` |\n| Logs | `\u002Fvar\u002Flog` | `$XDG_STATE_HOME\u002Flog` | `LogsDirectory=` | `%L` |\n| Runtime | `\u002Frun` | `$XDG_RUNTIME_DIR` | `RuntimeDirectory=` | `%t` |\n| Read-only data | `\u002Fusr\u002Fshare`, `\u002Fusr\u002Flocal\u002Fshare` | `$XDG_DATA_HOME` | | |\n| Executables | `\u002Fusr\u002Fbin`, `\u002Fusr\u002Flocal\u002Fbin` | `~\u002F.local\u002Fbin` | | |\n\nPrefer the systemd directives over `mkdir` in `ExecStartPre=`: systemd creates the directory with the right owner and exports `CONFIGURATION_DIRECTORY`, `STATE_DIRECTORY`, `CACHE_DIRECTORY`, `LOGS_DIRECTORY` and `RUNTIME_DIRECTORY` to the process. The user-unit mappings have changed between systemd releases, so confirm against `man systemd.exec` and `man systemd.unit` on the target. `systemd-path` prints what the running system resolves:\n\n```sh\nsystemd-path user-configuration user-state-private user-state-cache user-runtime\n```\n\nA tool that runs both as root daemon and as a user should pick by effective UID: FHS paths for UID 0 or a system user, XDG paths otherwise, with the systemd-provided environment variables taking priority when present.\n\nRead `references\u002Ffhs.md` for the full FHS 3.0 directory table, the shareable\u002Fstatic classification, what changed from FHS 2.3 (`\u002Frun`, `\u002Fusr\u002Flibexec`, `\u002Fvar\u002Frun`), merged `\u002Fusr`, and the path caveats on ostree systems (Fedora Atomic Desktops, IoT, CoreOS), bootc images, Flatpak and containers. Read it whenever the target is a system service, a package, or an immutable or sandboxed host.\n\n## Setting the variables for a login session\n\nMost users should leave the `*_HOME` variables unset; the defaults are the standard. Set them only to relocate a directory. On a systemd desktop the reliable place is `~\u002F.config\u002Fenvironment.d\u002F*.conf`, because it reaches graphical apps and user services as well as shells:\n\n```sh\nmkdir -p ~\u002F.config\u002Fenvironment.d\nvi ~\u002F.config\u002Fenvironment.d\u002F10-xdg.conf\n```\n\n```ini\nXDG_CONFIG_HOME=${HOME}\u002F.config\nXDG_DATA_HOME=${HOME}\u002F.local\u002Fshare\nXDG_STATE_HOME=${HOME}\u002F.local\u002Fstate\nXDG_CACHE_HOME=${HOME}\u002F.cache\n```\n\nFor shells without systemd (macOS, Alpine, ssh-only hosts), export the same four in `~\u002F.profile` or `~\u002F.zshenv`. Never export `XDG_RUNTIME_DIR` by hand.\n\n## Cleaning up `$HOME`\n\nRead `references\u002Fapplications.md` when the user wants to move a specific tool's dotfiles, audit a cluttered home directory, or asks whether an application supports XDG. It lists, per application, the legacy path and the exact environment variable, alias or config line that relocates it (shells, core tools, languages and build tools, cloud and container CLIs, databases), plus which applications are already compliant and which are hardcoded and should be left alone. It also covers `xdg-ninja` and `boxxy`.\n\nDo not quote a relocation variable from memory when that file has an entry; the details (config vs state vs data, minimum versions, directories that must exist first) are easy to get wrong.\n\n## Review checklist\n\nWhen reviewing code, a package or a dotfile setup, check each of these and report violations with the fix:\n\n1. No new dotfile or dot-directory directly in `$HOME`.\n2. No literal `~\u002F.config`, `~\u002F.cache`, `~\u002F.local\u002Fshare`, `\u002Fhome\u002F\u003Cuser>` or `\u002Frun\u002Fuser\u002F1000`.\n3. Empty-string variables fall back to the default (`:-`, not `-`).\n4. Relative values are rejected.\n5. Config lookup walks `XDG_CONFIG_HOME` then `XDG_CONFIG_DIRS`; first-hit or merge behaviour is documented.\n6. Writes go only to `*_HOME`; new directories are `0700`; existing modes are untouched.\n7. Logs and history are in state, not config or data. Caches are safe to `rm -rf`.\n8. Sockets and locks are in `XDG_RUNTIME_DIR`, with a checked `0700` fallback and a warning when it is unset.\n9. User folders come from `xdg-user-dir`, never from `$XDG_*_DIR` in the environment or a literal English name.\n10. A tool moving from a legacy path keeps reading the old location if it exists, and tells the user how to migrate. It does not silently split state across both.\n11. System services use FHS paths through systemd `*Directory=` directives, and `\u002Frun` instead of `\u002Fvar\u002Frun`.\n12. Tests override `HOME` and the `XDG_*` variables with a temp directory so they never touch the real home.\n\n## Sources\n\n- FHS 3.0: \u003Chttps:\u002F\u002Fspecifications.freedesktop.org\u002Ffhs\u002Flatest\u002F> and \u003Chttps:\u002F\u002Frefspecs.linuxfoundation.org\u002FFHS_3.0\u002Ffhs\u002Findex.html>\n- FHS 2.3: \u003Chttps:\u002F\u002Fwww.pathname.com\u002Ffhs\u002Fpub\u002Ffhs-2.3.html> and \u003Chttps:\u002F\u002Fwww.pathname.com\u002Ffhs\u002F>\n- XDG Base Directory Specification 0.8: \u003Chttps:\u002F\u002Fspecifications.freedesktop.org\u002Fbasedir\u002Flatest\u002F>\n- xdg-user-dirs: \u003Chttps:\u002F\u002Fwww.freedesktop.org\u002Fwiki\u002FSoftware\u002Fxdg-user-dirs\u002F> and the `xdg-user-dirs-update(1)`, `user-dirs.dirs(5)`, `user-dirs.defaults(5)`, `user-dirs.conf(5)` man pages\n- Arch Wiki: \u003Chttps:\u002F\u002Fwiki.archlinux.org\u002Ftitle\u002FXDG_Base_Directory> and \u003Chttps:\u002F\u002Fwiki.archlinux.org\u002Ftitle\u002FXDG_user_directories>\n- adrg\u002Fxdg (Go): \u003Chttps:\u002F\u002Fgithub.com\u002Fadrg\u002Fxdg>\n","# FHS, XDG base dirs, and XDG user dirs skill\n\nThree standards answer the question \"where does this file go?\":\n\n| Standard                            | Scope                                                            | Current version                           |\n| ----------------------------------- | ---------------------------------------------------------------- | ----------------------------------------- |\n| Filesystem Hierarchy Standard (FHS) | System-wide layout (`\u002Fetc`, `\u002Fusr`, `\u002Fvar`, `\u002Frun`...)           | 3.0 (2015; now hosted by freedesktop.org) |\n| XDG Base Directory Specification    | Per-user application files (config, data, state, cache, runtime) | 0.8, 8 May 2021                           |\n| xdg-user-dirs                       | User-facing folders (Desktop, Downloads, Documents...)           | tool release 0.20 (2026)                  |\n\nNote: FHS 2.3 (2004) is the older baseline that many enterprise docs still cite. The differences that matter are in `references\u002Ffhs.md`.\n\n## How to use this skill\n\n1. Classify each file the software touches with the decision table.\n2. Resolve the path with the rules in \"Resolution rules\". Never hardcode `~\u002F.config` and never write a new dotfile or dot-directory directly in `$HOME`.\n3. For a system service or package, use the FHS column instead of the XDG column.\n4. When reviewing existing code, run the review checklist at the end.\n\n## Decision table\n\nAsk these questions in order. The first \"yes\" wins.\n\n| Question | Per-user (XDG) | System-wide (FHS) |\n|---|---|---|\n| Is it a socket, pid file, lock or named pipe that must not survive logout or reboot? | `$XDG_RUNTIME_DIR\u002F\u003Capp>\u002F` | `\u002Frun\u002F\u003Capp>\u002F` |\n| Can it be deleted at any time with only a speed penalty? | `$XDG_CACHE_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Fcache\u002F\u003Capp>\u002F` |\n| Does the user (or admin) edit it to change behaviour? | `$XDG_CONFIG_HOME\u002F\u003Capp>\u002F` | `\u002Fetc\u002F\u003Capp>\u002F` (vendor defaults: `\u002Fetc\u002Fxdg\u002F\u003Capp>\u002F` or `\u002Fusr\u002Fshare\u002F\u003Capp>\u002F`) |\n| Is it history, logs, undo data, window layout, recently-used lists, a resume position? | `$XDG_STATE_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Flib\u002F\u003Capp>\u002F`, logs in `\u002Fvar\u002Flog\u002F\u003Capp>\u002F` |\n| Is it data the user would want backed up or moved to a new machine (databases, saves, downloaded models, plugins, keys)? | `$XDG_DATA_HOME\u002F\u003Capp>\u002F` | `\u002Fvar\u002Flib\u002F\u003Capp>\u002F` (mutable), `\u002Fusr\u002Fshare\u002F\u003Capp>\u002F` (read-only, shipped) |\n| Is it an executable the user installed? | `$HOME\u002F.local\u002Fbin` | `\u002Fusr\u002Flocal\u002Fbin` (admin), `\u002Fusr\u002Fbin` (package) |\n| Is it a document the user created on purpose? | An XDG user dir (ask `xdg-user-dir DOCUMENTS`), or wherever the user chose | n\u002Fa |\n\nThe config\u002Fstate\u002Fdata split is the one people get wrong. A useful test: if you would commit it to a dotfiles repo it is config; if you would back it up but not commit it, it is data; if losing it is only an annoyance, it is state; if losing it costs nothing but time, it is cache.\n\n## XDG Base Directory variables\n\n| Variable | Default when unset **or empty** | Holds |\n|---|---|---|\n| `XDG_CONFIG_HOME` | `$HOME\u002F.config` | User config |\n| `XDG_DATA_HOME` | `$HOME\u002F.local\u002Fshare` | User data |\n| `XDG_STATE_HOME` | `$HOME\u002F.local\u002Fstate` | Persistent but non-portable state |\n| `XDG_CACHE_HOME` | `$HOME\u002F.cache` | Non-essential cached data |\n| `XDG_RUNTIME_DIR` | **no default** (systemd sets `\u002Frun\u002Fuser\u002F$UID`) | Sockets, locks, pipes |\n| `XDG_CONFIG_DIRS` | `\u002Fetc\u002Fxdg` | Ordered system config search path |\n| `XDG_DATA_DIRS` | `\u002Fusr\u002Flocal\u002Fshare\u002F:\u002Fusr\u002Fshare\u002F` | Ordered system data search path |\n| *(none)* | `$HOME\u002F.local\u002Fbin` | User executables |\n\n`XDG_BIN_HOME`, `XDG_LIB_HOME` and similar are **not** in the spec. Some libraries invent them (adrg\u002Fxdg has `BinHome`). Do not rely on other software honouring them.\n\n### Resolution rules\n\nThese come straight from the spec. Code that skips one of them is non-compliant.\n\n- **Unset and empty are the same.** Use `${VAR:-default}`, not `${VAR-default}`. In other languages test for the empty string as well as absence.\n- **Paths must be absolute.** A relative value is invalid; ignore it and use the default (or skip that entry in a `*_DIRS` list).\n- **`*_DIRS` are colon-separated and ordered**, most important first. The matching `*_HOME` directory outranks every entry.\n- **Lookup** of `app\u002Ffile` checks `$XDG_CONFIG_HOME` then each `$XDG_CONFIG_DIRS` entry (same pattern for data). The spec does not say whether to take the first hit or merge all hits. Decide, and document it. \"First hit wins\" is the common choice for config; layered merge (system defaults, then user overrides) is the friendlier one.\n- **Writes go to `*_HOME` only.** Never write to a `*_DIRS` entry.\n- **Create missing directories with mode `0700`.** Do not change the mode of a directory that already exists.\n- **On read, skip anything missing or unreadable** and carry on with the next directory.\n- **Namespace under an app subdirectory** (`$XDG_CONFIG_HOME\u002Fmyapp\u002Fconfig.toml`). A single bare file directly in `~\u002F.config` is tolerated but scales badly.\n\n### XDG_RUNTIME_DIR\n\n- Owned by the user, mode `0700`, on a local filesystem, created at first login and removed at last logout. Contents do not survive a reboot.\n- It is usually tmpfs, so it counts against RAM. Keep large files out of it.\n- Files can be reaped unless their access time is refreshed at least every 6 hours or they carry the sticky bit.\n- **Do not set it yourself in a shell profile.** `pam_systemd`\u002Flogind creates it, and it is the only XDG variable a typical distro sets by default. Pointing it somewhere else can break PipeWire and browser screen sharing. If it is unset (cron, `su` without a login session, minimal containers, macOS), fall back to a private `0700` directory such as `$(mktemp -d)` or `${TMPDIR:-\u002Ftmp}\u002F\u003Capp>-$UID`, verify ownership and mode before use, and print a warning. For long-running services on headless hosts, `loginctl enable-linger \u003Cuser>` keeps `\u002Frun\u002Fuser\u002F$UID` alive.\n\n### ~\u002F.local\u002Fbin\n\nDistributions should put it on `PATH`. Because `$HOME` may be shared between machines of different architectures, compiled binaries here can break on the other host; mention that when a user has an NFS or synced home.\n\n## Reference implementations\n\nRead `references\u002Fimplementations.md` before writing path-resolution code. It has tested POSIX sh and stdlib Python helpers that apply every rule above, the `github.com\u002Fadrg\u002Fxdg` Go API with its per-OS default table and a Koanf load-order note, and the Rust crate options. Reuse those instead of writing a quick `os.path.expanduser(\"~\u002F.config\")`.\n\n### macOS policy\n\nThe XDG variables are not set on macOS. Libraries disagree: adrg\u002Fxdg, `directories` and `platformdirs` map to `~\u002FLibrary\u002F...`, while most CLI tools (git, neovim, fish) use `~\u002F.config` there too. For a CLI tool, the least surprising behaviour is: honour `XDG_*` when set, otherwise use the Linux defaults on macOS as well. For a GUI app, use `~\u002FLibrary`. State which policy the tool follows in its README.\n\n## XDG user directories (xdg-user-dirs)\n\nThese are the visible folders in a home directory. They are a separate mechanism from the base dirs.\n\n| Name | Key in `user-dirs.dirs` | Default (English) |\n|---|---|---|\n| DESKTOP | `XDG_DESKTOP_DIR` | `~\u002FDesktop` |\n| DOWNLOAD | `XDG_DOWNLOAD_DIR` | `~\u002FDownloads` |\n| TEMPLATES | `XDG_TEMPLATES_DIR` | `~\u002FTemplates` |\n| PUBLICSHARE | `XDG_PUBLICSHARE_DIR` | `~\u002FPublic` |\n| DOCUMENTS | `XDG_DOCUMENTS_DIR` | `~\u002FDocuments` |\n| MUSIC | `XDG_MUSIC_DIR` | `~\u002FMusic` |\n| PICTURES | `XDG_PICTURES_DIR` | `~\u002FPictures` |\n| VIDEOS | `XDG_VIDEOS_DIR` | `~\u002FVideos` |\n| PROJECTS | `XDG_PROJECTS_DIR` | `~\u002FProjects` (created by default from 0.20) |\n\n**These are not environment variables.** They are lines in a file. A script that reads `$XDG_DOWNLOAD_DIR` from the environment gets an empty string on almost every system, and the folder names are translated per locale, so `~\u002FDownloads` is also wrong for many users. Ask the tool:\n\n```sh\ndownloads=$(xdg-user-dir DOWNLOAD)     # prints $HOME if the dir is disabled\n```\n\nIf the tool is missing, fall back to `$HOME`. In GLib code use `g_get_user_special_dir()`.\n\nRead `references\u002Fuser-dirs.md` when changing, disabling, localising or administering these directories. It covers the four config files (`user-dirs.dirs`, `user-dirs.locale`, `user-dirs.defaults`, `user-dirs.conf`), the `xdg-user-dirs-update` options, login-time behaviour, how to disable a directory, and the `eval` issue in `xdg-user-dir` before 0.20.\n\n## FHS and XDG side by side\n\n| Role | System (FHS) | User (XDG) | systemd directive | Specifier |\n|---|---|---|---|---|\n| Config | `\u002Fetc` | `$XDG_CONFIG_HOME` | `ConfigurationDirectory=` | `%E` |\n| State | `\u002Fvar\u002Flib` | `$XDG_STATE_HOME` | `StateDirectory=` | `%S` |\n| Cache | `\u002Fvar\u002Fcache` | `$XDG_CACHE_HOME` | `CacheDirectory=` | `%C` |\n| Logs | `\u002Fvar\u002Flog` | `$XDG_STATE_HOME\u002Flog` | `LogsDirectory=` | `%L` |\n| Runtime | `\u002Frun` | `$XDG_RUNTIME_DIR` | `RuntimeDirectory=` | `%t` |\n| Read-only data | `\u002Fusr\u002Fshare`, `\u002Fusr\u002Flocal\u002Fshare` | `$XDG_DATA_HOME` | | |\n| Executables | `\u002Fusr\u002Fbin`, `\u002Fusr\u002Flocal\u002Fbin` | `~\u002F.local\u002Fbin` | | |\n\nPrefer the systemd directives over `mkdir` in `ExecStartPre=`: systemd creates the directory with the right owner and exports `CONFIGURATION_DIRECTORY`, `STATE_DIRECTORY`, `CACHE_DIRECTORY`, `LOGS_DIRECTORY` and `RUNTIME_DIRECTORY` to the process. The user-unit mappings have changed between systemd releases, so confirm against `man systemd.exec` and `man systemd.unit` on the target. `systemd-path` prints what the running system resolves:\n\n```sh\nsystemd-path user-configuration user-state-private user-state-cache user-runtime\n```\n\nA tool that runs both as root daemon and as a user should pick by effective UID: FHS paths for UID 0 or a system user, XDG paths otherwise, with the systemd-provided environment variables taking priority when present.\n\nRead `references\u002Ffhs.md` for the full FHS 3.0 directory table, the shareable\u002Fstatic classification, what changed from FHS 2.3 (`\u002Frun`, `\u002Fusr\u002Flibexec`, `\u002Fvar\u002Frun`), merged `\u002Fusr`, and the path caveats on ostree systems (Fedora Atomic Desktops, IoT, CoreOS), bootc images, Flatpak and containers. Read it whenever the target is a system service, a package, or an immutable or sandboxed host.\n\n## Setting the variables for a login session\n\nMost users should leave the `*_HOME` variables unset; the defaults are the standard. Set them only to relocate a directory. On a systemd desktop the reliable place is `~\u002F.config\u002Fenvironment.d\u002F*.conf`, because it reaches graphical apps and user services as well as shells:\n\n```sh\nmkdir -p ~\u002F.config\u002Fenvironment.d\nvi ~\u002F.config\u002Fenvironment.d\u002F10-xdg.conf\n```\n\n```ini\nXDG_CONFIG_HOME=${HOME}\u002F.config\nXDG_DATA_HOME=${HOME}\u002F.local\u002Fshare\nXDG_STATE_HOME=${HOME}\u002F.local\u002Fstate\nXDG_CACHE_HOME=${HOME}\u002F.cache\n```\n\nFor shells without systemd (macOS, Alpine, ssh-only hosts), export the same four in `~\u002F.profile` or `~\u002F.zshenv`. Never export `XDG_RUNTIME_DIR` by hand.\n\n## Cleaning up `$HOME`\n\nRead `references\u002Fapplications.md` when the user wants to move a specific tool's dotfiles, audit a cluttered home directory, or asks whether an application supports XDG. It lists, per application, the legacy path and the exact environment variable, alias or config line that relocates it (shells, core tools, languages and build tools, cloud and container CLIs, databases), plus which applications are already compliant and which are hardcoded and should be left alone. It also covers `xdg-ninja` and `boxxy`.\n\nDo not quote a relocation variable from memory when that file has an entry; the details (config vs state vs data, minimum versions, directories that must exist first) are easy to get wrong.\n\n## Review checklist\n\nWhen reviewing code, a package or a dotfile setup, check each of these and report violations with the fix:\n\n1. No new dotfile or dot-directory directly in `$HOME`.\n2. No literal `~\u002F.config`, `~\u002F.cache`, `~\u002F.local\u002Fshare`, `\u002Fhome\u002F\u003Cuser>` or `\u002Frun\u002Fuser\u002F1000`.\n3. Empty-string variables fall back to the default (`:-`, not `-`).\n4. Relative values are rejected.\n5. Config lookup walks `XDG_CONFIG_HOME` then `XDG_CONFIG_DIRS`; first-hit or merge behaviour is documented.\n6. Writes go only to `*_HOME`; new directories are `0700`; existing modes are untouched.\n7. Logs and history are in state, not config or data. Caches are safe to `rm -rf`.\n8. Sockets and locks are in `XDG_RUNTIME_DIR`, with a checked `0700` fallback and a warning when it is unset.\n9. User folders come from `xdg-user-dir`, never from `$XDG_*_DIR` in the environment or a literal English name.\n10. A tool moving from a legacy path keeps reading the old location if it exists, and tells the user how to migrate. It does not silently split state across both.\n11. System services use FHS paths through systemd `*Directory=` directives, and `\u002Frun` instead of `\u002Fvar\u002Frun`.\n12. Tests override `HOME` and the `XDG_*` variables with a temp directory so they never touch the real home.\n\n## Sources\n\n- FHS 3.0: \u003Chttps:\u002F\u002Fspecifications.freedesktop.org\u002Ffhs\u002Flatest\u002F> and \u003Chttps:\u002F\u002Frefspecs.linuxfoundation.org\u002FFHS_3.0\u002Ffhs\u002Findex.html>\n- FHS 2.3: \u003Chttps:\u002F\u002Fwww.pathname.com\u002Ffhs\u002Fpub\u002Ffhs-2.3.html> and \u003Chttps:\u002F\u002Fwww.pathname.com\u002Ffhs\u002F>\n- XDG Base Directory Specification 0.8: \u003Chttps:\u002F\u002Fspecifications.freedesktop.org\u002Fbasedir\u002Flatest\u002F>\n- xdg-user-dirs: \u003Chttps:\u002F\u002Fwww.freedesktop.org\u002Fwiki\u002FSoftware\u002Fxdg-user-dirs\u002F> and the `xdg-user-dirs-update(1)`, `user-dirs.dirs(5)`, `user-dirs.defaults(5)`, `user-dirs.conf(5)` man pages\n- Arch Wiki: \u003Chttps:\u002F\u002Fwiki.archlinux.org\u002Ftitle\u002FXDG_Base_Directory> and \u003Chttps:\u002F\u002Fwiki.archlinux.org\u002Ftitle\u002FXDG_user_directories>\n- adrg\u002Fxdg (Go): \u003Chttps:\u002F\u002Fgithub.com\u002Fadrg\u002Fxdg>\n",{"name":5,"description":7},"main","62177b0f31651c18aefb738bccb54168b8a5a982","plugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins","https:\u002F\u002Fgithub.com\u002Fthimslugga","https:\u002F\u002Fadamkaminski.com","I am interested in Linux, macOS, Python, Golang, Rust and Networking.\r\n\r\nOpinions expressed are my own and may not be the views of my employer.","2026-11-11 02:10:30",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add thimslugga\u002Fagent-plugins --skill fhs-xdg-dirs",{"tool":38,"command":39},"bunx","bunx skills add thimslugga\u002Fagent-plugins --skill fhs-xdg-dirs",{"tool":41,"command":42},"pnpm","pnpm dlx skills add thimslugga\u002Fagent-plugins --skill fhs-xdg-dirs","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002FSKILL.md",true,[46,52,56,60],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Fapplications.md","REFERENCE","参考文档",12992,"https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002Freferences\u002Fapplications.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Ffhs.md",9804,"https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002Freferences\u002Ffhs.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fimplementations.md",4370,"https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002Freferences\u002Fimplementations.md",{"path":61,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fuser-dirs.md",2137,"https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fbuilder\u002Fskills\u002Ffhs-xdg-dirs\u002Freferences\u002Fuser-dirs.md",[65,72,79,86,92,99],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M7BSDA3CNHHP07666X3H90CB","shell-script-expert","Use when the user asks \"review this script\", \"write a bash script\", \"fix my shell script\", \"make this script safer\", \"why does this script fail\", \"convert this to a script\", or working with .sh\u002F.bash files, sh\u002Fbash syntax, shellcheck, cronjobs, and bash one-liners.","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Fshell-script-expert\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7BSD6STC24Q13N4J8E0T93X","prose-synthesize","Turn unstructured notes into a structured, actionable plan. Use when given brain dumps, stream-of-consciousness, or scattered thoughts needing order.","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Fprose-synthesize\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7BSD16KRRWFMM3EN1WPK8G3","prose-distill","Condense verbose text to its essence.  Use when asked to condense, tighten, shorten, reduce verbosity, or omit needless words while preserving substance.","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Fprose-distill\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7BSCYJWSP5VJK3822XRNXR2","mindcraft","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Fmindcraft\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7BSCRQ1GCDCTPNZ3WA3R0JE","learn","Tutor for intellectual understanding: teach how or why something works rather than complete a task or provide an evaluative verdict.\nTrigger for explicit learning requests (teach, explain, ELI5, walkthroughs, quizzes, flashcards, definitions); terse concept prompts; confusion signals; prerequisite or sequencing questions; and conceptual questions about mechanisms, causes, or dynamics.\nDo not trigger for task completion (coding, writing, calculation, or translation), factual or news lookup, personal troubleshooting, resource recommendations, or opinion and interpretive verdicts.","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Flearn\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7BSCNAY02WX6BGDW06Y60D9","deployment-readiness","Use to check deployment readiness of a host.","https:\u002F\u002Fgithub.com\u002Fthimslugga\u002Fagent-plugins\u002Fblob\u002Fmain\u002Fskills\u002Fdeployment-readiness\u002FSKILL.md",[],[]]