# gogcli-skills

Claude Code skills for **gog** — the script-friendly Google CLI ([gogcli.sh](https://gogcli.sh/))
for Gmail, Calendar, Drive, Docs, Sheets, and more. One focused skill per Google
service, so Claude can act on your behalf with safe defaults and stable JSON.

## What this is

`gog` is a command-line tool that talks to Google Workspace APIs (Gmail,
Calendar, Drive, Docs, Sheets, Slides, and ~20 others) with predictable `--json`
output, explicit account selection, and built-in safety controls.

A **Claude skill** is a small instruction file that teaches Claude Code when and
how to use a tool. This bundle provides **22 skills** — one per service — each
describing that service's common reads/writes, the safety rules to follow, and
how to discover exact flags. When you ask Claude something like *"summarise my
unread email from this week,"* Claude picks the `gog-gmail` skill, runs the right
`gog` command, and reads back the JSON.

> **New to this?** Three things work together: **Claude Code** (the assistant),
> the **`gog` CLI** (the tool that calls Google), and **these skills** (the glue).
> The installer sets up `gog` and the skills for you — then you just talk to
> Claude in plain English.

Works on **macOS, Linux, and Windows**.

## Install

Download the package for your OS from **`releases.glbxai.com`**, extract it, and
run the bundled installer. It installs the `gog` CLI (if missing) and links the
22 skills into your per-user Claude skills directory.

**Linux**
```bash
curl -fsSLO https://releases.glbxai.com/gogcli-skills/latest/gogcli-skills_latest_linux.tar.gz
tar -xzf gogcli-skills_latest_linux.tar.gz
cd gogcli-skills
./install-linux.sh
```

**macOS**
```bash
curl -fsSLO https://releases.glbxai.com/gogcli-skills/latest/gogcli-skills_latest_macos.tar.gz
tar -xzf gogcli-skills_latest_macos.tar.gz
cd gogcli-skills
./install-macos.sh
```

**Windows (PowerShell)**
```powershell
irm https://releases.glbxai.com/gogcli-skills/latest/gogcli-skills_latest_windows.zip -OutFile gogcli-skills.zip
Expand-Archive gogcli-skills.zip -DestinationPath .
cd gogcli-skills
.\install.ps1
```

Then **start (or restart) Claude Code** so it loads the skills. Verify:
```bash
gog --version
```

The installer flags: `--force` / `-Force` reinstalls `gog`; `--skills-only` /
`-SkillsOnly` or `--gog-only` / `-GogOnly` runs just one half. On Windows the
skill links use directory junctions (no admin / Developer Mode); if PowerShell
blocks the script, run `powershell -ExecutionPolicy Bypass -File .\install.ps1`.

Verify a download against the published checksums:
```bash
curl -fsSL https://releases.glbxai.com/gogcli-skills/latest/checksums.txt
```

## Authorize a Google account

`gog` needs a Google account authorized once (interactive, browser consent).
Create a Google Cloud project, enable the APIs you need, create a Desktop OAuth
client, then:
```bash
gog auth credentials set <path-to-client_secret.json>
gog auth add you@gmail.com --services gmail,calendar,drive,docs,sheets,contacts
gog auth doctor --check
```
Full walkthrough and command reference: [gogcli.sh](https://gogcli.sh/).

## How to use

Just ask Claude in plain language. The skill's description is the trigger, so
naming the service or the task is enough:

- *"Search my Gmail for invoices newer than 30 days and list the senders."* → `gog-gmail`
- *"What's on my calendar tomorrow?"* → `gog-calendar`
- *"Audit which Drive files are shared publicly."* → `gog-drive`
- *"Append this section to the 'Notes' tab of that Google Doc."* → `gog-docs`
- *"Pull the GA4 active-users report for May."* → `gog-analytics`

Behaviour baked into every skill:

- **Reads return JSON** (`--json`), with fetched content marked untrusted and
  Gmail bodies sanitized — safe for Claude to parse.
- **Account is explicit.** Claude passes `--account you@example.com`, or set a
  default: `export GOG_ACCOUNT=you@example.com`.
- **Writes are cautious.** Claude prefers `--dry-run` first; destructive commands
  require `--force` and Claude only adds it for the exact change you asked for.
- **Sending is opt-in.** Gmail send and Chat messages only go out when you ask.
- **Secrets stay hidden.** Skills never print tokens, OAuth secrets, or keyring passwords.

### The 22 skills

| Skill | Service | Notes |
| --- | --- | --- |
| `gog-auth` | Auth & credentials | Check/fix accounts, keyring, tokens. Start here when auth is broken. |
| `gog-gmail` | Gmail | Search, read, labels, drafts; send is opt-in. |
| `gog-calendar` | Calendar | Events, free/busy, conflicts, RSVP. |
| `gog-drive` | Drive | Files, sharing, **read-only sharing audits**. |
| `gog-docs` | Docs | Read/write by tab and UTF-16 range. |
| `gog-sheets` | Sheets | Ranges, batch-update, formatting. |
| `gog-slides` | Slides | Read, export, build from markdown/template. |
| `gog-forms` | Forms | Structure, responses, questions. |
| `gog-meet` | Meet | Spaces, participants, history. |
| `gog-contacts` | Contacts | List/search, directory, create/dedupe. |
| `gog-people` | People | Read-only profile/identity lookups. |
| `gog-tasks` | Tasks | To-dos and task lists. |
| `gog-classroom` | Classroom | Courses, coursework, rosters, grading. |
| `gog-appscript` | Apps Script | Read projects; **run** executes real code. |
| `gog-analytics` | Analytics (GA4) | Read-only reports. |
| `gog-searchconsole` | Search Console | Search analytics, sitemaps. |
| `gog-sites` | Sites | Read-only site lookups. |
| `gog-photos` | Photos | App-created media only. |
| `gog-chat` | Chat | Read; sending posts real messages. |
| `gog-admin` | Workspace Admin | **Workspace-only**, domain-wide delegation. |
| `gog-groups` | Groups | Read-oriented; admin changes via `gog-admin`. |
| `gog-keep` | Keep | **Workspace-only**, needs a service account. |

## Updating

Re-download the latest package from `releases.glbxai.com` and re-run the
installer (`--force` to also refresh `gog`):
```bash
curl -fsSLO https://releases.glbxai.com/gogcli-skills/latest/gogcli-skills_latest_linux.tar.gz
tar -xzf gogcli-skills_latest_linux.tar.gz && cd gogcli-skills && ./install-linux.sh --force
```

## Troubleshooting

**Claude doesn't use a `gog` skill / the skills don't appear.**
Re-run the installer, then **restart Claude Code** (skills are discovered at
startup). On Windows the per-user skills directory is `%USERPROFILE%\.claude\skills`;
on macOS/Linux it's `~/.claude/skills`.

**`gog: command not found`.**
Re-run the installer (or just its gog half: `./install-linux.sh --gog-only`,
`./install-macos.sh --gog-only`, `.\install.ps1 -GogOnly`) and make sure its
install dir is on your `PATH`. If the release fallback was used, `~/.local/bin`
(Linux/macOS) must be on `PATH`; the installer prints the exact line to add.

**`accessNotConfigured` from Google.**
The API isn't enabled in the Cloud project that owns your OAuth client. Enable it
in that project and retry after propagation.

**Auth / keyring errors (e.g. `keyring.password`), especially headless.**
Run `gog auth doctor --check --no-input`. In services/containers, the process
that launches `gog` must have `GOG_KEYRING_BACKEND=file`, `GOG_KEYRING_PASSWORD`,
and `HOME` set — verify the *service* environment, not just your login shell.

**"Which account?" / wrong account.**
Pass `--account you@example.com` or set `export GOG_ACCOUNT=you@example.com`.
List what's authorized: `gog auth list --check --json --no-input`.

**Gmail/Chat send seems blocked.**
That's the safe default — sending is gated unless you explicitly ask to send.

**A flag in a skill doesn't exist / "unknown flag".**
`gog`'s flags evolve. The skills defer to the live CLI: check
`gog <service> <command> --help` or `gog schema <service> <command> --json`.

**Claude keeps asking permission to run `gog`.**
Allow it in Claude Code settings (e.g. add a `Bash(gog:*)` permission), or
approve "don't ask again" when prompted.

## Credits

These skills wrap the **gog** CLI ([gogcli.sh](https://gogcli.sh/)). `gog`, its
command surface, and its safety model are its own; this bundle just packages
Claude skills around it.
