gws-people Skill: Search and Manage Google Contacts

Lets your coding assistant search, create and update Google Contacts and look up people in your directory with the gws tool.

Installs: 33.3K; on skills.sh
Stars: 32K; on GitHub
Updated: Oct 2026; last repo commit

gws-people teaches your assistant to use gws people, the Google People part of the gws tool. It covers your contacts, contact groups, "other contacts" that Google saved from your emails, and your organization's directory. It can read, create, update and delete.

You need the gws command line tool and a Google sign-in. The skill is a list of API resources and methods, so the assistant uses gws schema to look up each call before it makes it.

Good for

Google Workspace users who want to look up colleagues and contacts from the terminal
People who bulk-create or update contacts
Developers who explore the Google People API with an assistant

Install gws-people

Claude Code

Copy this prompt.

Install the gws-people skill in Claude Code. Run this command:

npm install -g @googleworkspace/cli

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 18+.

Do steps 1 to 3 in order. The skill only gives your assistant instructions. The gws tool does the work, and it needs a Google sign-in. gws auth setup needs the gcloud CLI to create a Google Cloud project for you; without gcloud, use the manual setup in the README. The README also lists a GitHub Releases download, Homebrew and cargo as other ways to get gws.

From the project README. Source.

What's in the skill

When it loads

Google People: Manage contacts and profiles.

Sections in SKILL.md

API Resources
contactGroups
otherContacts
people
Discovering Commands

Key facts

Author: googleworkspace org (the README says it is not an officially supported Google product)
Repo: googleworkspace/cli
Installs on skills.sh: 33,303 as of 2026-11-02
GitHub stars: 32,038 for the whole googleworkspace/cli repo, 2026-11-02
License: Apache-2.0 (README)
Last commit to the repo: 2026-10-30
What is inside: 1 file (SKILL.md). It points to the separate gws-shared skill.
Needs: The gws command line tool (Node.js 18+ for the npm route), a Google account and a Google Cloud project for sign-in
Also installs: gws-shared, which the skill tells the assistant to read first for sign-in, flags and safety rules
skills.sh audits: Gen Agent Trust Hub pass, Socket pass, Snyk pass (2026-11-02)

What it includes

Gets, searches, creates and updates people and contacts
Includes get, getBatchGet, searchContacts, searchDirectoryPeople, listDirectoryPeople, createContact, updateContact, batchCreateContacts, batchUpdateContacts and contact photo updates. Use people/me for yourself. Mutations for the same user should be sent one at a time.
Try: “Search my contacts for Dana and show her email and phone.”
Write · people
Deletes a contact's photo
The one delete method listed under people.
Delete · people.deleteContactPhoto
Lists, creates, renames and deletes contact groups
Includes batchGet, create, delete, get, list and update, plus a members resource. Group names must be unique, and list does not fill in the members.
Try: “Create a contact group called Conference 2026.”
Delete · contactGroups
Lists and searches contacts Google saved automatically
These are contacts outside any group, usually created from your interactions. copyOtherContactToMyContactsGroup turns one into a real contact. The search method needs a warmup request with an empty query first.
Write · otherContacts
Lists the people you are connected to
Listed as a resource in the SKILL.md.
Network · people.connections
Browses methods and shows their parameters
The skill tells the assistant to inspect a method before it calls it, then build the --params and --json flags from the schema.
Read · gws people --help and gws schema

From the official docs

Permissions

Medium risk

This skill can read, change and delete your Google Contacts and read your company directory. Approve each write yourself and search narrowly.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It can edit and delete contact data
The skill lists create, update and batch update methods, contact group deletes and contact photo deletes. Approve each write and check what it will change. github.com
Contact details go to your AI provider
Names, emails and phone numbers the assistant reads become part of your chat with it. Search narrowly instead of listing the whole directory. github.com
Setup installs a global npm package
The npm route downloads the gws binary from GitHub Releases. The README also says to expect breaking changes before v1.0, so pin what you rely on. github.com
You need a Google Cloud project to sign in
gws uses OAuth credentials from your own Google Cloud project. If the consent screen is unverified, Google caps the scopes you can pick, so choose individual services with gws auth login -s. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only mode. Choose --dry-run to preview a call, and sign in with only the services you need.
Talks to	Google Workspace APIs, called by the gws tool. Anything the assistant reads from your account goes to your AI provider as part of the chat
Sign-in and keys	gws encrypts saved credentials (AES-256-GCM) with a key in your OS keyring, or in ~/.config/gws/.encryption_key when the file backend is chosen.
Scopes	Whatever Google permissions you approve when you run gws auth login

Questions

What does gws-people do?

It makes your assistant manage Google Contacts through gws people. It can search your contacts and your company directory, create and update contacts, and work with contact groups.

How do I install gws-people?

Use the install box at the top of this page and run all three steps. The skill does nothing without the gws tool and a Google sign-in. The skills command also adds gws-shared, which the skill tells the assistant to read first.

Does it need a Google Cloud project or an API key?

It needs a Google Cloud project, because gws signs in with OAuth credentials from one, according to the README. gws auth setup can create it if you have the gcloud CLI. Without gcloud, follow the README's manual setup.

Can it delete or change my contacts?

Yes. It can create and update contacts, delete a contact photo, and delete contact groups. Approve each write yourself, and use --dry-run to preview a call.

Is gws-people safe to use?

It reads names, emails and phone numbers and can change them, so review each command before you approve it. The shared rules tell the assistant to confirm write and delete commands first. Contact details it reads go to your AI provider.

Can I use it in the Claude app or Claude.ai?

The README does not document that. The skill tells the assistant to run gws shell commands, so it fits an assistant that can run commands on a machine where gws is installed and signed in, such as Claude Code or Codex.

Why does a contact search return nothing?

The SKILL.md says the search methods need a warmup request with an empty query to update the cache before the first real search. Ask the assistant to send that first.

Information

updated Nov 2, 2026

Repository: googleworkspace/cli
Folder: skills/gws-people

googleworkspace/cli skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 4

googleworkspace/cli README · github.com
gws-people SKILL.md · github.com
skills CLI commands · github.com
gws-shared SKILL.md · github.com