Dotfiles Config Skill

Dotfiles Config Skill

Golden Rule

ALWAYS edit files in ~/​dev/​dotfiles/, NEVER edit symlinked files in ~/ or ~/​.config/.

The files in your home directory are symlinks pointing back to this repo. Verify with:

ls -la ~/​.config/​ghostty/​config  # Should show symlink to dotfiles

Repository Structure

~/​dev/​dotfiles/
├── home/                    # Base configs (all platforms)
│   ├── .claude/             # Claude Code config (this skill lives here)
│   ├── .config/             # XDG configs
│   │   ├── alacritty/
│   │   ├── ghostty/
│   │   ├── helix/
│   │   ├── home-manager/    # Nix Home Manager (CLI tools)
│   │   ├── lazygit/
│   │   ├── nvim/
│   │   ├── yazi/
│   │   ├── zellij/
│   │   └── zsh/
│   ├── .bashrc
│   ├── .tmux.conf
│   └── .zshrc
├── home-mac/                # macOS-specific configs
│   └── Brewfile             # GUI apps via Homebrew
├── home-linux/              # Linux-specific configs
├── mac/
│   └── nix-darwin/          # macOS system settings
└── ubuntu/                  # Ubuntu-specific configs

Config File Locations

Package Management

CLI Tools (Nix Home Manager)

Edit: home/​.config/​home-manager/​home.nix Apply: home-manager switch

GUI Apps (macOS Homebrew)

Edit: home-mac/​Brewfile Apply: cd home-mac && brew bundle

Language Runtimes (mise)

Edit: home/​.config/​mise/​config.toml Apply: mise install

macOS System Settings (nix-darwin)

Edit: mac/​nix-darwin/​flake.nix Apply: just nix-darwin-switch

Stow Commands

After adding new config files, re-run stow:

just stow-mac    # macOS
just stow-linux  # Linux
just stow-home   # Just base home/

Skills Location

Skills live in home/​.claude/​skills/ and are symlinked to ~/​.claude/​skills/.

To create a new skill:

1. Create directory: mkdir -p home/​.claude/​skills/​skill-name
2. Create SKILL.md with frontmatter (name, description)
3. Stow will automatically symlink it

Common Mistakes to Avoid

1. Editing symlinked files - Always navigate to ~/​dev/​dotfiles/ first
2. Forgetting to stow - New files need just stow-* to create symlinks
3. Wrong platform directory - macOS GUI apps go in home-mac/, not home/
4. Editing ~/​.config directly - These are symlinks, edit the source in dotfiles

Verification

Before declaring a config change complete:

1. Confirm you edited the file in ~/​dev/​dotfiles/
2. Check the symlink exists: ls -la ~/​.config/<tool>/
3. Test the config works (reload app or run verification command)