diff --git a/bin/use-skills.sh b/bin/use-skills.sh
index 00265b4..4217af8 100755
--- a/bin/use-skills.sh
+++ b/bin/use-skills.sh
@@ -1,4 +1,17 @@
 #!/usr/bin/env bash
+# DEPRECATED: Per-repo skill loading is no longer recommended.
+#
+# Skills are now deployed globally via Home Manager (dotfiles/home/claude.nix).
+# This eliminates the 1-2 second delay on every `cd` caused by nix build calls.
+#
+# If you have a .skills file or source this script in .envrc, you can safely
+# remove those lines. All skills are available globally at ~/.claude/skills/,
+# ~/.codex/skills/, etc.
+#
+# This script remains for backward compatibility but will be removed in a
+# future update. See: https://github.com/dan/skills/issues/y7h4
+#
+# --- LEGACY DOCUMENTATION ---
 # Helper for per-repo skill deployment via direnv
 # Source this from your .envrc or copy the functions
 #