How to use the Google Apps Script Manager agent skill (gws-script)

What the gws-script skill lets the agent do

An agent skill is a folder containing a SKILL.md file that tells an AI agent how to perform a task. This skill covers the Apps Script part of the gws CLI. Once installed, the agent knows which commands exist for listing script processes, creating projects, reading or overwriting a project's code, viewing metrics, and running scripts. It also knows to look up required parameters before calling a command.

The skill does not do any of this by itself. It only describes commands, so the gws tool must be installed and authenticated on your machine.

• processes: list user processes and list a script's executed processes, including process type and current status
• projects: create an empty project, get project metadata, get project content, get metrics such as executions and active users, and update content
• scripts: run a script
• A helper command, +push, that uploads local files to an Apps Script project

Install the gws-script skill

Download the ZIP file from this page and unzip it. The skill is contained in SKILL.md. Put the unzipped folder in one of these locations:

For all of your projects, place it in ~/.claude/skills/. For a single project, place it in that project's .claude/skills/ folder.

Alternatively, in the Claude apps, open Settings, then Capabilities, then Skills, and upload the skill there.

• Personal: ~/.claude/skills/
• Project only: .claude/skills/ inside the project folder
• Claude apps: Settings → Capabilities → Skills

Set up the gws tool and authentication

The skill needs the gws command-line tool (the googleworkspace CLI) and a Google account authenticated for gws. The skill's prerequisite note points to ../gws-shared/SKILL.md, which covers authentication, global flags and security rules. Make sure that file exists alongside this skill.

If the shared file is missing, the skill says to run gws generate-skills to create it. You can check the command reference with gws script --help.

• Required: gws command-line tool
• Required: Google account authentication configured for gws, per the gws-shared skill
• Required: read access to ../gws-shared/SKILL.md (run gws generate-skills if it is missing)

Ask the agent in plain language

You do not need to type commands yourself. Describe the outcome you want and the agent will choose the matching gws script resource and method. Name the project or the script when you can, because the commands work on specific project IDs.

Before calling any method, the agent is directed to inspect it with gws schema, which shows required parameters, types and defaults. You can ask the agent to do this first if you want to review the plan.

• "List the recent processes for my Apps Script projects."
• "Show me the execution count and active users for this script over the last period." (uses getMetrics)
• "Show me the files in this Apps Script project." (uses getContent)
• "Create a new empty Apps Script project called Invoice Reminders." (uses create)
• "Upload the local files in this folder to my Apps Script project with the push helper." (uses +push)

Inspect a method before the agent calls it

The skill tells the agent to browse resources and methods, then inspect a method's parameters. You can run the same checks yourself to see what the agent will send.

The agent builds its --params and --json flags from the gws schema output, so this step is where wrong or missing inputs are caught.

Safety: overwrites, scripts and network access

The updateContent method clears all existing files in a project and replaces them with the new content. A mistake can destroy code. Review the content and keep a copy of the current code before asking for an update. Note also that updateContent sets the HEAD version, which is used by triggers, the script editor, add-on preview mode, and web apps or the Apps Script API in development mode.

The run method executes code with the permissions of the account you authenticated. Do not use it against production data without reviewing the script first. This skill runs scripts and uses the network.

• Overwriting: updateContent deletes all existing project files first
• Running: scripts run with your Google account's permissions
• Network: the skill makes calls to Google services through gws

Tips for better results

Give the agent exact project and script IDs when you have them, and say which resource you mean (processes, projects, or scripts). Ask for a schema check before any write or run.

If a command fails, check that gws is installed, that you are authenticated, and that ../gws-shared/SKILL.md is present. Run gws generate-skills if that file is missing.

• Ask for a read (getContent) before any update so you can compare
• Ask the agent to show the gws schema output before any run
• Keep a backup of project code before updateContent