agentleFS
TechNickAITechNickAI/hermes-skills/skills/productivity/google-docs/SKILL.md

google-docs

Skill0 starsChanged 3 months agoMITView on GitHub

Use this skill when the requested artifact is a Google Doc, especially when the source material is agent-generated Markdown and the user cares about formatting. The tested best default is Drive import of Markdown as a native Google Doc: 1. Write clean Markdown locally. 2. Upload it to Drive with source MIME text/markdown and target MIME application/vnd.google-apps.document. 3. Verify by exporting the created Doc back to text/markdown or text/plain. This outperformed the older pandoc -> docx -> Google Doc path…

  • Reads credentials
  • Installs packages

17 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use google-chat, google-calendar and 4 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • antoniolgSkill

    google-chat

    Read Google Chat spaces/threads via the Chat API, create/refresh OAuth tokens, parse Gmail Chat URLs, and list spaces. Use when asked to look up or verify messages in Google Chat or when you need API access to Chat from the CLI.

    Also in 3 projects that use this

  • younghaiSkill

    google-calendar

    Google Calendar 일정 조회, 검색, 등록. "일정", "스케줄", "캘린더" 등을 언급하면 자동 실행. Daily Note 작성, Weekly Review에 사용.

    Also in 7 projects that use this

  • refly-aiSkill

    gmail

    Integrate with Gmail for email management and automation. Use when you need to: (1) send and compose emails with attachments, (2) read and search emails by criteria, (3) manage drafts and email labels, or (4) reply to email threads and conversations.

    Also in 5 projects that use this

  • OpenAISkill

    linear

    Manage issues, projects & team workflows in Linear. Use when the user wants to read, create or updates tickets in Linear.

    Also in 4 projects that use this

  • AnthropicSkill

    slack

    Also in 3 projects that use this

  • ElasticSkill

    create-skill

    Interactively create a new Claude Code skill and add it to the elastic-docs-skills catalog. Use when the user wants to generate a new skill, scaffold a slash command, or build automation for docs tasks.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

29 rules. 0 are common, 19 are distinctive, and 10 are very specific to this project.

  • 0

    Common

    Most of the 16 edited versions we read keep these.

  • 19

    Distinctive

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use this skill when the requested artifact is a Google Doc, especially when the source material is agent-generated Markdown and the user …

    line 22
  2. Distinctive:

    Write clean Markdown locally.

    line 27
  3. Very specific:

    Verify by exporting the created Doc back to text/markdown or text/plain.

    line 30
  4. Very specific:

    pandoc: only if you use the docx path below (brew install pandoc on macOS).

    line 42
  5. Very specific:

    Do not use this for Sheets or Slides.

    line 64
  6. Distinctive:

    Use Drive convert-on-upload with Markdown:

    line 71
  7. Distinctive:

    No extra Python packages.

    line 88
  8. Very specific:

    If gog docs write --help exists on the machine, prefer newer gog for editing an existing Doc:

    line 95
  9. Very specific:

    Use pandoc -> docx -> Google Doc only when the source document needs Word-specific features or the Markdown import path fails:

    line 112
  10. Distinctive:

    Use the browser only for:

    line 125
  11. Distinctive:

    Do not use the browser as the primary document creation backend.

    line 131
  12. Distinctive:

    Write the source Markdown like a real source document, not like chat output.

    line 136
  13. Distinctive:

    Use H2/H3 for structure.

    line 139
  14. Distinctive:

    Use normal Markdown tables for tabular content.

    line 140
  15. Distinctive:

    Use fenced code blocks with language tags.

    line 141
  16. Distinctive:

    Use Markdown links, not bare URLs when the link text matters.

    line 142
  17. Distinctive:

    Avoid clever HTML unless you have verified Google import preserves it.

    line 143
  18. Distinctive:

    Keep long prose paragraphs readable.

    line 144
  19. Distinctive:

    After creation, verify the Doc is native and formatting survived:

    line 171
  20. Distinctive:

    If exact visual polish matters, open the link in the browser and inspect the first page, heading hierarchy, tables, and code blocks.

    line 185
  21. Distinctive:

    Prefer a two-step pattern:

    line 190
  22. Distinctive:

    Do not rewrite a human-edited Doc wholesale unless the user explicitly asks.

    line 202
  23. Very specific:

    share sends a real, externally-visible grant: Treat it like sending an email: confirm the recipient and role with the user first, and …

    line 216
  24. Distinctive:

    If the user explicitly asks "create a Google Doc", that is approval to create the new Drive file.

    line 225
  25. Very specific:

    Ask before sharing, deleting, moving, or overwriting existing Docs.

    line 227
  26. Distinctive:

    Ask before making broad edits to an existing human-owned Doc unless the requested edit is exact and scoped.

    line 229
  27. Very specific:

    Prefer reversible actions: create/copy/export before destructive edits.

    line 231
  28. Very specific:

    Credential lookup fails (missing_credentials): If the helper can't find gog's token, pass credentials explicitly: export gog's refresh …

    line 252
  29. Very specific:

    If you accidentally uploaded a raw file (used --as raw), meta will show a non-Google MIME type.

    line 263

“Common” is measured: kept by at least 6 in 10 of the 16 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Google Docs

Overview

Use this skill when the requested artifact is a Google Doc, especially when the source material is agent-generated Markdown and the user cares about formatting.

The tested best default is Drive import of Markdown as a native Google Doc:

  1. Write clean Markdown locally.
  2. Upload it to Drive with source MIME text/markdown and target MIME application/vnd.google-apps.document.
  3. Verify by exporting the created Doc back to text/markdown or text/plain.

This outperformed the older pandoc -> docx -> Google Doc path in testing: direct Markdown import preserved headings, bold, italic, links, native tables, inline code, and fenced code blocks more faithfully.

Prerequisites

  • gog CLI (steipete/gogcli) installed and authorized: run gog auth login once in the operating-system user's real $HOME. The bundled scripts/gworkspace.py reuses gog's stored OAuth refresh token, so no separate Google Cloud setup is needed.
  • python3 on PATH (the helper is stdlib-only — no pip install required).
  • pandoc only if you use the docx path below (brew install pandoc on macOS).
  • The helper resolves credentials in this order: explicit --refresh-token-file / --client-secret-file, then GOOGLE_REFRESH_TOKEN / GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET env vars, then gog's stored token. If lookup fails it exits with {"error": "missing_credentials"} — see Common Pitfalls for the manual escape hatch.

Run commands from the skill directory so scripts/gworkspace.py resolves relative to $PWD, or use the full path skills/google-docs/scripts/gworkspace.py from the repo root.

$HOME shadowing: some agent runtimes rewrite $HOME to a sandbox path where gog's auth doesn't exist. If credential lookup fails in that environment, point HOME at the real OS user home before invoking the helper.

When to Use

  • User asks for a Google Doc, report, memo, proposal, brief, agenda, or notes document.
  • User gives Markdown and wants it turned into a formatted Google Doc.
  • User asks whether to use gog, raw API, or browser for Docs.
  • User asks to export, inspect, copy, or verify a Google Doc.

Do not use this for Sheets or Slides; load google-sheets or google-slides instead.

Decision Tree

Best default for new docs from Markdown

Use Drive convert-on-upload with Markdown:

python3 scripts/gworkspace.py upload report.md \
  --as doc \
  --name "Quarterly Report" \
  --parent FOLDER_ID

FOLDER_ID is optional; omit --parent to create in My Drive root. To target a specific folder, copy the ID from its Drive URL (https://drive.google.com/drive/folders/<FOLDER_ID>), list folders with gog drive ls --json, or create one with python3 scripts/gworkspace.py mkdir "Reports".

Why this is the default:

  • No extra Python packages.
  • Reuses existing gog OAuth refresh token.
  • Produces a native Google Doc, not an uploaded .md or .docx file.
  • Preserves Markdown formatting well, including code fences and tables.

When to use newer gog directly

If gog docs write --help exists on the machine, prefer newer gog for editing an existing Doc:

# This path requires a newer gog with docs editing commands.
gog docs write --help >/dev/null 2>&1 || { echo "gog docs write not available; use Drive import instead"; exit 1; }
gog docs create "Draft Title" --parent FOLDER_ID --json
gog docs write DOC_ID --markdown --text "$(cat report.md)" --append --json

Newer upstream gog versions include Docs editing primitives such as docs write --markdown, docs format, docs insert-table, and raw Docs inspection. Local v0.9.0 did not expose these commands during the one occasion test, so do not assume they exist. Check help first.

When to use pandoc/docx

Use pandoc -> docx -> Google Doc only when the source document needs Word-specific features or the Markdown import path fails:

pandoc report.md -o report.docx
python3 scripts/gworkspace.py upload report.docx --as doc --name "Quarterly Report"

This path preserved headings, lists, tables, links, and basic text styling in testing, but degraded fenced code blocks compared with direct Markdown import.

When to use browser automation

Use the browser only for:

  • visual QA after API creation,
  • final manual polish that APIs cannot express quickly,
  • one-off "File -> Save as Google Docs" conversion if API conversion is unavailable.

Do not use the browser as the primary document creation backend. It is slower, less repeatable, and more fragile than Drive import or Docs API calls.

Markdown Authoring Rules

Write the source Markdown like a real source document, not like chat output.

  • One H1 title at the top.
  • Use H2/H3 for structure.
  • Use normal Markdown tables for tabular content.
  • Use fenced code blocks with language tags.
  • Use Markdown links, not bare URLs when the link text matters.
  • Avoid clever HTML unless you have verified Google import preserves it.
  • Keep long prose paragraphs readable; Google Docs import handles normal paragraphs well.

Good source (outer fence shown with ~~~ so the inner ``` code block renders correctly):

# Quarterly Business Review

## Executive Summary

Revenue increased **18%** quarter-over-quarter.

## Metrics

| Metric |    Q1 |    Q2 |
| ------ | ----: | ----: |
| MRR    | $420k | $496k |

```python
def churn_rate(lost, start):
    return round(lost / start * 100, 2)
```

Verification

After creation, verify the Doc is native and formatting survived:

python3 scripts/gworkspace.py meta DOC_ID
python3 scripts/gworkspace.py export DOC_ID --mime text/markdown --out /tmp/doc-roundtrip.md

Check that:

  • mimeType is application/vnd.google-apps.document.
  • Round-trip Markdown still contains headings, tables, links, inline code, and fenced code blocks.
  • The returned webViewLink opens as a Google Docs URL.

If exact visual polish matters, open the link in the browser and inspect the first page, heading hierarchy, tables, and code blocks.

Editing Existing Docs

Prefer a two-step pattern:

  1. Export or inspect the existing doc.
  2. Apply a targeted edit with the highest-level tool available.

Options in order:

  1. Newer gog docs write/format/find-replace if present.
  2. Raw Docs API documents.batchUpdate for precise paragraph/text/table/image operations.
  3. Browser for visual/manual edits only when the API path is too expensive for the task.

Do not rewrite a human-edited Doc wholesale unless the user explicitly asks. Export first, preserve structure, then apply a minimal diff.

Sharing and Drive Helpers

The bundled helper also exposes Drive operations the skills reference:

python3 scripts/gworkspace.py mkdir "Reports"                 # create a folder, returns its ID
python3 scripts/gworkspace.py meta DOC_ID                     # metadata + webViewLink
python3 scripts/gworkspace.py token                           # mint an access token for raw Docs API calls
python3 scripts/gworkspace.py share DOC_ID --email a@b.com --role reader   # share — IRREVERSIBLE

share sends a real, externally-visible grant. Treat it like sending an email: confirm the recipient and role with the user first, and never share without explicit approval. --notify additionally emails the recipient.

For raw Docs API work (documents.batchUpdate), mint a token with gworkspace.py token and call the REST endpoint directly.

Safety and Approval

  • If the user explicitly asks "create a Google Doc", that is approval to create the new Drive file.
  • Ask before sharing, deleting, moving, or overwriting existing Docs. share is irreversible — confirm recipient + role first.
  • Ask before making broad edits to an existing human-owned Doc unless the requested edit is exact and scoped.
  • Prefer reversible actions: create/copy/export before destructive edits.

Common Pitfalls

  1. Using old local gog Docs commands for formatting. Local gog v0.9.0 created title-only Docs and did not support docs write --markdown during testing. Check gog docs --help before relying on editing commands.
  2. Uploading Markdown without conversion. gog drive upload report.md creates a Drive file containing Markdown, not a native Google Doc. Use Drive API target MIME application/vnd.google-apps.document, or a newer gog conversion flag if available.
  3. Wrong source MIME. Markdown import needs source MIME text/markdown; guessing as plain text can fail or degrade formatting.
  4. Assuming docx is better. In testing, direct Markdown import preserved code fences and inline code better than pandoc -> docx -> Google Doc.
  5. Skipping verification. A successful upload is not enough. Confirm native Google Doc MIME type and round-trip export.
  6. Credential lookup fails (missing_credentials). If the helper can't find gog's token, pass credentials explicitly: export gog's refresh token to a 0600 file with gog auth tokens export <account> --output /tmp/tok.json --force, then run the helper with --refresh-token-file /tmp/tok.json --client-secret-file <gog credentials.json>. The helper refuses credential files that are group/world-readable or not owned by you — chmod 600 them. These flags work before or after the subcommand. For a gog named client or a non-default gog home, use --gog-client <name> / --gog-home <dir> (or the GOG_CLIENT / GOG_HOME env vars).
  7. export returns 403. Drive's export endpoint only works on Google-native files. If you accidentally uploaded a raw file (used --as raw), meta will show a non-Google MIME type; re-upload with the correct --as target.

One-Shot Recipe

mkdir -p /tmp/gdoc-build
cat > /tmp/gdoc-build/report.md <<'MD'
# Report Title

## Summary

Write the report here.
MD
python3 scripts/gworkspace.py upload /tmp/gdoc-build/report.md --as doc --name "Report Title"

Return the resulting webViewLink to the user.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.