How to use the Google People Contacts agent skill (gws-people)

What is an agent skill, and what does gws-people let the agent do?

An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. When the skill is installed and your request matches its description, the agent reads the file and follows it.

Once gws-people is installed, the agent can work with your Google Contacts through the gws CLI. According to the skill, it can list and search your contacts and contact groups, look up people in your organisation's domain directory, and create, edit or delete contacts and their photos. It can also copy an "Other contact" into your main contacts group, which is useful for contacts Google created automatically from past interactions.

Install the gws-people skill

Download the skill ZIP from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of these locations:

Your personal skills folder, ~/.claude/skills/, so it is available in all your projects. Or a project's .claude/skills/ folder, so it applies only to that project.

You can also upload the ZIP in the Claude apps under Settings → Capabilities → Skills.

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

Set up the gws tool and Google authentication first

The skill cannot work without the gws command-line tool. It must be installed and on your PATH, and Google authentication must be configured for gws. The skill points to a shared skill file, ../gws-shared/SKILL.md, for login steps, global flags and security rules. Read that file before your first use.

If the shared file is missing, the skill says to run gws generate-skills to create it. Your Google account also needs access to Contacts and the People API.

• gws (Google Workspace CLI) installed and on the PATH
• Google authentication configured for gws, as described in gws-shared SKILL.md
• A Google account with Contacts/People API access

Ask for contact tasks in plain language

You do not need to type gws commands yourself. Describe the outcome you want, such as finding a contact, listing a group or updating a phone number. The agent should pick the matching gws people command.

Under the hood, commands follow the pattern gws people <resource> <method> [flags]. Resources include contactGroups, otherContacts and people. Methods include list, get, search, create and update. If you want to see what is available, the skill suggests running gws people --help to browse resources and methods, and gws schema people.<resource>.<method> to see a method's required parameters.

• Search: "Find everyone in my contacts whose email is at example.com"
• Read: "List my contact groups"
• Create or edit: "Add a new contact for Sam Lee with this phone number"
• Delete: "Remove the photo from this contact"

Common tasks and what the skill is designed for

The skill documents several specific behaviours that affect results. Searching your grouped contacts works on names, nicknames, email addresses, phone numbers and organisations. Searching Other contacts works on names, email addresses and phone numbers. Before searching either, the skill says the agent should send a warmup request with an empty query to update the cache.

For the company directory, the skill can search domain profiles and domain contacts. Directory syncs may show a propagation delay of several minutes after a write, so they are not meant for checking a change you have just made.

Mutating requests (create, update, delete) should be sent one at a time for the same user, because parallel writes can slow down and fail. Creating a contact group with a name that already exists returns an HTTP 409 error.

• Warm up the search cache with an empty query before searching
• Directory results can lag by several minutes after a change
• Duplicate contact group names return HTTP 409
• updateContact only changes contact data and replaces the fields in the update mask

Safety notes: scripts and network access

The skill runs scripts and uses the network. Every create, update and delete call changes real data in your Google account. The skill does not say these changes can be undone, so do not assume they can.

Before bulk edits, deduplication or deletions, ask the agent to list the affected contacts first and confirm the list. Check the shared gws-shared SKILL.md for global flags and security rules. Keep the authentication you configured for gws limited to the account you intend to manage.

• Ask the agent to show a list of affected contacts before any write
• Review the security rules in gws-shared SKILL.md before first use
• Remember that deleting a photo or contact is a real change to your account