AgentSkillsCN

gdocs-sync

将Markdown文件同步至Google Docs，并保持稳定的URL。适用于以下场景： - 用户说“同步至Google Docs”“推送到gdocs”“更新Google Doc” - 用户希望将Markdown文件以永久的Google Docs URL提供访问 - 在生成了需要通过Google Docs访问的上下文文件或报告之后 - 用户希望从Markdown文件“创建Google Doc” 首次运行时会创建新的Google Docs，后续运行时则更新同一份文档。 文档ID会与源文件一同存储在JSON文件中，因此URL永远不会改变。

SKILL.md
--- frontmatter
name: gdocs-sync
description: |
  Sync Markdown files to Google Docs, preserving a stable URL. Use when:
  - User says "sync to Google Docs", "push to gdocs", "update the Google Doc"
  - User wants a Markdown file available at a permanent Google Docs URL
  - After generating a context file or report that should be accessible via Google Docs
  - User asks to "create a Google Doc" from a Markdown file

  Creates new Google Docs on first run, updates the same document on subsequent runs.
  The document ID is stored in a JSON file alongside the source, so the URL never changes.

Google Docs Sync

Sync Markdown files to Google Docs with stable URLs. Creates on first run, updates on subsequent runs.

Prerequisites

First-time setup (one-time only):

bash
python3 ~/.config/google-docs/gdocs_auth.py

This opens a browser to authorise Google Docs access. See SETUP.md for details.

Usage

Basic Sync

bash
python3 ~/.config/google-docs/gdocs_sync.py \
    "<markdown_file>" \
    "<doc_id_file>" \
    --title "<Document Title>"

Arguments:

  • •markdown_file — Path to the Markdown source
  • •doc_id_file — JSON file to store the Google Doc ID (create alongside the markdown file)
  • •--title — Title for new documents (ignored on updates)

Example: Project Context File

bash
python3 ~/.config/google-docs/gdocs_sync.py \
    "/path/to/project/summary/context.md" \
    "/path/to/project/summary/gdocs_id.json" \
    --title "Project Context"

First run: Creates Google Doc, saves ID to gdocs_id.json, outputs URL. Subsequent runs: Updates same document, URL unchanged.

Workflow Integration

When creating consolidated context files for projects:

  1. •Generate the Markdown context file
  2. •Sync to Google Docs
  3. •Store the URL in the project README
  4. •On future updates, regenerate context file and re-run sync

Output

The script outputs:

  • •Status message (creating vs updating)
  • •The permanent Google Doc URL

Example:

code
Updating existing document: 1w5mHT-E0qLXYcyYfet8g3UswhVd9AQ41yo-bs_XZavk
✅ Document updated
📄 URL: https://docs.google.com/document/d/1w5mHT-E0qLXYcyYfet8g3UswhVd9AQ41yo-bs_XZavk/edit

Troubleshooting

"No token found" — Run python3 ~/.config/google-docs/gdocs_auth.py

"Document not found" — The doc was deleted. Script will create a new one and update the ID file.

Formatting issues — The script converts basic Markdown (headers, bullets, tables). Complex formatting may simplify.