~/dotfiles

My macOS dev setup and 20 agent skills for Claude Code and Cursor, linked into place by one Makefile.

Agent skills · Quick start · How it works · Architecture · New Mac setup

Why

A new Mac means a day of remembering which apps, fonts, brew packages and editor
settings you had, and a shell that gets slower every time an installer appends a line to
.zshrc. This repo keeps all of it in one place: configs are symlinked into $HOME, so
editing a file here changes the live setup, and package lists are regenerated from the
machine instead of maintained by hand.

It is also where my agent skills live. The same skills/ folder is linked into Claude
Code, Cursor and ~/.agents, so every tool reads one copy.

It's for me first, and for developers who want to borrow a fast .zshrc or a skill. It
isn't a one-command bootstrap for someone else's machine: paths, apps and themes are mine,
and several steps are manual on purpose.

Design principles

Quick start

Prerequisites: macOS, git and make (from the Xcode Command Line Tools,
xcode-select --install). The Makefile expects the repo at ~/dotfiles.

The smallest useful piece is the agent skills, which need nothing else:

git clone https://github.com/glrodasz/dotfiles.git ~/dotfiles
cd ~/dotfiles
make help          # list every target
make slink-skills  # link skills/* into ~/.claude/skills, ~/.cursor/skills-cursor and ~/.agents/skills

Each linked skill replaces any existing skill with the same name in those folders. Open
Claude Code or Cursor and the skills show up as slash commands, e.g. /branch-test-plan.

To use the shell config too, install its dependencies (see New Mac setup)
and run make slink-zsh, which replaces ~/.zshrc and ~/.zprofile with links.

New Mac setup

Install fundamental apps

1. Install Chrome, 1Password, and Ghostty
2. Install Elgato Camera Hub, Elgato Control Center, Elgato Stream Deck, and Game Capture HD from here
3. Install Logitech Options+
4. Install Logitech G Hub
5. Install Purchased Apps from the App Store
6. Install Downloaded Apps listed in apps/installed-apps.json
7. Install Visual Studio Code and Cursor

Configure Git

(If not available) Install Git through the Xcode Command Line Tools: xcode-select --install

1. Add the SSH keys from 1Password to ~/.ssh and update permissions: chmod 400 id_{algorithm}
2. Add the SSH key to the agent: ssh-add -K ~/.ssh/id_{algorithm}
3. Set git name: git config --global user.name "Guillermo Rodas"
4. Set git email: git config --global user.email "<email>@gmail.com"
5. Clone dotfiles: git clone [email protected]:glrodasz/dotfiles.git ~/dotfiles

Configure Brew

1. Install brew: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
2. Run the commands it prints to make brew available in the path
3. Install brew packages: make install-brew (includes starship, z and zsh-syntax-highlighting, which .zshrc loads)

Configure Zsh

Linux: install sudo apt install zsh and make it the default shell: chsh -s $(which zsh)

1. Install Oh My Zsh: sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"
2. Clone zsh-defer into a hidden folder: git clone https://github.com/romkatv/zsh-defer.git ~/.zsh-defer
3. Link the zsh config: make slink-zsh

Configure the development environment

1. Install nvm following these instructions
2. Install Active LTS nvm install --lts and Current nvm install node
3. Install npm packages: make install-npm (with both the nvm LTS version and the OS Node version)

Install fonts

1. Install Hack Nerd Font and JetBrainsMono Nerd Font from https://www.nerdfonts.com/font-downloads

Configure terminals and Vim

1. Set up the terminals from terminal/: Ghostty, iTerm, Terminal.app and Warp
2. Clone vim-colors-solarized and link vim, following vim/README.md

Configure editors

1. Configure Visual Studio Code from editors/vscode
2. Configure Cursor from editors/cursor
3. Configure WebStorm from editors/webstorm

Configure extra options

1. Configure macOS options from mac/
2. Configure extra apps from the DO NOT FORGET to backup Apple Note
3. Link the agent skills: make slink-skills

Raspberry Pi OS

Follow Configure Git, Configure Zsh, Configure the development environment and
Configure terminals, then raspberry/README.md.

How it works

Everything runs through make. make help lists the targets from their ## comments.

Fast zsh startup

The shell is tuned around one fact: each process spawned at startup costs ~25ms here.

Architecture

Purple is this repo, blue is the AI coding tools that load the skills, and gray is people
and external systems.

The repo is plain files and a Makefile; nothing runs in the background. The only lasting
effect of make slink* is a set of symlinks, so git pull updates the live shell and
every agent tool at once, and deleting a link undoes it.

The scripts in scripts/ are the only part that talks to a remote service: they call the
GitHub API through gh to inventory repos or apply branch rulesets and security settings.

Tech stack · Shell: zsh, Oh My Zsh, zsh-defer, Starship · Automation: Make, Bash,
whiptail, gh + jq · Agents: Agent Skills (SKILL.md) for Claude Code, Cursor and
~/.agents · Packages: Homebrew, npm, nvm, pyenv

Usage

Agent skills

Private or machine-specific skills go in ~/.skills.local/<name>/SKILL.md; make slink-skills links them next to these. More in skills/README.md.

Shell aliases and functions

A few from zsh/.zshrc:

Scripts

• scripts/github-audit.sh inventories every repo of a
  GitHub user or org into scripts/github-audit/ (gitignored).
• scripts/harden-repos.sh applies a default-branch
  ruleset, squash-only merging, Dependabot and a read-only GITHUB_TOKEN, per visibility,
  with a --dry-run preview.
• raycast/scripts/ has three Raycast commands that open a URL or a
  Google search in a specific Chrome profile (work, private, public).

Project layout

dotfiles/
├── Makefile       # every install, link and backup target
├── zsh/           # .zshrc and .zprofile
├── skills/        # agent skills, one folder per skill
├── scripts/       # GitHub audit and hardening scripts
├── brew/          # brew/packages and its backup script
├── apps/          # installed-apps.json and its backup script
├── npm/           # global npm packages
├── terminal/      # Ghostty, iTerm, Terminal.app and Warp setup
├── editors/       # VS Code, Cursor and WebStorm setup
├── vim/           # .vimrc and solarized colors
├── raycast/       # Raycast script commands
├── mac/           # macOS settings
└── raspberry/     # Raspberry Pi OS setup

Documentation

Contributing

• Add a skill: create skills/<name>/SKILL.md with name and description
  frontmatter, check it with python3 skills/skills-audit/scripts/lint_skills.py, then run
  make slink-skills. Regenerate the catalog with the skills-social skill.
• Change the shell: follow AGENTS.md, then check the syntax with
  zsh -n zsh/.zshrc and the startup time with
  for i in $(seq 1 10); do /usr/bin/time zsh -i -c exit; done.
• Keep backups current: run make backup, follow the steps in each folder's README,
  and commit the changes.

License

MIT © 2026 Guillermo Rodas.

The Snazzy terminal color schemes are from Sindre Sorhus's Snazzy.
vim-colors-solarized by Ethan
Schoonover is cloned separately and keeps its own license.