--- title: "Atomic Skills and Role-Based Recipes: The Architecture of the Google Workspace CLI" author: "Martin Hawksey" date: 2026-04-21T14:36:32+00:00 modified: 2026-04-21T14:38:32+00:00 canonical_url: https://pulse.appsscript.info/p/2026/04/atomic-skills-and-role-based-recipes-the-architecture-of-the-google-workspace-cli/ markdown_url: https://pulse.appsscript.info/p/2026/04/atomic-skills-and-role-based-recipes-the-architecture-of-the-google-workspace-cli.md categories: - "Advanced" - "Comment" - "Solutions" tags: - "Editor" featured_image: https://pulse.appsscript.info/files/2026/04/workspace-cli.jpg description: "Exploring the modular architecture of the Google Workspace CLI. This post examines how atomic skills and persona-driven recipes provide a token-efficient, programmable runtime for developers and AI agents." --- # Atomic Skills and Role-Based Recipes: The Architecture of the Google Workspace CLI ![Atomic Skills and Role-Based Recipes: The Architecture of the Google Workspace CLI](https://pulse.appsscript.info/files/2026/04/workspace-cli.jpg) ![](https://pulse.appsscript.info/files/2026/04/workspace-cli.jpg) I have spent a significant portion of my career working with various command-line interfaces for Google Workspace, from [`gcloud`**](https://cloud.google.com/sdk/gcloud) to [`gam`**](https://github.com/GAM-team/GAM). The recent release of the [Google Workspace CLI**](https://github.com/googleworkspace/cli) (`gws`), which is **not** an officially supported Google product but has a number of Googler contributions, represents a fundamental shift in how we interact with the entire Google API surface. In this post, I will provide an overview of the `gws` tool and explain how it differs from the Gemini CLI Workspace Extensions. More importantly, we will examine the modular architecture of “Skills”, “Recipes” and “Personas” that makes this tool in my view a masterpiece in modern, role-based automation. ## **GWS vs. GAM: Understanding the Overlap** Many Workspace Admins are already deeply familiar with `gam` (Google Apps Manager), the open-source command-line tool that has long served as a staple for domain administration. While `gam` is exceptional for bulk administrative tasks, such as creating users, modifying groups, or auditing devices, `gws` serves a different primary audience. There is certainly a slight overlap between the two. You will notice administrative skills like [`gws-admin-reports`**](https://github.com/googleworkspace/cli/tree/main/skills/gws-admin-reports) present in the new repository. However, `gws` is fundamentally a developer and agentic tool focused on individual productivity applications like Drive, Gmail, and Docs, rather than domain-wide directory administration. ## **GWS vs. Gemini CLI Workspace Extensions** It is easy to confuse the Google Workspace CLI with the Workspace Extensions available for the Gemini CLI, but they serve entirely different purposes. The Gemini CLI Extension is a high-level interface designed for natural language tasks, such as “Summarize my unread emails” or “Find a file in Drive.” It is a convenient, user-centric tool for common, daily interactions. In contrast, `gws` is a developer’s infrastructure tool. While the Gemini Extension is about “doing,” `gws` is about “orchestrating.” It provides the granular, programmatic control needed to build complex, multi-step workflows that can be automated, tested, and shared across a team. ## **The Modular Approach: Atomic Skills** The repository breaks down Google Workspace API interactions into highly modular components called “skills”. Instead of a monolithic script handling an entire workflow, the architecture relies on specific, atomic actions. Some examples from the repository include [`gws-gmail-send`**](https://github.com/googleworkspace/cli/tree/main/skills/gws-gmail-send) and [`gws-docs-write`**](https://github.com/googleworkspace/cli/tree/main/skills/gws-docs-write). This atomic design means each skill has a single responsibility. For Apps Script developers, this is highly reminiscent of creating focused, single-purpose functions within an Apps Script library. By keeping these functions isolated, the code becomes easier to test, maintain, and reuse across different parts of an application. ## **Combining Forces: Recipes and Personas** Where this architecture becomes particularly interesting is how it combines these basic building blocks. The repository introduces the concept of “recipes,” such as [`recipe-backup-sheet-as-csv`**](https://github.com/googleworkspace/cli/tree/main/skills/recipe-backup-sheet-as-csv) or [`recipe-create-expense-tracker`**](https://github.com/googleworkspace/cli/tree/main/skills/recipe-create-expense-tracker). These recipes orchestrate multiple underlying skills to achieve a larger, practical goal. In addition, these recipes are mapped to specific user “personas” like [`persona-content-creator`**](https://github.com/googleworkspace/cli/tree/main/skills/persona-content-creator) or [`persona-it-admin`**](https://github.com/googleworkspace/cli/tree/main/skills/persona-it-admin). By grouping actions based on the user’s operational role, the tool becomes highly intuitive. When building Google Workspace automation tools, adopting a persona-driven approach can significantly improve the user experience: you are no longer just presenting a list of features, but offering targeted workflows tailored to what the user actually needs to accomplish their daily work. ## **Why this Approach Fits Workspace APIs Perfectly** This architectural choice is particularly effective given the versatile nature of Google Workspace APIs. Consider the Google Drive API, which features a generic endpoint for creating files. A basic integration might simply expose this raw “create file” capability. However, given the massive range of situations where you might want to create a file, a generic tool often leaves users or AI agents guessing how to properly format the request. This is where skills, recipes, and personas show their true value. They allow us to dictate exactly *how* a file should be created for a specific context. For instance, if you want to turn a Markdown document into a natively formatted Google Doc, you could try to use the complex Google Docs API to insert text paragraph by paragraph. Instead, a targeted recipe can use the [Drive API’s built-in file conversion features**](https://developers.google.com/workspace/drive/api/guides/manage-uploads#import-docs). By packaging instructions to upload the Markdown content and explicitly set the target MIME type to `application/vnd.google-apps.document`, the recipe abstracts away a complex API quirk into a reliable, repeatable action. ## **The Future of Agentic AI: The CLI + Skills Paradigm** As a [recent VentureBeat article**](https://venturebeat.com/orchestration/google-workspace-cli-brings-gmail-docs-sheets-and-more-into-a-common) highlighted, the real breakthrough of `gws` is not that it makes Google Workspace programmable, given those APIs have existed for years. Instead, the innovation is the interface itself. By eliminating the need for custom wrappers and endless glue code, the CLI transforms Workspace from a collection of siloed applications into a single, unified programmable runtime. This touches on a growing industry debate around the Model Context Protocol (MCP). Interestingly, while `gws` initially launched with a native MCP server mode, the maintainers explicitly [removed it in version 0.8.0**](https://github.com/googleworkspace/cli/blob/main/CHANGELOG.md). Justin Poehnelt, one of the main contributors behind `gws`, refers to this overhead as the [“MCP Abstraction Tax”**](https://justin.poehnelt.com/posts/mcp-abstraction-tax/). Exposing hundreds of granular API tools via a standard MCP server requires passing massive JSON schemas that bloat the AI’s context window and often lead to complex mapping bugs. Instead, `gws` is now focused on a pure “CLI + Skills” architecture. In a related post on why developers should [“Rewrite your CLI for AI Agents”**](https://justin.poehnelt.com/posts/rewrite-your-cli-for-ai-agents/), Justin outlines a shift from *imperative* to *declarative* design. An AI agent should “think” in terms of the high-level business goal (the “what”) rather than worrying about the underlying API steps to edit a document (the “how”). By moving the complex reconciliation logic directly into the CLI library, agents can simply use bash commands, a language they are already highly fluent in, to execute tasks efficiently. Agent skills supply the “recipes” for these declarative commands, acting as modular, portable sets of instructions that teach an AI agent exactly which CLI tools to execute. The repository already incorporates over 100 of these Markdown skills, following a standardised structure. This framework is a powerful example of how we are moving away from simple prompt engineering toward “Skill Engineering”. By encoding our organisational knowledge and engineering judgement into these portable files, we ensure that AI agents follow token-efficient, reliable workflows every time they interact with our data. ## **Summary** The Google Workspace CLI is a glimpse into a future where our development environments are natively aware of our roles and workflows. For those interested in mastering this new framework, Anthropic recently shared a [Complete Guide to Building Skills for Claude**](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf) which explores the technical patterns and best practices for creating your own high-order skills. Whether you are looking to automate your local development loop or build complex agentic workflows, the `googleworkspace/cli` provides the infrastructure you should keep an eye on! --- *Published by [Martin Hawksey](https://pulse.appsscript.info/p/author/admin/) on [Pulse](https://pulse.appsscript.info/). Original article: [https://pulse.appsscript.info/p/2026/04/atomic-skills-and-role-based-recipes-the-architecture-of-the-google-workspace-cli/](https://pulse.appsscript.info/p/2026/04/atomic-skills-and-role-based-recipes-the-architecture-of-the-google-workspace-cli/)*