diff --git a/.craft.yml b/.craft.yml
index 0b9618e15..6b927495d 100644
--- a/.craft.yml
+++ b/.craft.yml
@@ -75,10 +75,22 @@ workspaces:
 
             def install
               bin.install Dir["sentry-*"].first => "sentry"
+              # Homebrew-managed completion dirs survive the build sandbox and
+              # are cleaned up by `brew uninstall`. Writing into $HOME from
+              # post_install does not work: it runs under a throwaway HOME.
+              generate_completions_from_executable(bin/"sentry", "cli", "completion")
             end
 
-            def post_install
-              system bin/"sentry", "cli", "setup", "--method", "brew", "--no-modify-path"
+            def caveats
+              <<~EOS
+                Shell completions for bash, zsh, and fish are installed by Homebrew.
+
+                To install the Sentry CLI skill for detected AI coding agents, run:
+                  sentry cli setup --no-modify-path --no-completions
+
+                `sentry cli upgrade` refreshes the skill automatically. After a
+                `brew upgrade`, run the command above again.
+              EOS
             end
 
             test do
diff --git a/apps/cli-docs/src/content/docs/agentic-usage.md b/apps/cli-docs/src/content/docs/agentic-usage.md
index 452fbf792..2f6e6ff27 100644
--- a/apps/cli-docs/src/content/docs/agentic-usage.md
+++ b/apps/cli-docs/src/content/docs/agentic-usage.md
@@ -7,7 +7,7 @@ AI coding agents can use the Sentry CLI through the skill system. The CLI detect
 
 ## Automatic Installation
 
-The curl installer and Homebrew run `sentry cli setup`, which installs agent skills into detected agent root directories (`~/.claude`, `~/.agents`). After a package-manager install, run `sentry cli setup` yourself. `sentry cli upgrade` also refreshes skills. No network fetch is needed — skill files are embedded in the binary.
+The curl installer runs `sentry cli setup`, which installs agent skills into detected agent root directories (`~/.claude`, `~/.agents`). After a Homebrew or package-manager install, run `sentry cli setup` yourself. `sentry cli upgrade` also refreshes skills. No network fetch is needed — skill files are embedded in the binary.
 
 This uses the same `~/.agents` convention as [dotagents](https://github.com/getsentry/dotagents), Sentry's first-party tool for installing agent skills. See [Manual Installation](#manual-installation) to add the skill with dotagents yourself.
 
diff --git a/apps/cli-docs/src/content/docs/getting-started.mdx b/apps/cli-docs/src/content/docs/getting-started.mdx
index 75ee43927..ee2b01822 100644
--- a/apps/cli-docs/src/content/docs/getting-started.mdx
+++ b/apps/cli-docs/src/content/docs/getting-started.mdx
@@ -123,6 +123,12 @@ On Alpine and other musl-based Linux systems, install Node.js and use
 brew install getsentry/tools/sentry
 ```
 
+Homebrew installs shell completions but can't install agent skills into your home directory. Run `sentry cli setup` once to add them, and again after `brew upgrade`:
+
+```bash
+sentry cli setup --no-modify-path --no-completions
+```
+
 ## Package Managers
 
 Install globally with your preferred package manager (the npm packages require **Node.js 20+**; on **22.15+** the built-in `node:sqlite` is used, on 20–22.14 a bundled WASM fallback is used transparently):
@@ -134,7 +140,7 @@ Install globally with your preferred package manager (the npm packages require *
   bun="bun add -g sentry"
 />
 
-Unlike the install script and Homebrew, package manager installs don't set up shell completions or agent skills. Run `sentry cli setup` once to enable them:
+Unlike the install script, package manager installs don't set up shell completions or agent skills. Run `sentry cli setup` once to enable them:
 
 ```bash
 sentry cli setup
diff --git a/packages/cli/plugins/README.md b/packages/cli/plugins/README.md
index ff0afb95c..f7848b78f 100644
--- a/packages/cli/plugins/README.md
+++ b/packages/cli/plugins/README.md
@@ -6,9 +6,10 @@ Agent skills for using the Sentry CLI, following the [Agent Skills](https://gith
 
 ### Automatic (recommended)
 
-When you install the CLI via the install script, Homebrew, or a package manager,
-`sentry cli setup` automatically installs skills into detected agent directories
-(`~/.claude`, `~/.agents`). Skills are also refreshed on `sentry cli upgrade`.
+When you install the CLI via the install script, `sentry cli setup` automatically
+installs skills into detected agent directories (`~/.claude`, `~/.agents`). After
+a Homebrew or package-manager install, run `sentry cli setup` yourself. Skills are
+also refreshed on `sentry cli upgrade`.
 
 ### dotagents