# Dotfiles Stow

> REQUIRED when changing configs managed by ~/.config/dotfiles or ~/.config/dotfiles-private. Enforces editing stow source paths (not ad-hoc live paths) and using the dot command for stow/update/validation workflows.

- Skill: `timmo001/dotfiles-stow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add timmo001/dotfiles-stow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/timmo001/dotfiles-stow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: timmo001 (https://skillmd.com/u/timmo001)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/timmo001/dotfiles-stow

---


# Dotfiles Stow Skill

Use this skill for changes to user config managed by GNU Stow through the public `~/.config/dotfiles` source or optional private `~/.config/dotfiles-private` overlay.

## Rules

1. Resolve every live config path to its owning stow source before editing.
2. Keep shared non-sensitive config public and machine-specific or private data in the private overlay.
3. Edit the source repository, never an unmanaged live file.
4. Run `dot stow` after stowed source changes.
5. Create, import, review, and update reusable skills in `~/repos/skills`; never edit `~/.agents/skills` or `agents/.agents/skills` directly. Review third-party updates through `dot skills updates`; normal `dot update` only stows committed snapshots.
6. After every committed or upstream-updated `~/repos/skills` revision, update and commit the `agents/.agents/skills` submodule pointer in `~/.config/dotfiles`. Do not leave the repositories out of sync.
7. Update the canonical docs site when user-facing behaviour, paths, commands, or configuration change.

## Common Paths

- `~/.zshrc` -> `~/.config/dotfiles/zsh/.zshrc`
- `~/.config/nvim/init.lua` -> `~/.config/dotfiles/neovim/.config/nvim/init.lua`
- `~/.agents/skills/dotfiles-stow` -> `~/.config/dotfiles/dotfiles-skills/.agents/skills/dotfiles-stow`
- Shared adapted skills -> `~/repos/skills/<name>`
- Reviewed third-party snapshots -> `~/repos/skills/<name>` plus `imports.json`

Do not run `dot clean` unless the user explicitly asks to remove stowed configuration. Preserve unrelated worktree changes and continue with public-safe work when the private overlay is unavailable.

## Omarchy Host Overrides

- Hyprland config is stowed from `hypr/.config/hypr/`, with host overrides selected through `~/.config/hypr/host`.
- The Hypr package is stowed non-destructively: `dot stow` and `dot install` never unstow it first, so `hyprland.lua` cannot disappear during Hyprland's live reload.
- Keep the generated Omarchy `shell.json`, Lua host layout, and canonical docs in sync when their contracts change.