googleworkspace · Bortlesboat · Apr 7, 2026
diff --git a/.changeset/fix-selective-skill-install.md b/.changeset/fix-selective-skill-install.md
@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Clarify selective skill installation by requiring `gws-shared` alongside service skills and by keeping `gws generate-skills` as the local generation path.
diff --git a/README.md b/README.md
@@ -224,10 +224,13 @@ 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
+npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-shared
 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
 ```
 
+When you selectively install skills, always install `gws-shared` first so the service skills can rely on the shared auth, flag, and safety guidance.
+
 <details>
 <summary>OpenClaw setup</summary>
 
@@ -236,7 +239,7 @@ npx skills add https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail
 ln -s $(pwd)/skills/gws-* ~/.openclaw/skills/
 
 # Or copy specific skills
-cp -r skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
+cp -r skills/gws-shared skills/gws-drive skills/gws-gmail ~/.openclaw/skills/
 ```
 
 The `gws-shared` skill includes an `install` block so OpenClaw auto-installs the CLI via `npm` if `gws` isn't on PATH.

diff --git a/crates/google-workspace-cli/src/generate_skills.rs b/crates/google-workspace-cli/src/generate_skills.rs
@@ -404,7 +404,7 @@ metadata:
     out.push_str(&format!("# {alias} ({api_version})\n\n"));
 
     out.push_str(
-        "> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.\n\n",
+        "> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.\n\n",
     );
 
     out.push_str(&format!(
@@ -541,7 +541,7 @@ metadata:
     out.push_str(&format!("# {alias} {cmd_name}\n\n"));
 
     out.push_str(
-        "> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.\n\n",
+        "> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.\n\n",
     );
 
     out.push_str(&format!("{about}\n\n"));
@@ -1400,4 +1400,70 @@ mod tests {
             "frontmatter should contain '- gws' block entry"
         );
     }
+
+    #[test]
+    fn test_service_skill_prerequisite_mentions_selective_install_and_local_generation() {
+        let entry = services::SERVICES
+            .iter()
+            .find(|s| s.api_name == "drive")
+            .unwrap();
+        let doc = crate::discovery::RestDescription {
+            name: entry.api_name.to_string(),
+            title: Some("Google Drive API".to_string()),
+            description: Some(entry.description.to_string()),
+            ..Default::default()
+        };
+        let cli = crate::commands::build_cli(&doc);
+        let helpers: Vec<&Command> = cli
+            .get_subcommands()
+            .filter(|s| s.get_name().starts_with('+'))
+            .collect();
+        let resources: Vec<&Command> = cli
+            .get_subcommands()
+            .filter(|s| !s.get_name().starts_with('+'))
+            .collect();
+
+        let md = render_service_skill(
+            entry.aliases[0],
+            entry,
+            &helpers,
+            &resources,
+            "Google Drive",
+            &doc,
+        );
+
+        assert!(md.contains("install `gws-shared` alongside this skill"));
+        assert!(md.contains("If you're generating skills from a local checkout, run `gws generate-skills`"));
+    }
+
+    #[test]
+    fn test_helper_skill_prerequisite_mentions_selective_install_and_local_generation() {
+        let entry = services::SERVICES
+            .iter()
+            .find(|s| s.api_name == "drive")
+            .unwrap();
+
+        let doc = crate::discovery::RestDescription {
+            name: entry.api_name.to_string(),
+            title: Some("Google Drive API".to_string()),
+            description: Some(entry.description.to_string()),
+            ..Default::default()
+        };
+        let cli = crate::commands::build_cli(&doc);
+        let helper = cli
+            .get_subcommands()
+            .find(|s| s.get_name().starts_with('+'))
+            .expect("No helper command found for test");
+
+        let md = render_helper_skill(
+            entry.aliases[0],
+            helper.get_name(),
+            helper,
+            entry,
+            "Google Drive",
+        );
+
+        assert!(md.contains("install `gws-shared` alongside this skill"));
+        assert!(md.contains("If you're generating skills from a local checkout, run `gws generate-skills`"));
+    }
 }
diff --git a/skills/gws-admin-reports/SKILL.md b/skills/gws-admin-reports/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # admin-reports (reports_v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws admin-reports <resource> <method> [flags]

diff --git a/skills/gws-calendar-agenda/SKILL.md b/skills/gws-calendar-agenda/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # calendar +agenda
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Show upcoming events across all calendars
 

diff --git a/skills/gws-calendar-insert/SKILL.md b/skills/gws-calendar-insert/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # calendar +insert
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 create a new event
 

diff --git a/skills/gws-calendar/SKILL.md b/skills/gws-calendar/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # calendar (v3)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws calendar <resource> <method> [flags]

diff --git a/skills/gws-chat-send/SKILL.md b/skills/gws-chat-send/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # chat +send
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Send a message to a space
 

diff --git a/skills/gws-chat/SKILL.md b/skills/gws-chat/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # chat (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws chat <resource> <method> [flags]

diff --git a/skills/gws-classroom/SKILL.md b/skills/gws-classroom/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # classroom (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws classroom <resource> <method> [flags]

diff --git a/skills/gws-docs-write/SKILL.md b/skills/gws-docs-write/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # docs +write
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Append text to a document
 

diff --git a/skills/gws-docs/SKILL.md b/skills/gws-docs/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # docs (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws docs <resource> <method> [flags]

diff --git a/skills/gws-drive-upload/SKILL.md b/skills/gws-drive-upload/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # drive +upload
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Upload a file with automatic metadata
 

diff --git a/skills/gws-drive/SKILL.md b/skills/gws-drive/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # drive (v3)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws drive <resource> <method> [flags]

diff --git a/skills/gws-events-renew/SKILL.md b/skills/gws-events-renew/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # events +renew
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Renew/reactivate Workspace Events subscriptions
 

diff --git a/skills/gws-events-subscribe/SKILL.md b/skills/gws-events-subscribe/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # events +subscribe
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Subscribe to Workspace events and stream them as NDJSON
 

diff --git a/skills/gws-events/SKILL.md b/skills/gws-events/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # events (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws events <resource> <method> [flags]
@@ -38,11 +38,11 @@ gws events <resource> <method> [flags]
 
 ### subscriptions
 
-  - `create` — Creates a Google Workspace subscription. To learn how to use this method, see [Create a Google Workspace subscription](https://developers.google.com/workspace/events/guides/create-subscription).
+  - `create` — Creates a Google Workspace subscription. To learn how to use this method, see [Create a Google Workspace subscription](https://developers.google.com/workspace/events/guides/create-subscription). For a subscription on a [Chat target resource](https://developers.google.com/workspace/events/guides/events-chat), you can create a subscription as: - A Chat app by specifying an authorization scope that begins with `chat.app` and getting one-time administrator approval.
   - `delete` — Deletes a Google Workspace subscription. To learn how to use this method, see [Delete a Google Workspace subscription](https://developers.google.com/workspace/events/guides/delete-subscription).
   - `get` — Gets details about a Google Workspace subscription. To learn how to use this method, see [Get details about a Google Workspace subscription](https://developers.google.com/workspace/events/guides/get-subscription).
   - `list` — Lists Google Workspace subscriptions. To learn how to use this method, see [List Google Workspace subscriptions](https://developers.google.com/workspace/events/guides/list-subscriptions).
-  - `patch` — Updates or renews a Google Workspace subscription. To learn how to use this method, see [Update or renew a Google Workspace subscription](https://developers.google.com/workspace/events/guides/update-subscription).
+  - `patch` — Updates or renews a Google Workspace subscription. To learn how to use this method, see [Update or renew a Google Workspace subscription](https://developers.google.com/workspace/events/guides/update-subscription). For a subscription on a [Chat target resource](https://developers.google.com/workspace/events/guides/events-chat), you can update a subscription as: - A Chat app by specifying an authorization scope that begins with `chat.app` and getting one-time administrator approval.
   - `reactivate` — Reactivates a suspended Google Workspace subscription. This method resets your subscription's `State` field to `ACTIVE`. Before you use this method, you must fix the error that suspended the subscription. This method will ignore or reject any subscription that isn't currently in a suspended state. To learn how to use this method, see [Reactivate a Google Workspace subscription](https://developers.google.com/workspace/events/guides/reactivate-subscription).
 
 ### tasks

diff --git a/skills/gws-forms/SKILL.md b/skills/gws-forms/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # forms (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws forms <resource> <method> [flags]

diff --git a/skills/gws-gmail-forward/SKILL.md b/skills/gws-gmail-forward/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +forward
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Forward a message to new recipients
 

diff --git a/skills/gws-gmail-read/SKILL.md b/skills/gws-gmail-read/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +read
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Read a message and extract its body or headers
 

diff --git a/skills/gws-gmail-reply-all/SKILL.md b/skills/gws-gmail-reply-all/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +reply-all
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Reply-all to a message (handles threading automatically)
 

diff --git a/skills/gws-gmail-reply/SKILL.md b/skills/gws-gmail-reply/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +reply
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Reply to a message (handles threading automatically)
 

diff --git a/skills/gws-gmail-send/SKILL.md b/skills/gws-gmail-send/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +send
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Send an email
 

diff --git a/skills/gws-gmail-triage/SKILL.md b/skills/gws-gmail-triage/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +triage
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Show unread inbox summary (sender, subject, date)
 

diff --git a/skills/gws-gmail-watch/SKILL.md b/skills/gws-gmail-watch/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail +watch
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 Watch for new emails and stream them as NDJSON
 

diff --git a/skills/gws-gmail/SKILL.md b/skills/gws-gmail/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # gmail (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws gmail <resource> <method> [flags]

diff --git a/skills/gws-keep/SKILL.md b/skills/gws-keep/SKILL.md
@@ -13,7 +13,7 @@ metadata:
 
 # keep (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If you're installing skills selectively, install `gws-shared` alongside this skill. If you're generating skills from a local checkout, run `gws generate-skills` to create it.
 
 ```bash
 gws keep <resource> <method> [flags]