How to use the Google Docs Access agent skill (gws-docs)

What is an agent skill and what does gws-docs do?

An agent skill is a folder containing a SKILL.md file. The file tells an AI agent when a task applies and how to carry it out. The gws-docs skill is for Google Docs. With it installed, the agent can run gws docs commands on your behalf.

The skill covers three Google Docs operations: reading a document's latest contents, creating a blank document with a title, and applying batch edits to a document. A helper command, +write, appends text to a document. Before acting, the skill points the agent to the shared gws setup for sign-in and safety rules, and it tells the agent to look up the exact inputs each operation needs.

• get: gets the latest version of a document
• create: creates a blank document using the title in the request
• batchUpdate: applies one or more updates; if any request is invalid, nothing is applied
• +write: appends text to a document

Install the gws-docs skill

The skill is distributed as a ZIP file from this page. You can install it in one of two ways.

For Claude Code, download the ZIP and unzip it into ~/.claude/skills/ to make it available to you everywhere, or into a project's .claude/skills/ folder to limit it to that project.

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

• Option 1 (personal): unzip into ~/.claude/skills/
• Option 2 (single project): unzip into the project's .claude/skills/ folder
• Option 3 (Claude apps): Settings → Capabilities → Skills, then upload the ZIP

Set up the gws tool and sign-in first

The skill cannot work without the gws command-line tool installed and available on your PATH. Authentication for Google Workspace is configured through gws and is described in the shared gws-shared SKILL.md file. The skill's prerequisite note says to run gws generate-skills if that shared file is missing.

You also need access to the target Google Docs in the account you signed in with.

• gws is installed and runs from your terminal
• Google Workspace authentication is configured via gws
• The shared gws-shared SKILL.md is present (run gws generate-skills if it is not)
• The target documents are accessible to the signed-in account

Ask for Google Docs work in natural language

You do not need to type commands yourself. Describe the task and name the document or the title you want. The agent should choose the matching operation and look up the inputs it needs with gws schema before running anything.

Be specific about the action. Asking for a summary of a document calls for reading it. Asking for a new document calls for creating one. Asking for an edit calls for batchUpdate, which applies changes directly.

• "Read the latest text of my Q3 planning doc and summarise the open decisions."
• "Create a blank Google Doc titled Meeting notes 12 May."
• "Append a short action-items section to the end of the project brief doc."

Discover commands and inputs

The skill tells the agent to inspect a method before calling it. You can do the same to see what the skill will use. Browse resources and methods with the help command, then inspect a method's required parameters, types and defaults with the schema command. The output is used to build the --params and --json flags.

The skill documents the generic form of the command, which you can use to see the same information yourself.

Safety notes: scripts and network access

This skill runs scripts and uses the network. It calls the gws tool, which talks to Google Workspace on your behalf, so anything the signed-in account can change through Google Docs can be changed by the agent.

batchUpdate applies edits directly. If any request in the batch is not valid, the whole request fails and nothing is applied, but valid requests are not held for review. A loose instruction could overwrite content. For sensitive documents, state exactly what to change, and check the result afterwards.

• Use an account and documents you are comfortable having automated
• Give precise instructions for edits, and name the exact text to change
• Keep a copy of important documents before large edits
• Review the document after the agent has written to it

Tips for reliable results

Check that gws works from the terminal before you ask the agent for Google Docs work, since most failures come from setup rather than from the skill itself. Name the document clearly so the agent reads the right file.

Use read and summarise requests first to confirm the agent sees the document you mean, then move to edits.

• Test gws docs --help in the terminal first
• Use read requests to confirm the right document before editing
• Ask for create or append steps one at a time when the change matters