Agent-Skills.md

Agent Skills: Managing Personal Dotfiles with Yadm

Use this skill when working with personal dotfiles managed by yadm. This includes pulling remote changes, committing and pushing dotfile changes, modifying configuration files (shell, editor, terminal, git, etc.), viewing tracked files, resolving merge conflicts, and maintaining the dotfiles repository. For work dotfiles, use the managing-work-dotfiles skill instead.

UncategorizedID: tdhopper/dotfiles2.0/managing-dotfiles

Repository

tdhopper/dotfiles2.0
tdhopper
73

Install this agent skill to your local

pnpm dlx add-skill https://github.com/tdhopper/dotfiles2.0/tree/HEAD/.claude/skills/managing-dotfiles

Skill Files

Browse the full folder contents for managing-dotfiles.

Download Skill

Loading file tree…

.claude/skills/managing-dotfiles/SKILL.md

Skill Metadata

Name
managing-dotfiles
Description
Use this skill when working with personal dotfiles managed by yadm. This includes pulling remote changes, committing and pushing dotfile changes, modifying configuration files (shell, editor, terminal, git, etc.), viewing tracked files, resolving merge conflicts, and maintaining the dotfiles repository. For work dotfiles, use the managing-work-dotfiles skill instead.

Managing Personal Dotfiles with Yadm

This skill manages personal dotfiles using yadm (Yet Another Dotfiles Manager).

Note: For work-specific dotfiles (Spotify GHE), use the managing-work-dotfiles skill with yadm-work commands.

Repository Info

  • Remote: Your dotfiles git repository
  • Work tree: $HOME
  • Yadm repo: ~/.local/share/yadm/repo.git

Getting Current State

Always start by checking the current state:

yadm status          # Show modified/staged files
yadm ls-files        # List all tracked files
yadm diff            # Show unstaged changes

Managed Files Reference

Run yadm ls-files to get the authoritative list. Common categories:

| Category | Files | |----------|-------| | Shell | .config/fish/ (config.fish, aliases, env, functions, keybindings, plugins) | | Editor | .vimrc, Library/Application Support/Code/User/ (settings.json, keybindings.json) | | Terminal | .tmux.conf, .config/ghostty/config, .config/starship.toml | | Git | .gitconfig, .gitignore, .gitmodules | | Claude | .claude/skills/ (commit, creating-pull-requests, managing-dotfiles) | | Yadm | .config/yadm/ (bootstrap, hooks, README, install-hooks.sh) | | Other | .config/bat/config, .config/ruff/pyproject.toml, .duti, .hushlogin, Caddyfile |

Core Operations

Pull from Remote

yadm pull

If merge conflicts occur:

  1. Run yadm status to see conflicted files
  2. Edit files to resolve conflicts (remove conflict markers)
  3. Stage resolved files: yadm add <file>
  4. Complete the merge: yadm commit

Commit and Push Changes

yadm add <file>           # Stage specific file
yadm add -u               # Stage all modified tracked files
yadm commit -m "message"  # Commit with message
yadm push                 # Push to remote

Commit conventions (from commit skill):

  • No AI/Claude attribution
  • No Co-Authored-By headers

Modify Configuration Files

When asked to modify a config (e.g., "update tmux to do X"):

  1. Find the relevant file: yadm ls-files | grep -i tmux
  2. Read and understand the current config
  3. Make the requested changes
  4. Stage, commit, and push: 
    yadm add <modified-file>
yadm commit -m "Update <config> to <what was changed>"
yadm push

Adding/Removing Files

Add a new file to tracking

yadm add <new-file>
yadm commit -m "Add <file> to dotfiles"
yadm push

Stop tracking a file (without deleting it)

yadm rm --cached <file>
yadm commit -m "Stop tracking <file>"
yadm push

Pre-commit Hooks

Pre-commit is configured via ~/.pre-commit-config.yaml. Hooks check for:

  • Private keys and secrets
  • Large files (>500KB)
  • Trailing whitespace
  • Merge conflicts

Run manually:

yadm enter pre-commit run --all-files

If a commit fails due to pre-commit fixes, stage the fixes and retry.

Self-Management

This skill is itself tracked by yadm at ~/.claude/skills/managing-dotfiles/.

When updating this skill:

  1. Make changes to the skill files
  2. Commit with yadm: 
    yadm add ~/.claude/skills/managing-dotfiles/
yadm commit -m "Update managing-dotfiles skill"
yadm push

When files are added/removed from yadm tracking, update the "Managed Files Reference" section above if the categories change significantly.

Useful Commands

See yadm-command-reference.md for a quick reference of common yadm commands.

Bootstrap (New System Setup)

On a new system after cloning:

yadm bootstrap

This runs ~/.config/yadm/bootstrap which installs Homebrew, uv, vim-plug, and other dependencies.