How to use the gog Google Workspace agent skill

What the gog skill lets your agent do

An agent skill is a folder of instructions that an AI agent loads when a task matches it. The gog skill's instructions tell the agent how to run the gog command-line tool against your Google account. The skill's own description is a Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets and Docs.

• Gmail: search mail, send plain or HTML messages, create drafts, send drafts and reply to messages
• Calendar: list events, create events (with colours) and update events, and show the available colour IDs
• Drive: search files
• Contacts: list contacts
• Sheets: read, update, append, clear and inspect spreadsheets, with JSON output available
• Docs: export a document to a text file or print its contents

Install the gog tool and the skill

The skill needs the gog command-line tool on your machine. The skill's metadata lists a Homebrew install using the formula steipete/tap/gogcli, which provides the gog binary. The skill itself is a SKILL.md file, so you install it as a folder containing that file.

To install the skill, download the skill ZIP from this page and unzip it into ~/.claude/skills/ for your user account, or into a project's .claude/skills/ folder to limit it to that project. Alternatively, in the Claude apps go to Settings, then Capabilities, then Skills, and upload the skill there.

• Install gog with Homebrew: brew install steipete/tap/gogcli
• Unzip the skill so that the gog folder containing SKILL.md sits in ~/.claude/skills/ or .claude/skills/
• Or upload the skill under Settings → Capabilities → Skills in the Claude apps

Set up Google access once with OAuth

gog needs OAuth access to your Google account. You supply your own Google credentials file, called client_secret.json, which comes from your Google Cloud project. The skill's setup is a one-time process: point gog at the credentials file, add your account with the services you want, then check the list of authorised accounts.

Your account must be authorised for Gmail, Calendar, Drive, Contacts, Docs and Sheets for the commands to work. Replace the example paths and addresses with your own.

• Add your credentials file: gog auth credentials /path/to/client_secret.json
• Add your account with services: gog auth add you@gmail.com --services gmail,calendar,drive,contacts,docs,sheets
• Check what is set up: gog auth list
• Optional: set GOG_ACCOUNT=you@gmail.com so you do not need to repeat --account

Ask for things in plain language

Once the skill is installed and set up, you do not need to type gog commands yourself. Describe the task and the agent chooses the right command. The skill is most useful when your request names the service and gives enough detail to act on, such as a time range, a recipient or a sheet name.

Examples of requests that match the skill:

• Find emails from the last week that mention an invoice, and list the senders
• Draft a reply to the email from Sam about the budget and show it to me before sending
• Put a 45-minute review on my calendar on Thursday afternoon, coloured blue
• Read the Sales tab of my budget spreadsheet and summarise the totals
• Export my meeting notes doc as plain text
• Find the Drive file named Q3 plan

Common commands the agent uses

These are the main commands from the skill. You can run them yourself to test your setup or to understand what the agent is doing. Calendar IDs, event IDs, message IDs, draft IDs and sheet IDs come from earlier results or from your Google account.

• Search Gmail threads: gog gmail search 'newer_than:7d' --max 10
• Search individual emails: gog gmail messages search 'in:inbox from:example.com' --max 20
• Create a draft: gog gmail drafts create --to a@b.com --subject 'Hi' --body-file ./message.txt
• Send a draft: gog gmail drafts send <draftId>
• Search Drive: gog drive search 'query' --max 10
• Read sheet values as JSON: gog sheets get <sheetId> 'Tab!A1:D10' --json
• Export a doc to text: gog docs export <docId> --format txt --out /tmp/doc.txt

Format email and calendar colours correctly

For multi-paragraph email, the skill prefers plain text sent with --body-file, which also works for drafts and replies. The --body flag does not turn \n into line breaks, so use a file or stdin for multi-line text. Use --body-html only when you need rich formatting.

For calendar colours, run gog calendar colors to see the event colour IDs from 1 to 11, then pass one with --event-color. The skill lists these IDs: 1 is #a4bdfc, 2 is #7ae7bf, 3 is #dbadff, 4 is #ff887c, 5 is #fbd75b, 6 is #ffb878, 7 is #46d6db, 8 is #e1e1e1, 9 is #5484ed, 10 is #51b749 and 11 is #dc2127.

• Multi-line plain text: --body-file ./message.txt or --body-file - for stdin
• Rich formatting: --body-html with tags such as <p>, <br>, <strong>, <a href> and <ul>/<li>
• Replies: add --reply-to-message-id <msgId>
• Colours: gog calendar create <calendarId> --summary 'Title' --from <iso> --to <iso> --event-color 7

Safety, permissions and limits

This skill runs scripts and uses the network, because it calls gog, which talks to Google's services using your credentials. The skill's instructions tell the agent to confirm with you before sending mail or creating events. Review drafts before sending, and do not point this skill at shared or sensitive mailboxes where a mistake would matter.

The skill does not edit the contents of existing Google Docs in place. Its notes say Docs supports export, cat and copy, and in-place edits need a Docs API client, which is not part of gog.

• Keep client_secret.json private and only grant access to accounts you own
• Ask the agent to create drafts first, then send them after you check them
• For scripts, the skill recommends --json together with --no-input
• gog gmail search returns one row per thread; use gog gmail messages search to get each email separately