skills.rest
r-senchuk
r-senchukCOMMUNITY
Explore all skills by this author →
GitHub

macos-homebrew-troubleshoot

Diagnose and fix macOS environment, Homebrew, PATH, and launchd service issues.

Updated Mar 29, 2026
Search Tags:#troubleshooting#macos#shell#homebrew#diagnose#path#launchd
One-click install
npx skills add https://github.com/r-senchuk/agentskills --skill macos-homebrew-troubleshoot-r-senchuk
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: macos-homebrew-troubleshoot
Source: https://github.com/r-senchuk/agentskills/tree/main/.agents/skills/macos-homebrew-troubleshoot
Command: npx skills add https://github.com/r-senchuk/agentskills --skill macos-homebrew-troubleshoot-r-senchuk

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? macOS developers frequently hit broken environments: commands not found after brew install, wrong binary versions picked up, quarantine-blocked apps, and failing launchd services. This Skill provides a structured diagnostic procedure to identify root causes and apply safe, verified fixes. ## Core Features & Use Cases - Systematic Diagnosis: Gathers system context (macOS version, shell, Homebrew prefix, PATH) before investigating symptoms. - Root Cause Mapping: Matches common symptoms like command not found, permission errors, and quarantine blocks to known causes and fixes. - Validated Fixes: Applies minimal-privilege fixes and verifies resolution persists across new shell sessions. - Use Case: After installing a tool with Homebrew, which still points to the system binary. The Skill inspects PATH ordering, checks brew link status, corrects the shell profile, and confirms the right version runs. ## Quick Start Ask the agent to diagnose why a Homebrew-installed command is not found on your Mac, providing the error output and your macOS version.

Frequently Asked Questions about macos-homebrew-troubleshoot

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix command not found after brew install?▼

The usual cause is Homebrew's bin directory missing from PATH. Add eval "$(brew shellenv)" to your shell profile (.zshrc or .zprofile), then source the file and verify with which and brew doctor.

Why does the wrong version of a tool run on macOS?▼

The system binary in /usr/bin often shadows the Homebrew-installed version because of PATH ordering. Check with which -a, then reorder PATH or run brew link --force to prioritize the Homebrew build.

How do I fix 'app is damaged and can't be opened' on macOS?▼

This error comes from the com.apple.quarantine attribute set by Gatekeeper. Inspect it with xattr -l on the file, then remove it with xattr -cr on the app path after confirming the source is trusted.

What is the difference between /opt/homebrew and /usr/local?▼

/opt/homebrew is the Homebrew prefix on Apple Silicon Macs, while /usr/local is used on Intel Macs or under Rosetta. Mixing prefixes causes binary conflicts, so keep ARM and Intel installations separate.

How do I debug a launchd service that won't start?▼

Validate the plist syntax with plutil -lint, confirm the referenced binary path exists, and check launchctl list for the service status. Use log show with a sender predicate to view recent service logs.

When should I not use this troubleshooting procedure?▼

It does not apply to writing new scripts from scratch, Linux or Windows issues, or general application debugging unrelated to the macOS environment. It targets environment, Homebrew, and system-level configuration problems only.

Related Skills

Explore More Software Engineering Skills→
eugenereugener
3

brew-optimize

Analyze Homebrew installations and generate cleanup commands for unused packages.

Community
Intermediate
knowledgexhuntaknowledgexhunta

YADM Utilities

Automate Claude Code dotfile management with YADM across multiple machines.

Community
Advanced
GelioGelio
10

update-neovim

Build and install Neovim from source using a local install.sh script.

Community
Intermediate
mozillamozilla

mozconfig

Generates Firefox mozconfig build configuration files for preset and custom setups.

Official
Advanced