How to use the Google Tasks CLI agent skill (gws-tasks)

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

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific job. The agent reads these instructions when a request matches them. The gws-tasks skill covers the Google Tasks API resources, so the agent knows how to use the gws tool to work with Google Tasks.

Once installed, the agent can view and manage task lists, add or change tasks, move tasks under parent tasks, and clear completed items. The skill only documents commands. It does not give the agent access to your Google account by itself.

• Task lists: list, get, insert, update, patch and delete lists.
• Tasks: list, get, insert, update, patch, delete, move and clear.
• Before calling any method, the agent looks up exact parameters with gws help and schema commands instead of guessing.

What you need before installing the gws-tasks skill

The skill depends on three things. Without them the agent cannot run any Google Tasks commands.

The gws command-line tool must be installed. The skill lists gws as a required binary. Your Google account must be authenticated through gws. The skill also relies on a shared skill called gws-shared, which holds the sign-in, global flag and security rules. If that file is missing, the skill says to run gws generate-skills to create it.

• gws command-line tool (googleworkspace CLI)
• A Google account authenticated through gws
• The gws-shared SKILL.md (create it with gws generate-skills if missing)

How do you install the gws-tasks skill?

Download the ZIP file from this page. It contains SKILL.md. Unzip it so the folder sits in one of the locations below. For a personal setup, use ~/.claude/skills/. For a single project, put it in the project's .claude/skills/ folder.

You can also upload the skill in the Claude apps. Open Settings, go to Capabilities, then choose Skills and upload the skill there.

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

How do you trigger the skill with a natural request?

You do not need to type commands yourself. Ask the agent for what you want in ordinary language, and mention Google Tasks so the agent knows which tool to use. The agent will decide when the skill applies and will check the command syntax before running anything.

Good requests name the task list, the task and the change you want. If you are unsure of a list name, ask the agent to list your task lists first.

• "Show me all my Google Tasks lists."
• "Add 'renew passport' to my Errands list due Friday."
• "Move 'buy stamps' under 'Post office trip' in my Errands list."
• "Clear the completed items from my Work list."

How does the agent find the right command?

The skill tells the agent to inspect the API before calling it. It can browse resources and methods with the help command, then check the exact parameters for one method with the schema command. The agent uses that output to build its --params and --json flags.

You can run the same checks yourself to see what the agent will see.

What safety rules should you know about?

This skill runs scripts and uses the network, because it calls the gws tool, which talks to Google's services. Read the gws-shared rules before use. Some methods remove data. The delete and clear methods remove tasks. Deleting a task list or an assigned task also removes the original item in Docs or Chat Spaces. Deleting an assigned task only is done by unassigning it from the assignment surface instead.

Ask the agent to show you what it plans to delete, and confirm before it runs any delete or clear request.

• tasks clear marks completed tasks as hidden, so they are no longer returned by default when listing.
• tasks delete on an assigned task also deletes the original in Docs or Chat Spaces.
• tasklists delete also deletes assigned tasks and their originals.
• To remove only the assignment, unassign the task from Docs or Chat Spaces.

Tips for getting reliable results

Keep requests specific. Name the list and task exactly as they appear in Google Tasks. Ask for a preview before any change, especially for moves and deletions. If a command fails, ask the agent to check the schema for that method and try again with the listed parameters.

Note the limits in the source: a user can have up to 2,000 task lists, up to 20,000 non-hidden tasks per list, up to 100,000 tasks in total, and up to 2,000 subtasks per task. Tasks assigned from Docs or Chat Spaces cannot be created through the Tasks API; they must be assigned from those apps.

• Use exact list and task names.
• Ask for a preview before moves, clears and deletes.
• Check the limits if you manage very large lists.