google-docs-reader

Google Docs Reader

Read and locate Google Docs via the official Google API. A bundled script handles authentication, dependency setup, and converting Google's nested JSON into whatever format the task needs.

When to reach for this

Use it whenever you need the actual content of a Google Doc — to summarize it, answer questions about it, extract data, quote it, or feed it into other work. A docs.google.com/document/d/... URL or a bare document ID is the strongest signal. If the user names a doc but gives no link ("read my design doc 'Project Atlas'"), use search first to find its ID, then read it.

This skill is only for Google Docs. For .docx, PDFs, or Sheets, use the dedicated docx / pdf / xlsx skills instead.

Locating the script

The helper lives at skills/google-docs-reader/scripts/gdocs.py within the plugin. When installed, its absolute path is ${CLAUDE_PLUGIN_ROOT}/skills/google-docs-reader/scripts/gdocs.py — prefer that env var so the path is correct regardless of where the user's session is rooted. Define a shorthand once per session:

GDOCS="$CLAUDE_PLUGIN_ROOT/skills/google-docs-reader/scripts/gdocs.py"

The script self-installs its Python dependencies into an isolated environment the first time it runs, so you don't need to pip install anything.

Quick start

# Read a doc as markdown (default — best for reasoning and summarizing)
python3 "$GDOCS" read "https://docs.google.com/document/d/DOC_ID/edit"

# Plain text (no formatting markers)
python3 "$GDOCS" read DOC_ID --format text

# Structured JSON (title + raw Docs API document; for programmatic use)
python3 "$GDOCS" read DOC_ID --format json

# Include comments alongside the content
python3 "$GDOCS" read DOC_ID --include-comments

# Find a doc by name, then read the id it returns
python3 "$GDOCS" search "Project Atlas"

# List recently modified docs / get metadata
python3 "$GDOCS" recent --max 20
python3 "$GDOCS" metadata DOC_ID

Always pass the doc URL or ID exactly as the user gave it — the script extracts the ID itself.

Choosing an output format

Pick the format from what the task actually needs — that's why --format is flexible rather than fixed:

• md (default) — preserves headings, lists, tables, links, bold/italic. Best when summarizing, quoting, or when structure carries meaning.
• text — flat text, no markup. Best when you only need raw wording and formatting would be noise.
• json — full Docs API document plus title. Use when you need exact structure/styling or want to process elements programmatically.

When unsure, start with md.

Authentication — the one thing the user must do

Reading requires the user to be signed in. The script auto-detects credentials, but the first time on a machine the user must run a one-time login. Login opens a browser for Google consent, so it has to be the human — don't try to complete it yourself. Crucially, the user runs it in their own terminal, where $CLAUDE_PLUGIN_ROOT is NOT set (it only exists inside your runtime). Give them the explicit installed path instead:

python3 ~/.claude/plugins/marketplaces/ai-agent-skills/skills/google-docs-reader/scripts/gdocs.py login

(If that path doesn't exist, find it with find ~/.claude/plugins -name gdocs.py.) After they approve in the browser, the token is cached and every command works without prompting.

If a command prints an auth error, no credentials are set up yet. Relay the script's message: the user needs an OAuth client file dropped into ~/.config/google-docs-reader/ (the script auto-detects credentials.json or Google's raw client_secret*.json — no rename needed), then to run the login command above. Full setup is in references/setup.md — point the user there rather than improvising, then continue once they confirm login succeeded.

Note: your own read/search/etc. calls (via $GDOCS above) work fine once the user has logged in — the cached token lives in ~/.config/google-docs-reader/ and is shared across both invocation paths.

Handling common errors

• "No Google credentials available" — user hasn't set up creds. Have them drop the shared OAuth client file into ~/.config/google-docs-reader/ and run login (see references/setup.md).
• Python venv module isn't available — one-time system install: sudo apt install -y python3-venv python3-pip, then re-run.
• 404 / "not found or not shared" — the signed-in account can't access that doc; ask the owner to share it.
• 403 / access denied — the Docs/Drive APIs aren't enabled on the project, or the account lacks access. See references/setup.md.
• Search returns nothing — name contains matches substrings of the title only (case-insensitive). Try a shorter distinctive fragment, or use recent.

Notes

• The script uses read-only scopes — it cannot modify or delete docs. Keep it that way; this skill is for reading.
• Credentials and the cached token live in ~/.config/google-docs-reader/, outside the plugin, so they survive plugin updates and never leak into git.
• Very large docs produce a lot of text. If you only need part, read as text and search within it, or read json and target specific sections.