dotfiles-config

majiayu000's avatarfrom majiayu000

Use when editing ANY configuration file in this dotfiles repository. Ensures files are edited in the repo (not symlinks), identifies correct file locations, and tracks the repository structure.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 5, 2026
[Developer Tools]

When & Why to Use This Skill

This Claude skill optimizes the management of dotfiles repositories by enforcing best practices for configuration editing. It ensures that changes are made directly to source files in the repository rather than symlinks, maintains a clear mapping of tool-specific paths, and supports cross-platform environment synchronization for tools like Neovim, Zsh, and Nix.

Use Cases

  • Safely updating configuration files for terminal emulators, shells, and editors (e.g., Ghostty, Neovim, Zsh) without accidentally breaking symlink structures.
  • Managing platform-specific settings for macOS (Homebrew/nix-darwin) and Linux within a single, organized repository hierarchy.
  • Automating the deployment and verification of new configuration files using GNU Stow and platform-specific package managers like Nix Home Manager.
  • Maintaining a consistent development environment across multiple machines by tracking the internal repository structure and avoiding common pathing mistakes.
namedotfiles-config
descriptionUse when editing ANY configuration file in this dotfiles repository. Ensures files are edited in the repo (not symlinks), identifies correct file locations, and tracks the repository structure.

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

Tool Dotfiles Location Symlinked To
Alacritty home/.config/alacritty/ ~/.config/alacritty/
Claude Code home/.claude/ ~/.claude/
Ghostty home/.config/ghostty/ ~/.config/ghostty/
Helix home/.config/helix/ ~/.config/helix/
Home Manager home/.config/home-manager/ ~/.config/home-manager/
Lazygit home/.config/lazygit/ ~/.config/lazygit/
Neovim home/.config/nvim/ ~/.config/nvim/
Ripgrep home/.config/rg/ ~/.config/rg/
Starship home/.config/starship.toml ~/.config/starship.toml
Tmux home/.tmux.conf ~/.tmux.conf
Yazi home/.config/yazi/ ~/.config/yazi/
Zellij home/.config/zellij/ ~/.config/zellij/
Zsh home/.zshrc, home/.config/zsh/ ~/.zshrc, ~/.config/zsh/

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)