Skip to content
Get packs

Guide · Agent skill

How to use the Google Chat Manager agent skill (gws-chat)

Updated · written with AI from the project's own documentation and checked against our catalogue data

The gws-chat skill is a set of instructions that teaches an AI agent how to manage Google Chat spaces and messages through the gws command-line tool. This guide explains what the skill lets the agent do, how to install it, how to ask for things in plain language, and what to check before letting it change anything. By the end you will be able to install the skill, run a few safe requests and know where the risks are.

Google Chat Managergoogleworkspace/cli · Apache-2.0

Quick start

  1. 1Download the ZIP. Download the gws-chat skill ZIP from this page.
  2. 2Unzip the skill. Unzip it so the gws-chat folder contains SKILL.md.
  3. 3Place or upload the skill. Move the folder to ~/.claude/skills/ or a project's .claude/skills/, or upload the ZIP under Settings → Capabilities → Skills in the Claude apps.
  4. 4Install and authorise gws. Make sure the gws command-line tool is installed and your Google account is authorised with gws auth, as described in ../gws-shared/SKILL.md.
  5. 5Ask a read-only question. Start with a listing request, such as listing your spaces, to confirm the agent can reach your account.
  6. 6Make changes with review. For updates or deletions, ask the agent to show the target first and confirm before it runs the change.

What the gws-chat skill makes the agent do

Once installed, the agent knows how to work with Google Chat through the gws command-line tool. The skill covers spaces (list, create, get, update, delete, and look up direct messages), custom emoji (create, get, list, delete), and media (upload and download message attachments). It also covers messages, members and space events, which the skill lists as resources without detailed examples.

Before calling any method, the skill tells the agent to look up the exact parameters with gws schema. The agent therefore builds requests from the official API definitions rather than guessing field names.

  • Spaces: list, create, get, patch (update), delete, findDirectMessage, search (admin), setup
  • Custom emoji: create, get, list, delete
  • Media: upload and download attachments

Install the gws-chat skill

Download the skill ZIP from this page and unzip it. For a personal install, place the skill folder in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

The skill package contains one file, SKILL.md. The skill also needs the gws command-line tool installed. Read ../gws-shared/SKILL.md for authentication setup; if that file is missing, the skill says to run gws generate-skills to create it.

  • Personal install: ~/.claude/skills/
  • Project install: .claude/skills/ inside the project
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Check the prerequisites

The skill needs the gws command-line tool (the googleworkspace CLI) and a Google account authorised through gws auth. The shared authentication details are in ../gws-shared/SKILL.md.

Custom emoji and admin search features require a Google Workspace account. Custom emoji also require the administrator to turn custom emojis on for the organisation.

  • gws command-line tool installed
  • Google account authorised via gws auth
  • Google Workspace account for custom emoji and admin search
gws chat --help

Ask for things in natural language

You do not need to remember command syntax. Describe the outcome you want and the agent chooses the resource and method. Be specific about the space name, the user or the attachment, because the agent has to find the right object before acting.

When you want to inspect before changing, say so. Asking the agent to list or get a space first is a safe way to confirm it has found the right one.

  • List the spaces I am a member of and show their display names.
  • Find my direct message space with a named colleague.
  • Show details for the space called Project Alpha before changing anything.
  • Upload this file as an attachment to the space called Launch Notes.
  • List custom emoji available in my organisation.

Safety notes: scripts and network access

This skill runs scripts and uses the network. It acts on real Google Chat accounts and data, not on a sandbox. Every request goes to Google's API using the account you authorised.

Deletion is the main risk. The source says that deleting a space always performs a cascading delete, which removes its messages and memberships. The source does not describe any undo. Ask the agent to confirm the exact space before any delete, and review the target yourself first.

  • Use gws auth only with accounts you intend the agent to act on.
  • Review any delete or patch request before the agent runs it.
  • Do not use the skill for destructive changes without a review step.

Tips for better results

Give the display name or the resource identifier of the space, not a vague description. If an update fails with an ALREADY_EXISTS error on displayName, the source suggests trying a different display name, because another space in the organisation may already use it.

Group chats and direct messages do not appear in list results until the first message is sent. If a conversation is missing, that is expected behaviour.

  • Include the exact display name when renaming a space.
  • Expect new group chats and DMs to be missing from lists until a message is sent.
  • Run gws chat --help to see the resources available in your installed version.

What people use it for

  • Listing the Chat spaces you belong to and tidying up names.
  • Finding an existing direct message space with a colleague.
  • Creating a named space and adding initial members with the setup method.
  • Uploading or downloading message attachments from the command line.
  • Reviewing custom emoji available in a Google Workspace organisation.

Frequently asked questions

What is the gws-chat skill?

It is an agent skill, a SKILL.md instruction file, that teaches an AI agent to manage Google Chat spaces and messages through the gws command-line tool. The agent looks up exact parameters with gws schema before each call.

What do I need to use the gws-chat skill?

You need the gws command-line tool, a Google account authorised through gws auth, and for custom emoji and admin search, a Google Workspace account. The shared auth details are in ../gws-shared/SKILL.md.

How do I install the gws-chat skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

Is the gws-chat skill free?

The skill is licensed under Apache-2.0, as listed for the googleworkspace/cli repository. The source does not describe pricing, and Google Workspace or Chat accounts are needed to use it.

Can the agent delete Google Chat spaces?

Yes, the spaces delete method is included. The source says it always deletes the space's messages and memberships too, and describes no undo, so review the target before allowing it.

Why is my Chat space or DM missing from the agent's list?

The source says group chats and direct messages are not listed until the first message is sent. Also check that the account authorised with gws auth is the one that belongs to the space.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits Workspace admins, developers and teams already using gws who want an agent to organise Chat spaces or automate routine Chat tasks. It is not suitable for anyone without a Google Workspace or Chat account, or for destructive clean-up that has no review step, because deletes remove spaces and their messages with no described undo.

Download the skill