diff --git a/docs/file-layout.md b/docs/file-layout.md
index 08516524..24c21af5 100644
--- a/docs/file-layout.md
+++ b/docs/file-layout.md
@@ -198,12 +198,7 @@ Runs once per user. It does **not** copy `~/.config/**`, `~/.bashrc`,
 `flags.lua`, or the nautilus extensions — `/etc/skel` already seeded those.
 It only does the things `/etc/skel` can't:
 
-- Skill symlinks `~/.{agents,claude,codex,pi/agent,hermes}/skills/<name>` (and each `~/.hermes/profiles/*/skills/<name>`) →
-  `$OMARCHY_PATH/default/agents/skills/<name>`, looping over every skill
-  directory there (currently `omarchy` and `diagnose-crash`) so new skills
-  need no edit. Symlinks (not copies) so `omarchy dev link` against a dev
-  checkout repoints them correctly. Hermes profile dirs are only linked when
-  they already exist — provision does not create Hermes profiles.
+- Skill symlinks into `~/.agents/skills/<name>`, `~/.claude/skills/<name>`, `~/.codex/skills/<name>`, `~/.pi/agent/skills/<name>`, `~/.gemini/config/skills/<name>` (Antigravity), `~/.hermes/skills/<name>`, and each existing `~/.hermes/profiles/*/skills/<name>` → `$OMARCHY_PATH/default/agents/skills/<name>`, looping over every skill directory there (currently `omarchy` and `diagnose-crash`) so new skills need no edit. Symlinks (not copies) so `omarchy dev link` against a dev checkout repoints them correctly. Hermes profile dirs are only linked when they already exist — provision does not create Hermes profiles.
 - `xdg-user-dirs-update` (Templates/Public/Desktop folded back into `$HOME`)
   and `~/.config/gtk-3.0/bookmarks` (needs `$HOME` expansion).
 - Hyprland's package-owned default input reads `XKBLAYOUT` / `XKBVARIANT`
diff --git a/test/shell.d/hermes-skills-migration-test.sh b/test/shell.d/hermes-skills-migration-test.sh
new file mode 100755
index 00000000..f1145bd7
--- /dev/null
+++ b/test/shell.d/hermes-skills-migration-test.sh
@@ -0,0 +1,75 @@
+#!/bin/bash
+
+set -euo pipefail
+
+source "$(dirname "$0")/base-test.sh"
+
+migration="$ROOT/migrations/1787843905.sh"
+[[ -f $migration ]] || fail "Hermes skills migration exists"
+
+test_dir=$(mktemp -d)
+trap 'rm -rf "$test_dir"' EXIT
+home="$test_dir/home"
+
+run_migration() {
+  HOME="$home" OMARCHY_PATH="$ROOT" bash -euo pipefail "$migration" >/dev/null ||
+    fail "migration exits clean"
+}
+
+assert_link() {
+  local link="$1"
+  local skill="$2"
+  local description="$3"
+
+  [[ -L $link && $(readlink "$link") == "$ROOT/default/agents/skills/$skill" ]] ||
+    fail "$description" "$link -> $(readlink "$link" 2>/dev/null || echo missing)"
+}
+
+# ------------------------------------------------------------------ default home, no profiles
+
+rm -rf "$home"
+mkdir -p "$home"
+run_migration
+
+for skill in omarchy diagnose-crash; do
+  assert_link "$home/.hermes/skills/$skill" "$skill" "migration links $skill into the default Hermes home"
+done
+[[ -e $home/.hermes/profiles ]] && fail "migration does not create Hermes profiles"
+pass "migration links the default Hermes home and does not create profiles"
+
+run_migration
+for skill in omarchy diagnose-crash; do
+  assert_link "$home/.hermes/skills/$skill" "$skill" "migration is idempotent on the default home for $skill"
+done
+pass "migration is idempotent on the default home"
+
+# ------------------------------------------------------------------ pre-existing profile
+
+rm -rf "$home"
+mkdir -p "$home/.hermes/profiles/james"
+run_migration
+
+for skill in omarchy diagnose-crash; do
+  assert_link "$home/.hermes/skills/$skill" "$skill" "migration links $skill into the default Hermes home when a profile exists"
+  assert_link "$home/.hermes/profiles/james/skills/$skill" "$skill" "migration links $skill into a pre-existing Hermes profile"
+done
+[[ -d $home/.hermes/profiles/james ]] || fail "migration leaves the pre-existing profile in place"
+profile_count=$(find "$home/.hermes/profiles" -mindepth 1 -maxdepth 1 -type d | wc -l)
+(( profile_count == 1 )) || fail "migration does not create extra profiles" "count=$profile_count"
+pass "migration links a pre-existing Hermes profile and does not create extras"
+
+run_migration
+for skill in omarchy diagnose-crash; do
+  assert_link "$home/.hermes/skills/$skill" "$skill" "migration is idempotent on the default home when a profile exists for $skill"
+  assert_link "$home/.hermes/profiles/james/skills/$skill" "$skill" "migration is idempotent on a pre-existing profile for $skill"
+done
+pass "migration is idempotent on a pre-existing profile"
+
+# ------------------------------------------------------------------ missing skill source
+
+rm -rf "$home"
+mkdir -p "$home" "$test_dir/empty-omarchy"
+HOME="$home" OMARCHY_PATH="$test_dir/empty-omarchy" bash -euo pipefail "$migration" >/dev/null ||
+  fail "migration exits clean when the skill source is missing"
+[[ -e $home/.hermes ]] && fail "migration no-ops when the skill source is missing"
+pass "migration no-ops when the skill source is missing"