Agent skills: gws-gmail prereq on gws-shared causes unnecessary ceremony in agent environments

[jdkang]

Agent skills: gws-gmail prereq on gws-shared causes unnecessary ceremony in agent environments

Summary

When using the gws-gmail skill from AI coding/agent environments (e.g. Claude Code), the prerequisite on ../gws-shared/SKILL.md makes the agent go through a lot of startup “ceremony” (auth checks, profile calls, cache/state probing) before actually running the requested Gmail command. This behavior is reasonable in a human-driven shell, but it’s problematic in locked-down agent environments with strict permissions and read-only/sandboxed filesystems.

It would be helpful if the skills were structured so that:

• “Core” Gmail operations (e.g. +triage, +read) can be used without pulling in all of the shared auth/setup heuristics, and
• The shared file is clearly separated into optional guidance vs. required steps, or at least toned down for agent use.

---

Files and lines

The key line is in skills/gws-gmail/SKILL.md:

> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.

(At time of writing, this is in skills/gws-gmail/SKILL.md on the main branch; the line number may change as the file evolves.)

The shared reference is in:

• skills/gws-shared/SKILL.md

which contains the installation, authentication, global flags, and “security rules” sections that an agent interprets as “do environment and auth diagnostics before doing anything useful.”

---

What happens in practice

In an agent environment with a skill that wraps gws-gmail, if I ask for a simple read-only operation like “summarize my unread inbox” with gws gmail +triage, the agent:

1. Reads skills/gws-gmail/SKILL.md.
2. Sees the prerequisite note and reads ../gws-shared/SKILL.md.
3. From gws-shared, infers it should:
   • verify auth,
   • sometimes run gws auth status or a “cheap” profile call such as
     gws gmail users getProfile --params '{"userId":"me"}',
   • potentially touch cache/discovery paths to avoid discovery errors.
4. Only then does it try to run gws gmail +triage.

In a sandboxed/locked-down environment (e.g. Claude Code with:

• restricted Bash permissions,
• a read-only or whitelisted filesystem,
• and an external permissions system that requires allow/deny patterns),

this ceremony is actively harmful:

• It triggers shell commands that:
  • the user did not explicitly ask for,
  • may not be allowed by the agent’s permission model, and
  • may fail because the assumed cache/state directories are not writable.
• It makes the skill harder to safely integrate: I have to explicitly block env inspection, cache tweaks, and some of the auth helpers on the agent side, and write a new “minimal” SKILL.md that just runs +triage / +read without all the shared behavior.

Concretely, I saw the agent trying to run things like:

gws gmail users getProfile --params '{"userId":"me"}'

and even cache-related commands, before the actual gws gmail +triage I asked for. In my case this resulted in:

• discovery/cache writes hitting a read-only filesystem, and
• the agent then being unable to fix it because my own minimal skill rules forbid it from probing env vars or overriding cache paths.

---

Why this is a problem for agent users

The current prereq wording:

> **PREREQUISITE:** Read `../gws-shared/SKILL.md` for auth, global flags, and security rules. If missing, run `gws generate-skills` to create it.

is interpreted by agents as:

• “You must consult gws-shared before using this skill.”
• “You may run gws generate-skills if it looks missing.”
• “You should follow the auth and shell hints there, which includes auth commands and possibly cache behavior.”

That’s a great UX if I am a human reading the docs in a shell and following them manually.

For an AI agent, it turns into:

• extra shell commands I never explicitly asked to run,
• tighter coupling between every Gmail operation and a shared, “do everything” auth/setup doc, and
• trouble in any environment that doesn’t look like a full, writable user shell.

This forces users like me to either:

• fork the skill and rewrite it into a “minimal, no-diagnostics, assume-env-is-correct” version, or
• add a lot of deny rules in the agent’s permission system to keep it from doing all the extra steps.

---

Suggested improvements

A few concrete ideas that would preserve the value of gws-shared for humans while making the skills friendlier to agents:

1. Clarify that gws-shared is “reference” not “must-run behavior”

   • Change the wording from “PREREQUISITE: Read ../gws-shared/SKILL.md” to something more like “See ../gws-shared/SKILL.md for background on auth/global flags,” to avoid agents treating it as mandatory procedural steps.

2. Split the shared file into “reference” vs “runtime behavior”

   • Keep installation/auth/global-flag docs there for humans, but clearly separate anything that implies active shell commands (“run gws auth login now”, “set XDG_CACHE_HOME here”) into a “manual setup” section, not a runtime pattern for agents.

3. Provide a minimal agent-focused variant

   • For example, a gws-gmail-read or gws-gmail-minimal skill that:
     • assumes gws is already installed and authenticated,
     • explicitly says “do not run env inspection, auth, or cache setup commands,”
     • and only documents core operations like +triage, +read, and a few users.* read methods.
   • This would make it much easier to integrate safely into agent environments that already handle auth and filesystem concerns externally.

4. Document agent/sandbox considerations in the skills

   • A short “Agent Integration” section describing:
     • where gws stores config and token state (~/.config/gws),
     • what needs to be writable (~/.config/gws, cache directory),
     • and which shell commands are assumed safe to run automatically (if any).

---

Why this matters

gws is positioned as “one CLI for all of Google Workspace” and ships with a rich skills library for AI agents. That’s great, but the current skills assume a fairly permissive, human-driven shell. As more people plug gws into agent environments that have:

• strict permission models,
• sandboxed filesystems,
• and external security policies,

a small change to how the skills reference gws-shared would make them much easier to adopt safely, without everyone having to fork and rewrite the SKILL.md files to remove ceremony.

---

What should be surfaced to the user?

In sandboxed envs it can also be unclear WHAT gws actually needs on disk.. The aforementioned gws-shared skill tries to abstract this which leads to a lot of prompts (some that look a bit sketchy).

For context, here is the project-level config I ended up using in a Claude Code repo to safely expose gws to an agent:

{
  "env": {
    "GOOGLE_WORKSPACE_CLI_CONFIG_DIR": "~/.config/gws",
    "XDG_CACHE_HOME": "~/.cache"
  },
  "permissions": {
    "allow": [
      "Bash(gws --help)",
      "Bash(gws gmail --help)",
      "Bash(gws schema *)",
      "Bash(gws auth status)",
      "Bash(gws gmail +triage*)",
      "Bash(gws gmail +read*)",
      "Bash(gws gmail users getProfile*)",
      "Bash(gws gmail users labels list*)",
      "Bash(gws gmail users messages list*)",
      "Bash(gws gmail users messages get*)",
      "Bash(gws gmail users threads list*)",
      "Bash(gws gmail users threads get*)",
      "Bash(gws gmail users settings filters list*)"
    ]
  },
  "sandbox": {
    "network": {
      "allowedDomains": [
        "accounts.google.com",
        "oauth2.googleapis.com",
        "www.googleapis.com",
        "gmail.googleapis.com"
      ]
    },
    "filesystem": {
      "allowRead": [
        "~/.config/gws",
        "~/.cache"
      ],
      "allowWrite": [
        "~/.config/gws",
        "~/.cache"
      ]
    }
  }
}

Perhaps if gws detects it doesn't have sufficient access it suggests writing a project-level boilerplate like this or surfaces a command to write the boilerplate (e.g. gws new-proj-settings etc.

[m13v]

splitting gws-shared into reference vs runtime closes the +triage case, but the ceremony comes back the moment any skill encodes setup as prose the agent reads. softening 'PREREQUISITE' to 'see for background' still leaves auth state as something the model infers probabilistically per run, not a precondition the runtime actually checks. so the next undeclared step, a cache path or a discovery write, drifts into unrequested shell calls the same way. the boundary the wording doesn't touch is that procedural intent lives in markdown instead of a declared capability the harness can enforce or skip.