gws-drive

Overview of gws-drive skill

What gws-drive does

gws-drive is the Google Drive skill for the Google Workspace CLI. It helps you manage files, folders, shared drives, and related Drive API workflows from the command line, with the skill-specific guidance needed to avoid guessing at resource names, required fields, and permission constraints.

Who should use it

Use the gws-drive skill if you work in Backend Development, automation, or ops and need repeatable Drive actions in scripts or agent workflows. It is most useful when you want a CLI-backed process for Drive tasks instead of a one-off prompt, especially for uploads, metadata-aware operations, and API-driven queries.

What matters before install

The main value of gws-drive is not breadth, but reliability: it points the agent toward the right Drive resources and the right request shape. The biggest adoption blocker is auth and shared setup, because the skill depends on the broader gws environment and on the shared gws-shared instructions for flags and security rules.

How to Use gws-drive skill

Install and prerequisite check

Install the gws-drive skill in the Google Workspace CLI context, then confirm the shared prerequisite first: ../gws-shared/SKILL.md. The skill metadata also expects the gws binary to be available, so verify the CLI works before trying a Drive workflow. A practical install path is to read gws drive --help after setup and compare it with the skill’s resource list.

Start from the right input shape

The gws-drive usage pattern is gws drive <resource> <method> [flags], so your prompt should name the target resource, the action, and the exact output constraints. Strong input looks like this: “List shared drives I can access, return only name and id, and exclude trash.” Weak input looks like: “Check Drive.” If you are using the gws-drive guide for Backend Development, include identifiers, parent folders, and any permission or scope assumptions up front.

Read these files first

Start with SKILL.md, then inspect ../gws-shared/SKILL.md because it governs authentication, global flags, and security behavior. In this repo slice, there are no helper scripts or support folders to lean on, so the skill file itself is the primary source of truth. Pay special attention to the API resource sections and the helper command +upload, since they show the intended workflow instead of forcing you to infer it from generic Drive docs.

Workflow that produces better results

Use a three-step flow: define the resource, narrow the method, then add only the flags that affect the API response. For example, a request to fetch Drive account info should mention that the about.get call requires fields, while upload-related work should route through the helper command when you want automatic metadata. This is the main gws-drive usage discipline: ask for the smallest useful response, not the broadest possible one.

gws-drive skill FAQ

Is gws-drive only for Drive basics?

No. gws-drive covers core Drive resources plus specific API behaviors that matter in automation, such as about.get requiring fields and access proposal handling with approver-only constraints. That makes it more suitable than a plain prompt when your task depends on correct API shape rather than just a general Drive explanation.

When should I not use this skill?

Skip the gws-drive skill if you only need a manual, one-off Drive tip or if you do not have the gws CLI and shared auth setup ready. It is also a poor fit when your task is outside Drive operations entirely, because the skill is optimized for request construction and CLI execution, not general Workspace advice.

Is it beginner-friendly?

Yes, if you can describe a concrete Drive goal. The skill reduces guesswork by showing the resource-method pattern and the key caveats, but beginners still need to provide a target file, folder, shared drive, or permission scenario. Without that, the agent may produce a vague command or choose an overly broad API call.

What is the biggest difference from a normal prompt?

A normal prompt may explain Drive concepts; gws-drive gives you a workflow anchored in the actual CLI and API resources. That matters when you need a deterministic command, a valid field selection, or a permission-aware operation that should not fail on first execution.

How to Improve gws-drive skill

Give the agent exact Drive context

The best results come from naming the resource, action, and scope in one sentence. Example: “Use gws-drive to list files in folder abc123, return id, name, mimeType, and modifiedTime, and do not include trashed items.” This is much stronger than asking to “find documents,” because it reduces search ambiguity and avoids unnecessary API output.

State constraints that change the API call

Mention whether you need shared drives, a specific folder, an access proposal, or account-level info. For gws-drive, those details matter because different resources have different permissions and response requirements. If you omit them, the first output often fails on missing fields, missing approver access, or an overbroad query.

Iterate from command to result

If the first output is too broad, tighten the request by removing optional output and adding the exact identifiers you care about. If it fails, check whether the issue is auth, missing prerequisites from gws-shared, or a mismatched resource-method pair. The fastest gws-drive guide workflow is to correct the command shape before changing the task itself.