Guide · Agent skill
How to use the Google Keep Notes Manager agent skill (gws-keep)
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the gws-keep agent skill, a set of instructions that teaches an AI agent to work with Google Keep notes through the gws command-line tool. It is written for readers who have not used agent skills before. By the end you will know what the skill lets the agent do, how to install it, how to ask for things in plain language, and what safety points to check before the agent changes or deletes anything.
Google Keep Notes Managergoogleworkspace/cli · Apache-2.0 Download the skill Quick start
- 1Install the gws CLI. Install the gws command-line tool and make sure it is on your path. The skill cannot run without it.
- 2Authenticate gws with Google. Configure Google account authentication for gws as described in the gws-shared SKILL.md file.
- 3Check the shared skill file. Confirm gws-shared/SKILL.md exists. If it is missing, run gws generate-skills to create it.
- 4Download and unzip the skill. Download the ZIP from this page and unzip the gws-keep folder into ~/.claude/skills/ or a project's .claude/skills/ folder.
- 5Or upload the ZIP in the Claude apps. Go to Settings → Capabilities → Skills and upload the ZIP if you use the Claude apps.
- 6Ask for a Keep task. Make a plain-language request such as listing your recent notes, and review the commands the agent proposes.
What the gws-keep skill lets the agent do
An agent skill is a folder containing a SKILL.md file. The file describes a task to an AI agent so the agent knows which commands exist and how to use them. The gws-keep skill covers Google Keep notes and teaches the agent to run gws keep commands.
Once installed, the agent can list notes, fetch a specific note, create a new note, delete a note, and download note attachments. It also explains how to look up the exact parameters each command needs before it runs them.
- List notes, one page of results at a time
- Get a specific note
- Create a new note
- Delete a note (permanent, see safety notes)
- Download a note attachment
Before you install: what the skill needs
The skill only describes commands. It cannot work without the gws command-line tool installed and authenticated with your Google account. The skill's metadata lists gws as a required binary.
The skill also depends on a shared file, gws-shared/SKILL.md, which covers authentication, global flags and security rules. The skill's prerequisite note says that if this file is missing, you should run gws generate-skills to create it.
- The gws command-line tool (googleworkspace CLI)
- Google account authentication configured for gws
- The gws-shared SKILL.md file present (create it with gws generate-skills if missing)
Install the gws-keep skill
Download the ZIP from this page and unzip it. You can install the skill in one of two places.
For personal use across projects, unzip the skill folder into ~/.claude/skills/. To limit it to a single project, unzip it into that project's .claude/skills/ folder.
Alternatively, upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Trigger the skill with natural requests
You do not need to type a command yourself. Ask the agent in plain language about your Google Keep notes, and it can use the skill to choose and run the right gws keep command.
Be specific about the note or the outcome you want. If you are not sure which parameters a command needs, ask the agent to check first. The skill tells the agent to inspect a method before calling it.
- "List my most recent Google Keep notes."
- "Get the note with this ID and summarise it."
- "Create a Keep note titled Groceries with milk, eggs and bread."
- "Download the attachment from this note."
How the agent looks up the right command
Before calling any API method, the skill directs the agent to browse resources and methods, then inspect the method's required parameters, types and defaults. The agent uses that output to build its --params and --json flags.
You can run the same discovery commands yourself to check what the agent will do.
# Browse resources and methods
gws keep --help
# Inspect a method's required params, types, and defaults
gws schema keep.<resource>.<method>Understand the notes list and paging
The list method returns results in pages. The page_size value sets the upper bound on items returned, and a value of zero lets the server choose. If more notes remain, the response includes a next_page_token value.
To get the next page, the agent copies next_page_token into the next request's page_token. The source notes that page tokens are opaque, so they should be passed through as given rather than edited.
Safety notes: deletion, network and scripts
Deletion is permanent. Deleting a note removes the resource immediately and cannot be undone. Only the note's OWNER can delete it, and collaborators will lose access. Check the agent's plan before it deletes anything.
The skill runs scripts and uses the network, because the gws tool calls Google's services. Review the commands the agent proposes, and only run it with an account and data you are comfortable exposing to that tool.
The skill file does not describe editing existing notes, so do not expect the agent to modify them.
- Deletion cannot be undone and removes access for collaborators
- Only the OWNER role can delete a note
- The skill runs scripts and uses the network
- Editing existing notes is not described in the skill
What people use it for
- List recent notes so an agent can summarise a to-do list
- Fetch a specific note by ID for reference while working on a task
- Create a new note from a request, such as a shopping list
- Download a note's attachment through the gws tool
- Build an automation that reads or writes Google Keep data through gws
Frequently asked questions
How do I install the gws-keep agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.
What do I need before the gws-keep skill works?
You need the gws command-line tool installed and authenticated with your Google account. The skill also relies on the gws-shared SKILL.md file, which you can create with gws generate-skills if it is missing.
Is the gws-keep skill free?
The skill is licensed under Apache-2.0. This page does not state any price, so check the repository for licence terms and any costs of the gws tool itself.
Can the agent delete my Google Keep notes?
The skill includes a delete command, but deletion is permanent and cannot be undone. Only the note's OWNER can delete it, and collaborators lose access, so review the agent's plan before approving a delete.
What can the gws-keep skill not do?
The skill file does not describe editing existing notes. It covers listing, getting, creating, deleting notes and downloading attachments. It also cannot work without the gws tool.
How is this different from using the gws command directly?
The skill gives the agent instructions so it can choose and run gws keep commands from a plain-language request. You can still run the same commands yourself, and the skill points to gws keep --help and gws schema for checking parameters.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use gws-keep if you already have the gws CLI authenticated and want an agent to list, fetch, create or download Google Keep notes, or to build automations on top of them. Pick something else if you have not set up gws, need to edit existing notes, or want an agent to manage deletions without close supervision.
Download the skill