Refactor generated skills into canonical skill with reference files to reduce agent overhead

[barronlroth]

Summary

Please consider refactoring the generated Google Workspace CLI skills from many separate top-level skills into a smaller number of canonical skills that use references/ markdown files for the detailed sub-guides.

Concretely, instead of installing dozens of independent skills such as gws-gmail-send, gws-gmail-read, gws-calendar-insert, gws-sheets-read, etc., ship something closer to:

google-workspace/
  SKILL.md
  references/
    gmail.md
    gmail-send.md
    gmail-read.md
    calendar.md
    calendar-insert.md
    drive.md
    sheets.md
    docs.md
    chat.md
    admin.md
    workflows.md

The top-level SKILL.md would act as the routing layer: explain when to use the skill, summarize available capability areas, and point agents to the relevant reference file(s) for task-specific details.

Motivation

Agent skill overhead is a real cost. Many agent runtimes expose the installed skill index to the model on every turn, even when the full skill body is not loaded. A repo that contributes dozens of top-level skills can meaningfully increase prompt size and skill-selection noise for every downstream agent session.

At the moment, this repo still appears to expose many top-level skill directories. From the GitHub contents API, I currently see approximately:

• 44 gws-* skill directories
• 41 recipe-* skill directories
• 10 persona-* skill directories
• 95 total directories under skills/

That makes the CLI very capable, but it is costly for agents that already have many other domain skills installed.

This is especially painful because the gws-* skills are highly related and often cross-reference each other. For an agent, the problem is not only token count; it is also routing ambiguity. Similar top-level skills like gws-gmail, gws-gmail-send, gws-gmail-read, gws-gmail-reply, and gws-gmail-reply-all compete in skill selection even though they are really chapters of the same Workspace operating manual.

Prior art / related issue

This is related to #82, which was closed as completed, but the current repo layout still seems to include dozens of top-level generated skills. If there has already been a newer consolidation path, it would be useful to document it clearly for downstream agent frameworks and skill installers.

Proposed direction

A possible structure:

1. Keep one canonical google-workspace or gws skill as the main entry point.
2. Move detailed service/action documentation into reference files under that skill:
   • references/gmail.md
   • references/gmail-send.md
   • references/calendar.md
   • references/drive.md
   • references/sheets.md
   • etc.
3. Keep the root SKILL.md short and index-like:
   • prerequisites/auth
   • global CLI conventions
   • service routing table
   • pointers to the relevant reference files
4. Optionally keep a few truly distinct top-level skills only where they represent a different persona/workflow, not every individual command.
5. Provide a migration path or compatibility alias for users who installed the older granular skills.

Why this helps

• Lower prompt/token overhead for agents
• Less skill-selection ambiguity
• Easier maintenance: shared auth/conventions live in one place
• Better fit for emerging skill patterns where SKILL.md is a concise router and references/ holds detailed docs
• Less risk of stale or conflicting instructions across dozens of near-duplicate skills

Acceptance criteria suggestion

• The default installation path exposes a small number of top-level skills for Google Workspace.
• Detailed generated operation docs are accessible as linked reference files from the canonical skill.
• The canonical SKILL.md clearly tells agents which reference file to load for each service/task.
• Existing granular skill users have a documented migration path.

[mieubrisse]

I have exactly this problem; would love a fix here