diff --git a/.changeset/fix-skill-install-docs.md b/.changeset/fix-skill-install-docs.md
new file mode 100644
index 00000000..b4c8937d
--- /dev/null
+++ b/.changeset/fix-skill-install-docs.md
@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Document gws-shared as a required prerequisite for selective skill installation
diff --git a/README.md b/README.md
index 04c532d0..b0aaa7b5 100644
--- a/README.md
+++ b/README.md
@@ -224,6 +224,10 @@ The repo ships 100+ Agent Skills (`SKILL.md` files) — one for every supported
 npx skills add https://github.com/googleworkspace/cli
 
 # Or pick only what you need
+# gws-shared is required by all service skills — install it first
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
+
+# Then install the specific service skills you need
 npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-drive
 npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
 ```