How to use the Google Drive File Manager agent skill (gws-drive)

What the gws-drive skill lets the agent do

gws-drive is a reference of Google Drive API operations, organised by resource. It is not a standalone program. The agent reads the skill, then runs gws commands on your behalf in the form gws drive <resource> <method> [flags].

The source lists these resources: about, accessproposals, approvals, apps, changes, channels, comments, drives, and files. Examples include files list, files copy, files download, files export, comments create, drives list, and accessproposals resolve. There is also a helper command, +upload, which uploads a file with automatic metadata.

• Look up and list files and folders, including searching with a query parameter
• Create, copy, download and export files; export is limited to 10 MB of content
• Manage comments and replies on a file
• Create, look up, hide, unhide and update shared drives
• List, get and resolve access proposals (approvers only can list them)
• Upload files with automatic metadata

Install the skill from the ZIP download

Download the ZIP file for the skill from this page and unzip it. The skill is a folder that contains SKILL.md. Put the folder in one of two places depending on how you want to use it.

For a personal install available to your projects, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

Alternatively, if you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills instead of placing files by hand.

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

Set up gws and Google authentication first

The skill cannot work without the gws command-line tool installed and available as the gws binary. The skill also points to a prerequisite skill, gws-shared, which covers auth, global flags and security rules. Read that skill before you start.

If the gws-shared skill file is missing, the source says to run gws generate-skills to create it. You also need a Google account with access to the Drive files you want the agent to touch.

• gws command-line tool (Google Workspace CLI) installed
• Google account authentication configured through gws (see gws-shared)
• Access to Google Drive with the permissions you need

Ask for what you want in plain language

You do not need to type gws commands yourself. Describe the outcome you want and name the file, folder or shared drive. The agent chooses the matching resource and method, such as files list for finding files or comments list for reviewing feedback.

Be specific about what should change. Requests that involve create, update, delete or permission changes are the ones that modify real files, so state exactly what you want done and where.

• Find files: "Find the Q3 budget spreadsheet in my Drive and tell me when it was last modified."
• Copy: "Make a copy of the project proposal doc called Proposal v2 in the same folder."
• Export: "Export the meeting notes doc as a PDF."
• Comments: "List the open comments on the launch plan document."
• Shared drives: "List the shared drives I can access and show their names."
• Access requests: "Show pending access proposals on the handbook file."

Safety notes: scripts and network access

This skill runs scripts and uses the network. Its commands call the Google Drive API through gws, so the agent's requests reach your Google account. Only install it if you trust the source and the gws tool you have set up.

Create, update, delete and permission actions can change or expose real files. Shared or sensitive Drive content deserves extra care. Review what the agent plans to run before approving, and prefer read-only requests (listing, getting, exporting) when you are exploring.

• Use a test folder or shared drive when you are trying the skill for the first time
• Check permission-related requests carefully, since they can expose files
• Be cautious with delete and update requests on shared content
• The skill is not a substitute for reading gws-shared's security rules

Tips for better results

Name the file and its location, because Drive has many similar names. Mention whether you want trashed files included: the files list method returns all files by default, including trashed ones, unless you filter them out with the trashed=false query parameter.

For large or detailed responses, ask for specific fields. Several methods, such as comments list and about get, require the fields parameter to be set, so the agent will need to request the exact fields it needs.

• Include the folder or shared drive name in your request
• Say whether trashed files should be excluded
• Expect the agent to ask for the fields it needs on some methods