Agent skills: gws-gmail prereq on gws-shared causes unnecessary ceremony in agent environments
Maintainers usually reply within 1 day
Nobody has claimed this yet.
- #862 by @initiallyqq — closed without merging
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 48/100
- Issue type
- Documentation
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- markdown
- Domain
- cli, developer-experience, documentation
Research direction
Start by reading skills/gws-gmail/SKILL.md and skills/gws-shared/SKILL.md, focusing on the prerequisite wording and the installation, authentication, global flags, and security sections. Compare the current guidance with the proposed agent use cases. Done means core Gmail operations no longer imply unnecessary diagnostics, while optional setup guidance and agent or sandbox considerations are clearly documented.
Written by the indexing model from the issue text.
Description
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:
- Reads
skills/gws-gmail/SKILL.md. - Sees the prerequisite note and reads
../gws-shared/SKILL.md. - From
gws-shared, infers it should:- verify auth,
- sometimes run
gws auth statusor a “cheap” profile call such as
gws gmail users getProfile --params '{"userId":"me"}', - potentially touch cache/discovery paths to avoid discovery errors.
- 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/+readwithout 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-skillsif 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:
-
Clarify that
gws-sharedis “reference” not “must-run behavior”- Change the wording from “PREREQUISITE: Read
../gws-shared/SKILL.md” to something more like “See../gws-shared/SKILL.mdfor background on auth/global flags,” to avoid agents treating it as mandatory procedural steps.
- Change the wording from “PREREQUISITE: Read
-
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 loginnow”, “set XDG_CACHE_HOME here”) into a “manual setup” section, not a runtime pattern for agents.
- Keep installation/auth/global-flag docs there for humans, but clearly separate anything that implies active shell commands (“run
-
Provide a minimal agent-focused variant
- For example, a
gws-gmail-readorgws-gmail-minimalskill that:- assumes
gwsis 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 fewusers.*read methods.
- assumes
- This would make it much easier to integrate safely into agent environments that already handle auth and filesystem concerns externally.
- For example, a
-
Document agent/sandbox considerations in the skills
- A short “Agent Integration” section describing:
- where
gwsstores 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).
- where
- A short “Agent Integration” section describing:
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.
- Dominant language
- Rust
- Stars
- 32.3k
- Forks
- 2k
- Avg merge
- 16h 3m
- Merged PRs (30d)
- 1
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from googleworkspace/cli
-
Difficulty 2/5 1-3 hours Newbie friendliness 80/100
googleworkspace/cli#984 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
googleworkspace/cli#983 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 82/100
googleworkspace/cli#958 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
googleworkspace/cli#921 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
googleworkspace/cli#920 ·
Maintainers usually reply within 1 day
All issues in googleworkspace/cli
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
status: new topic: ga4gh-sdk type: bug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Maintainers usually reply within 1 day
-
comp-rbac
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
ClickHouse/ClickHouse#131875 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
Maintainers usually reply within 1 day
-
bug(python): read_transaction raises TypeError on a Rewrite with rewritten indicesPossibly taken @Borg93 claimed this today. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
lance-format/lance#11117 ·
Maintainers usually reply within 2 days