rr-system
System setup, tool information, and AI configuration management for development environments. Use when setting up new machines, explaining available tools (shell-config, ai-rules, wt), managing AI assistant configurations (Claude/Codex/Gemini/OpenCode), checking system configuration, or troubleshooting environment issues. Also triggers when working with configuration files (.json, .toml, .fish, .zsh, .bash), Brewfiles, or installation scripts. Example triggers: "Set up my development environment", "Install tools on new machine", "Configure AI assistant", "What tools do I have?", "Update my shell config", "Add MCP server to Claude", "Check system configuration"
When & Why to Use This Skill
The rr-system skill is a comprehensive automation suite designed for development environment setup and AI configuration management. It streamlines the installation of essential CLI tools, shell configurations (Fish, Zsh, Bash), and AI assistant settings across platforms like Claude, Gemini, and Codex. By leveraging idempotent scripts and automated verification, it ensures a consistent, high-performance workspace on macOS and Linux, significantly reducing manual configuration time.
Use Cases
- 1. Automated Machine Onboarding: Rapidly set up new macOS or Linux environments by installing Homebrew, CLI utilities, and development packages via pre-configured Brewfiles.
- 2. AI Assistant Synchronization: Maintain feature parity across multiple AI platforms by automatically updating MCP servers and environment variables in Claude, Codex, Gemini, and OpenCode settings.
- 3. Shell Environment Optimization: Deploy modular shell configurations and modern CLI alternatives (like eza, bat, and starship) to enhance terminal productivity and navigation.
- 4. Environment Troubleshooting & Validation: Use automated scripts to verify tool installations, validate JSON/TOML configuration syntax, and resolve common PATH or permission issues.
| name | rr-system |
|---|---|
| description | System setup, tool information, and AI configuration management for development environments. Use when setting up new machines, explaining available tools (shell-config, ai-rules, wt), managing AI assistant configurations (Claude/Codex/Gemini/OpenCode), checking system configuration, or troubleshooting environment issues. Also triggers when working with configuration files (.json, .toml, .fish, .zsh, .bash), Brewfiles, or installation scripts. Example triggers: "Set up my development environment", "Install tools on new machine", "Configure AI assistant", "What tools do I have?", "Update my shell config", "Add MCP server to Claude", "Check system configuration" |
System Setup & Configuration
Comprehensive system setup automation and tool reference for the rr- development environment. Provides automated installation scripts, AI configuration management, and modern CLI tools for macOS and Linux.
⚠️ IMPORTANT: ALWAYS CHECK OFFICIAL DOCUMENTATION ONLINE
Tools evolve rapidly. Before providing commands or configuration changes:
- Load
references/tools-reference.mdfor official documentation URLs - Search online for latest official documentation
- Verify CLI options and flags are current
- Use official docs as source of truth - this skill may be outdated
When to Use This Skill
- Setting up new macOS or Linux machines
- Explaining available tools (shell commands, aliases, modern CLI tools)
- Managing AI assistant configurations (Claude Code, Codex, Gemini, OpenCode)
- Editing, validating, or updating AI configuration files
- Adding/removing MCP servers across AI platforms
- Checking if tool or configuration exists
- Troubleshooting environment issues
- Updating existing installations
Progress Reporting Requirements
CRITICAL: Provide continuous progress updates for all installation tasks.
Before ANY task:
- Use TodoWrite tool to create task list
- Explain what you're about to do
- Show exact command you'll run
During execution:
- Report real-time progress
- Show relevant output
- Explain warnings/errors immediately
After each step:
- Mark task as completed
- Summarize accomplishments
- Note issues or next steps
Never run commands silently - always inform user what and why.
Quick Installation
Complete 4-step setup on macOS or Linux:
cd .claude/skills/rr-system
# 1. Install tools (includes Homebrew)
bash scripts/install-tools.sh
# 2. Upgrade all packages (MANDATORY)
brew upgrade
# 3. Install shell configs
bash scripts/install-shell-config.sh
# 4. Install AI configs
bash scripts/install-ai-configs.sh
# 5. Restart terminal
For detailed instructions, see references/installation-guide.md
Core Capabilities
1. System Installation
4 automated scripts for zero-interaction setup:
install-tools.sh - Development tools via Homebrew
- Installs Homebrew (macOS & Linux)
- CLI tools from
Brewfile(cross-platform) - macOS apps from
Brewfile.macos(auto-skipped on Linux) - Verifies critical tools installed
brew upgrade - MANDATORY after installing Homebrew
- Upgrades all packages to latest versions
- Ensures security patches and features
- Must run before other installation scripts
install-shell-config.sh - Shell configurations
- Fish/Zsh/Bash configs with modular conf.d structure
- Starship prompt + Ghostty terminal (macOS)
- wt function (Fish only - git worktree manager)
- Registers shells in /etc/shells (requires sudo)
- Fixes Zsh permissions (requires sudo)
- Enables Touch ID for sudo (macOS, requires sudo)
install-ai-configs.sh - AI assistant configurations
- Claude Code, Codex, Gemini, OpenCode configs
- Validates JSON/TOML syntax
- Creates directories, overwrites existing configs
All scripts are idempotent (safe to run multiple times) with automatic verification.
2. Brewfile Structure
Two Brewfiles for organized package management:
Brewfile - Shared CLI tools (macOS & Linux):
- Shells (Fish, Zsh, Bash)
- Modern CLI (bat, eza, fd, ripgrep, fzf, jq, yq, btop)
- Development (git, neovim, node, go, python, mkcert)
- Cloud (AWS, Azure, GCloud, kubectl, helm, k9s)
- Terminal (tmux, zellij, lazygit, lazydocker)
- AI CLIs (gemini-cli, opencode)
Brewfile.macos - macOS-only applications:
- Password & Security (1Password, 1Password CLI)
- Communication (Slack, Zoom, Linear)
- Development (Cursor, Ghostty, Tower)
- AI Assistants (Claude, ChatGPT, Codex, Claude Code)
- Productivity (Raycast, Granola, Shottr)
Adding tools:
- Edit
Brewfilefor CLI:brew "tool-name" - Edit
Brewfile.macosfor macOS apps:cask "app-name" - Run:
bash scripts/install-tools.sh
3. AI Configuration Management
Manage AI assistant configs with automated installation or manual editing.
Supported platforms:
- Claude Code (
~/.claude/settings.json) - Codex CLI (
~/.codex/config.toml) - Gemini CLI (
~/.gemini/settings.json) - OpenCode (
~/.config/opencode/opencode.json) - Cursor (
~/.cursor/mcp.json)
Quick install (recommended):
bash scripts/install-ai-configs.sh
Manual editing workflow:
- Read current config file
- Reference
assets/ai-configs/<platform>-*templates - Make changes with Edit tool
- Validate syntax:
- JSON:
jq empty <file> - TOML:
python3 -c "import tomllib; tomllib.load(open('<file>', 'rb'))"
- JSON:
- Restart AI assistant
Common tasks:
- Add MCP server: Modify mcpServers section, validate, restart
- Update environment variables: Edit env section, validate, restart
- Modify hooks (Claude): Edit hooks array, validate, restart
Feature Parity Principle:
Maintain near-identical configs across all platforms:
- Keep same MCP servers on all platforms
- Adapt only syntax for each platform's format
- When adding/removing MCP servers, update ALL platforms
- Only deviate when feature unavailable or platform requires different approach
For detailed schemas and patterns, see references/ai-config-schemas.md
4. Tool Reference
⚠️ Load references/tools-reference.md for complete documentation links
Modern CLI tools installed:
- File operations: bat, eza, fd, ripgrep
- Development: neovim, lazygit, lazydocker, fzf, ast-grep
- Linting: actionlint, shellcheck
- Navigation: zoxide, atuin, direnv
- Version managers: fnm (Node.js), uv (Python)
- System: procs, hexyl, broot, git-delta, difftastic
- Cloud: kubectl, helm, gh, aws-cli, azure-cli, gcloud
- Blockchain: foundry (forge, cast, anvil, chisel)
- Terminal: tmux, zellij
- AI CLIs: Claude Code, OpenCode, Codex, Gemini CLI
- Package managers: Homebrew, Bun
Configuration locations:
- Fish:
~/.config/fish/(config.fish + conf.d/) - Zsh:
~/.zshrc+~/.config/zsh/conf.d/ - Bash:
~/.bashrc,~/.bash_profile+~/.config/bash/conf.d/ - Neovim:
~/.config/nvim/(LazyVim with Catppuccin) - Starship:
~/.config/starship.toml - Claude:
~/.claude/ - Codex:
~/.codex/ - Gemini:
~/.gemini/ - Cursor:
~/.cursor/
Git Worktree Manager (wt):
- Installation: Included in Fish config (via
install-shell-config.sh) - Location:
~/.config/fish/functions/wt.fish - Availability: Fish shell only (use
fish -c "wt <cmd>"from bash/zsh) - Commands: new, switch, list, remove, clean, status
- Auto package manager detection
- Storage:
~/.wt/<repo-name>/
Key aliases:
ls→eza,cat→bat,grep→rg- File finder:
fd - Navigation:
z dirname,zi(zoxide) - Git: 60+ abbreviations (
g,ga,gc,gp,gl,gs, etc.) - Tools:
lzg(lazygit),lzd(lazydocker),ff(fzf preview)
Essential Workflows
Setting Up New Machine
cd .claude/skills/rr-system
# 1. Install development tools (includes Homebrew)
bash scripts/install-tools.sh
# 2. Upgrade all packages (MANDATORY)
brew upgrade
# 3. Install shell configs
bash scripts/install-shell-config.sh
# 4. Install AI configs
bash scripts/install-ai-configs.sh
# 5. Restart terminal, then:
fish # Start Fish shell
chsh -s $(which fish) # Optional: make Fish default
Verify:
bat --version
fish --version
ls ~/.config/fish/config.fish
ls ~/.claude/settings.json
fish -c "wt help"
Updating Existing Installation
# ALWAYS upgrade Homebrew first (MANDATORY)
brew upgrade
# Then update components
bash scripts/install-tools.sh
bash scripts/install-shell-config.sh
bash scripts/install-ai-configs.sh
# Restart terminal
Adding MCP Server to All Platforms
To maintain feature parity:
- Load
references/ai-config-schemas.mdfor formats - For each platform (Claude, Codex, Gemini, OpenCode):
- Read current config
- Add server definition (adapt syntax for platform)
- Validate: JSON (
jq empty), TOML (python3 tomllib)
- Verify all 4 configs have server
- Restart each AI assistant
- Test server on each platform
Checking System Status
Verify tool installation:
command -v <tool> # Check if exists
which <tool> # Show location
<tool> --version # Check version
For wt (Fish function):
ls ~/.config/fish/functions/wt.fish # Check file exists
fish -c "wt help" # Test from any shell
Check configurations:
# Shell configs
ls ~/.config/fish/conf.d/
ls ~/.config/zsh/conf.d/
# AI configs
ls ~/.claude/settings.json
ls ~/.codex/config.toml
Troubleshooting
Homebrew
Not in PATH (macOS):
# Apple Silicon
eval "$(/opt/homebrew/bin/brew shellenv)"
# Intel
eval "$(/usr/local/bin/brew shellenv)"
Shell
Shell not found:
sudo sh -c "echo $(which fish) >> /etc/shells"
sudo sh -c "echo $(which zsh) >> /etc/shells"
Config not loading:
source ~/.config/fish/config.fish # Fish
source ~/.zshrc # Zsh
source ~/.bashrc # Bash
Tools
Tool not working:
command -v <tool> # Check exists
brew list | grep <tool> # Check installed
brew reinstall <tool> # Reinstall
source ~/.config/fish/config.fish # Reload config
wt
Command not found:
ls ~/.config/fish/functions/wt.fish # Check file
fish -c "wt help" # Test from any shell
fish # Or switch to Fish
wt help
Note: wt is Fish-only. Use fish -c "wt <cmd>" from bash/zsh.
AI Configs
Syntax error:
# Validate JSON
jq empty ~/.claude/settings.json
# Validate TOML
python3 -c "import tomllib; tomllib.load(open('~/.codex/config.toml', 'rb'))"
Common errors:
- Trailing commas (JSON)
- Missing quotes around keys
- Mismatched brackets/braces
- Unescaped special characters
Config missing:
bash scripts/install-ai-configs.sh # Reinstall
For detailed troubleshooting, see references/installation-guide.md
Best Practices
Installation
- Run scripts in order: tools → brew upgrade → shell → AI
- Always
brew upgradeafter installing Homebrew - Restart terminal after installation
Shell Selection
- Fish (recommended): Best autosuggestions, modular structure, wt integration
- Zsh: Good plugin ecosystem, bash-compatible
- Bash: Universal compatibility, enhanced features
Tool Usage
- Use modern alternatives:
bat(cat),eza(ls),rg(grep),fd(find) - Use
zinstead ofcdfor frequent directories - Use
wtfor git worktrees (Fish only)
Resources
⚠️ ALWAYS START WITH OFFICIAL DOCUMENTATION
Before using skill resources:
- Load
references/tools-reference.mdfor official doc URLs - Search online for current documentation
- Verify commands with official sources
- Use skill as baseline only - official docs are source of truth
references/
installation-guide.md- Complete installation instructions, troubleshooting, verificationtools-reference.md- Official documentation URLs, quick reference (verify online first)ai-config-schemas.md- Config schemas, MCP patterns, validation, merge strategies
scripts/
install-tools.sh- Install development tools via Homebrewinstall-shell-config.sh- Install shell configurationsinstall-ai-configs.sh- Install AI assistant configurations
All scripts are idempotent with verification.
assets/
Brewfile- CLI tools package list (cross-platform)Brewfile.macos- macOS-only applicationsai-configs/- AI configuration templatesshell-config/- Shell configuration files
Common Scenarios
"What tools do I have?"
- Load
references/tools-reference.mdfor organized list by category
"How do I install on new machine?"
- Run 4 scripts in order (see Quick Installation)
- Restart terminal, verify with
bat --version,fish,wt help
"How do I update everything?"
- Run
brew upgrade(MANDATORY first step) - Run all install scripts
- Restart terminal
"Where is X configured?"
- Shell:
~/.config/<shell>/ - AI:
~/.claude/,~/.codex/,~/.gemini/ - Neovim:
~/.config/nvim/ - Starship:
~/.config/starship.toml
"Tool not working after install?"
- Check PATH:
command -v <tool> - Reload config:
source ~/.config/fish/config.fish - Reinstall:
brew reinstall <tool> - For wt: Check
~/.config/fish/functions/wt.fish, usefish -c "wt help"