用途：在 macOS 上正确安装 Homebrew（前缀正确、为后续所有 shell 接好 PATH）、验证安装，并建立让机器可复现的 Brewfile 工作流。该技能负责 ~/.zprofile 中的 brew 行与 Brewfile 重新生成流程，其他技能只安装包，不改写这些内容。
不适用场景：选择安装哪些 CLI 工具、GUI 应用、日常 brew update/upgrade/cleanup、缺少 Xcode CLT、本地数据库服务等，分别由其他技能处理。
前置条件：xcode-select -p 必须能解析，否则先运行 macos-system-prep；不要让 Homebrew 安装器与 CLT 图形安装器同时运行。
安全约束：安装脚本会要求管理员密码并打印将执行的操作，不要抑制输出；向 ~/.zprofile 追加时用 grep 守卫保证幂等；brew bundle dump 拒绝覆盖已有文件，--force 会覆盖，brew bundle cleanup --force 会卸载未列出的所有内容，更新应走临时候选文件 + diff + 用户确认；brew analytics off 应作为选项呈现，不要静默决定。
工作流：1) 检测 command -v brew && brew --prefix && brew --version，已安装则跳到验证；Apple Silicon 前缀为 /opt/homebrew，Intel 为 /usr/local，arm64 机器上的 /usr/local 安装属 Rosetta 时代遗留，应标记而非叠加安装。2) 安装：/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"，然后为未来登录 shell 接好 PATH，先检查已有 shellenv 行，arm64 上过期的 /usr/local 行需先备份再替换，无则用 grep 守卫追加 eval "$(${BREW_BIN} shellenv)" 到 ~/.zprofile。3) 验证：brew --version、brew --prefix（与架构匹配）、brew doctor（警告仅供参考，错误不是），在新终端确认 brew 可用，可选 brew analytics off。4) Brewfile 工作流：brew bundle 内置于 brew；用 brew bundle dump --describe --file=/tmp/Brewfile.candidate 生成候选，diff 后经用户批准再替换 ~/Brewfile；用 brew bundle install --file=~/Brewfile 恢复/收敛，brew bundle check 只检查，brew bundle cleanup 列出未在文件中的项。省略 --file 时默认 ./Brewfile，--global 时为 ~/.Brewfile。条目支持 brew、cask、tap、mas "App", id: N（需 brew install mas 并登录 App Store）、vscode "publisher.extension"。建议把 Brewfile 放入 dotfiles 仓库。5) 运行检查脚本 sh "${CLAUDE_SKILL_DIR}/scripts/check.sh"。
完成标准：新 shell 中 brew doctor 通过，~/.zprofile 中 shellenv 行恰好一条，如需要则 Brewfile 存在且 brew bundle check 通过。
注意事项：brew install docker 只装 CLI 公式（无引擎），Docker Desktop cask 为 docker-desktop；mas 无法自行登录 App Store，需用户先在 App Store 应用登录一次；从 Intel 迁移的 Mac 常同时存在 /usr/local 与 /opt/homebrew 的 brew，每种架构只保留一个；Homebrew 要求 macOS Sonoma 14+，2026 年末起对 Intel 仅尽力支持。当前版本、支持层级、cask 改名等易变细节见 references/homebrew-facts.md。