diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 4eaee42..b8dab21 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -27,8 +27,9 @@ jobs:
           cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/"
           cp start.sh "$stage/agentvfs-quickstart"
           chmod +x "$stage/agentvfs-quickstart"
+          cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md"
           tar -C "$stage" -czf "agentvfs-${version}-linux-x86_64.tar.gz" \
-              agentvfs agentvfs-ctl agentvfs-quickstart LICENSE
+              agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE
       - uses: actions/upload-artifact@v4
         with:
           name: linux-x86_64
@@ -52,8 +53,9 @@ jobs:
           cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/"
           cp start.sh "$stage/agentvfs-quickstart"
           chmod +x "$stage/agentvfs-quickstart"
+          cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md"
           tar -C "$stage" -czf "agentvfs-${version}-darwin-arm64.tar.gz" \
-              agentvfs agentvfs-ctl agentvfs-quickstart LICENSE
+              agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE
       - uses: actions/upload-artifact@v4
         with:
           name: darwin-arm64
@@ -77,8 +79,9 @@ jobs:
           cp build/agentvfs build/agentvfs-ctl LICENSE "$stage/"
           cp start.sh "$stage/agentvfs-quickstart"
           chmod +x "$stage/agentvfs-quickstart"
+          cp docs/skills/agentvfs-workspace.md "$stage/agentvfs-workspace.md"
           tar -C "$stage" -czf "agentvfs-${version}-darwin-x86_64.tar.gz" \
-              agentvfs agentvfs-ctl agentvfs-quickstart LICENSE
+              agentvfs agentvfs-ctl agentvfs-quickstart agentvfs-workspace.md LICENSE
       - uses: actions/upload-artifact@v4
         with:
           name: darwin-x86_64
diff --git a/install.sh b/install.sh
index 58319fb..637ea18 100755
--- a/install.sh
+++ b/install.sh
@@ -107,8 +107,20 @@ mkdir -p "$PREFIX"
 for f in agentvfs agentvfs-ctl agentvfs-quickstart; do
     [ -f "$WORK/$f" ] && install -m 0755 "$WORK/$f" "$PREFIX/$f"
 done
+# agentvfs-quickstart reads this file at runtime to write
+# ~/.claude/skills/agentvfs-workspace/SKILL.md and ~/.codex/AGENTS.md.
+[ -f "$WORK/agentvfs-workspace.md" ] && \
+    install -m 0644 "$WORK/agentvfs-workspace.md" "$PREFIX/agentvfs-workspace.md"
 
 # Final message.
+# Suggest the rc file for the most common login shell on this OS so the
+# user knows where to persist the PATH addition.
+if [ "$os" = darwin ]; then
+    default_rc="~/.zshrc"; alt_rc="~/.bashrc"
+else
+    default_rc="~/.bashrc"; alt_rc="~/.zshrc"
+fi
+
 echo
 echo "Installed agentvfs $VERSION to $PREFIX"
 echo
@@ -117,10 +129,15 @@ case ":$PATH:" in
         echo "next: agentvfs-quickstart /path/to/project"
         ;;
     *)
-        echo "Note: $PREFIX is not in your PATH. Add it:"
+        echo "Note: $PREFIX is not in your PATH."
+        echo
+        echo "  # 1) Activate in the current shell (run this NOW):"
         echo "  export PATH=\"$PREFIX:\$PATH\""
-        echo "  echo 'export PATH=\"$PREFIX:\$PATH\"' >> ~/.bashrc   # or ~/.zshrc"
         echo
-        echo "Then: agentvfs-quickstart /path/to/project"
+        echo "  # 2) Persist for future shells (run this ONCE):"
+        echo "  echo 'export PATH=\"$PREFIX:\$PATH\"' >> $default_rc"
+        echo "  # (use $alt_rc if that's your login shell)"
+        echo
+        echo "Then run: agentvfs-quickstart /path/to/project"
         ;;
 esac
diff --git a/start.sh b/start.sh
index 8d53592..d438648 100755
--- a/start.sh
+++ b/start.sh
@@ -85,10 +85,27 @@ if ! command -v agentvfs >/dev/null 2>&1; then
 fi
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-SKILL_SRC="$SCRIPT_DIR/docs/skills/agentvfs-workspace.md"
+# In a repo checkout the skill source lives under docs/skills/. In a
+# packaged install (release.yml + install.sh) it's bundled flat next to
+# the renamed agentvfs-quickstart script.
+SKILL_SRC=""
+for candidate in \
+    "$SCRIPT_DIR/docs/skills/agentvfs-workspace.md" \
+    "$SCRIPT_DIR/agentvfs-workspace.md"; do
+    if [[ -f "$candidate" ]]; then
+        SKILL_SRC="$candidate"
+        break
+    fi
+done
 
-if [[ ! -f "$SKILL_SRC" ]]; then
-    echo "start.sh: skill source not found at $SKILL_SRC — run start.sh from the agentvfs repo checkout" >&2
+if [[ -z "$SKILL_SRC" ]]; then
+    echo "start.sh: skill source not found." >&2
+    echo "  searched: $SCRIPT_DIR/docs/skills/agentvfs-workspace.md" >&2
+    echo "            $SCRIPT_DIR/agentvfs-workspace.md" >&2
+    echo "  If you installed via install.sh, this is a packaging bug — please" >&2
+    echo "  report at https://github.com/thustorage/ContextFS/issues." >&2
+    echo "  If you're running from a repo checkout, make sure" >&2
+    echo "  docs/skills/agentvfs-workspace.md exists." >&2
     exit 1
 fi