fix(skills): treat shared guidance as reference

.changeset/agent-skill-shared-reference.md

@@ -0,0 +1,5 @@
+---
+"@googleworkspace/cli": patch
+---
+
+Clarify generated skills treat gws-shared as reference material for agent environments.

crates/google-workspace-cli/src/generate_skills.rs

@@ -26,6 +26,12 @@ use std::path::Path;
 
 const PERSONAS_TOML: &str = include_str!("../registry/personas.toml");
 const RECIPES_TOML: &str = include_str!("../registry/recipes.toml");
+const SHARED_REFERENCE_NOTE: &str = concat!(
+    "> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, ",
+    "and security rules. Treat it as background guidance; do not run auth, ",
+    "setup, cache, or `gws generate-skills` commands unless the user explicitly ",
+    "asks or a command fails because setup is missing.\n\n"
+);
 
 /// Methods blocked from skill generation.
 /// Format: (service_alias, resource, method).
@@ -403,9 +409,7 @@ metadata:
     let api_version = entry.version;
     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",
-    );
+    out.push_str(SHARED_REFERENCE_NOTE);
 
     out.push_str(&format!(
         "```bash\ngws {alias} <resource> <method> [flags]\n```\n\n",
@@ -540,9 +544,7 @@ metadata:
     // Title
     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",
-    );
+    out.push_str(SHARED_REFERENCE_NOTE);
 
     out.push_str(&format!("{about}\n\n"));
 
@@ -730,6 +732,13 @@ gws <service> <resource> [sub-resource] <method> [flags]
 - Prefer `--dry-run` for destructive operations
 - Use `--sanitize` for PII/content safety screening
 
+## Agent and Sandbox Use
+
+- Treat this file as reference material, not a startup checklist
+- Assume `gws` is already installed and authenticated unless the requested command fails
+- Do not run auth, setup, cache, or `gws generate-skills` commands unless the user asks or setup is required to recover from a specific failure
+- In read-only or locked-down environments, prefer the requested read-only helper command directly and report missing filesystem or auth access instead of probing the environment
+
 ## Shell Tips
 
 - **zsh `!` expansion:** Sheet ranges like `Sheet1!A1` contain `!` which zsh interprets as history expansion. Use double quotes with escaped inner quotes instead of single quotes:
@@ -1274,6 +1283,14 @@ mod tests {
             fm.contains("- gws"),
             "frontmatter should contain '- gws' block entry"
         );
+        assert!(
+            md.contains("Treat it as background guidance"),
+            "service skills should describe gws-shared as reference material"
+        );
+        assert!(
+            !md.contains("PREREQUISITE"),
+            "service skills should not require reading gws-shared before use"
+        );
     }
 
     #[test]
@@ -1291,6 +1308,14 @@ mod tests {
             fm.contains("- gws"),
             "shared skill frontmatter should contain '- gws'"
         );
+        assert!(
+            content.contains("## Agent and Sandbox Use"),
+            "shared skill should include agent and sandbox guidance"
+        );
+        assert!(
+            content.contains("not a startup checklist"),
+            "shared skill should not be interpreted as required startup steps"
+        );
     }
 
     #[test]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws admin-reports <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Show upcoming events across all calendars
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 create a new event
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws calendar <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Send a message to a space
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws chat <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws classroom <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Append text to a document
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws docs <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Upload a file with automatic metadata
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws drive <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Renew/reactivate Workspace Events subscriptions
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Subscribe to Workspace events and stream them as NDJSON
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws events <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws forms <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Forward a message to new recipients
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Read a message and extract its body or headers
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Reply-all to a message (handles threading automatically)
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Reply to a message (handles threading automatically)
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Send an email
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Show unread inbox summary (sender, subject, date)
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Watch for new emails and stream them as NDJSON
 

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws gmail <resource> <method> [flags]

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.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws keep <resource> <method> [flags]

skills/gws-meet/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # meet (v2)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws meet <resource> <method> [flags]

skills/gws-modelarmor-create-template/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # modelarmor +create-template
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Create a new Model Armor template
 

skills/gws-modelarmor-sanitize-prompt/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # modelarmor +sanitize-prompt
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Sanitize a user prompt through a Model Armor template
 

skills/gws-modelarmor-sanitize-response/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # modelarmor +sanitize-response
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Sanitize a model response through a Model Armor template
 

skills/gws-modelarmor/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # modelarmor (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws modelarmor <resource> <method> [flags]

skills/gws-people/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # people (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws people <resource> <method> [flags]

skills/gws-script-push/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # script +push
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 Upload local files to an Apps Script project
 

skills/gws-script/SKILL.md

@@ -13,7 +13,7 @@ metadata:
 
 # script (v1)
 
-> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.
+> **REFERENCE:** See `../gws-shared/SKILL.md` for auth, global flags, and security rules. Treat it as background guidance; do not run auth, setup, cache, or `gws generate-skills` commands unless the user explicitly asks or a command fails because setup is missing.
 
 ```bash
 gws script <resource> <method> [flags]