Agent skills: gws-gmail prereq on gws-shared causes unnecessary ceremony in agent environments
Mantenedores costumam responder em até 1 dia
Ninguém assumiu esta issue ainda.
- #862 de @initiallyqq — fechado sem integrar
Avaliação
- Dificuldade
- 4/5
- Tempo estimado
- 3-5 dias
- Facilidade para iniciantes
- 48/100
- Tipo de issue
- Documentação
- Clareza
- Razoavelmente clara
- Status de atividade
- Pouca atividade
- Stack de tecnologia
- markdown
- Domínio
- cli, developer-experience, documentation
Direção de pesquisa
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.
Escrita pelo modelo de indexação a partir do texto da issue.
Descrição
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.
- Linguagem predominante
- Rust
- Estrelas
- 32.3k
- Forks
- 2k
- Merge médio
- 16h 3min
- PRs com merge (30d)
- 1
Preparar o ambiente
- Sem Dockerfile nem arquivo Docker Compose
- Tem um modelo de pull request
- Ler o guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Mais de googleworkspace/cli
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 80/100
googleworkspace/cli#984 ·
Mantenedores costumam responder em até 1 dia
-
auth export masks secrets by default with no warning; consumers fail later with invalid_clientAberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 64/100
googleworkspace/cli#983 ·
Mantenedores costumam responder em até 1 dia
-
Replace gemini with agyAberta
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 82/100
googleworkspace/cli#958 ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 82/100
googleworkspace/cli#921 ·
Mantenedores costumam responder em até 1 dia
-
Dificuldade 1/5 Menos de uma hora Facilidade para iniciantes 88/100
googleworkspace/cli#920 ·
Mantenedores costumam responder em até 1 dia
Todas as issues de googleworkspace/cli
Issues semelhantes
-
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 78/100
matrix-org/matrix-rust-sdk#7495 ·
Mantenedores costumam responder em até 1 dia
-
bug
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 75/100
yantrikos/yantrik-os#1272 ·
Mantenedores costumam responder em até 1 dia
-
crate: spate-kafka priority: low tech-debt
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 74/100
Mantenedores costumam responder em até 1 dia
-
[Bug]: Executable check only looks at the "others" execute bit, so 0750 binaries are rejectedAberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 72/100
Mantenedores costumam responder em até 1 dia
-
macOS 菜单栏托盘图标保留橙色,与系统单色图标风格不一致Talvez já em andamento @xhugoliu assumiu hoje. Aberta
Dificuldade 2/5 1-3 horas Facilidade para iniciantes 70/100
YizhengWw/HachimoDock#56 · 1 comentário ·