diff --git a/.changeset/docs-drive-shared-drives-tip.md b/.changeset/docs-drive-shared-drives-tip.md
new file mode 100644
index 00000000..b8e9ed7c
--- /dev/null
+++ b/.changeset/docs-drive-shared-drives-tip.md
@@ -0,0 +1,11 @@
+---
+"@googleworkspace/cli": patch
+---
+
+docs(drive): add shared drives tip to SKILL.md
+
+Files in shared drives are invisible to `files list` and `files get`
+by default. Adds a "Shared Drives" section explaining that agents
+should retry with `supportsAllDrives: true` and
+`includeItemsFromAllDrives: true` when a file search returns no
+results and the user indicates the file is in a shared drive.
diff --git a/skills/gws-drive/SKILL.md b/skills/gws-drive/SKILL.md
index d4debbdb..588f7b8c 100644
--- a/skills/gws-drive/SKILL.md
+++ b/skills/gws-drive/SKILL.md
@@ -25,6 +25,20 @@ gws drive <resource> <method> [flags]
 |---------|-------------|
 | [`+upload`](../gws-drive-upload/SKILL.md) | Upload a file with automatic metadata |
 
+## Shared Drives
+
+Files stored in a shared drive are not returned by default. If a file search returns no results, add `"supportsAllDrives": true` to your `--params`:
+
+```bash
+# List files across all drives (including shared drives)
+gws drive files list --params '{"q":"name = '\''report.pdf'\''","supportsAllDrives":true,"includeItemsFromAllDrives":true}'
+
+# Get a file that lives in a shared drive
+gws drive files get --params '{"fileId":"FILE_ID","supportsAllDrives":true}'
+```
+
+> **Tip:** If you can't find a file and the user mentions it's in a shared drive, retry the request with `"supportsAllDrives": true` (and `"includeItemsFromAllDrives": true` for list/search requests only — this parameter is not valid for `files.get`).
+
 ## API Resources
 
 ### about