google-docs

Google Docs

ドキュメントの作成、編集、コンテンツ管理のために Google Docs を操作します。

インストール

依存関係: pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml markdown-it-py

セットアップの確認

インストール後、スキルが正しく設定されていることを確認します。

$SKILL_DIR/scripts/google-docs.py check

以下を確認します。

• Python の依存関係（google-auth、google-auth-oauthlib、google-api-python-client、keyring、pyyaml、markdown-it-py）
• 認証設定
• Google Docs API への接続

不足しているものがある場合、確認コマンドでセットアップ手順が表示されます。

認証

Google Docs では認証に OAuth 2.0 を使用します。詳しいセットアップ手順については、以下を参照してください。

1. GCP プロジェクトのセットアップガイド - プロジェクトの作成と Docs API の有効化
2. Google OAuth のセットアップガイド - 認証情報の設定

クイックスタート

1. ~/.config/agent-skills/google.yaml を作成します。

   oauth_client:
     client_id: your-client-id.apps.googleusercontent.com
     client_secret: your-client-secret
   

2. $SKILL_DIR/scripts/google-docs.py check を実行して OAuth フローを開始し、セットアップを確認します。

スコープまたは認証エラーが発生した場合は、OAuth トラブルシューティングガイドを参照してください。

コマンド

各コマンドの読み取り／書き込みの分類については、permissions.md を参照してください。

check

設定と接続を確認します。

$SKILL_DIR/scripts/google-docs.py check

以下を検証します。

• Python の依存関係がインストールされていること
• 認証が設定されていること
• Google Docs API に接続できること
• 書き込みアクセスを確認するためのテストドキュメントを作成すること

auth setup

カスタム OAuth フロー用の OAuth 2.0 クライアント認証情報を保存します。

$SKILL_DIR/scripts/google-docs.py auth setup \
  --client-id YOUR_CLIENT_ID \
  --client-secret YOUR_CLIENT_SECRET

認証情報は ~/.config/agent-skills/google-docs.yaml に保存されます。

オプション:

• --client-id - OAuth 2.0 クライアント ID（必須）
• --client-secret - OAuth 2.0 クライアントシークレット（必須）

auth reset

保存されている OAuth トークンを消去します。次に認証が必要なコマンドを実行すると、自動的に再認証が開始されます。

$SKILL_DIR/scripts/google-docs.py auth reset

スコープまたは認証エラーが発生した場合に使用します。

auth status

API 呼び出しを行わずに、現在の OAuth トークン情報を表示します。

$SKILL_DIR/scripts/google-docs.py auth status

次の情報が表示されます。トークンが保存されているかどうか、付与されたスコープ、リフレッシュトークンの有無、トークンの有効期限、クライアント ID。

documents create

新しい空の Google ドキュメントを作成します。

$SKILL_DIR/scripts/google-docs.py documents create --title "My Document"

オプション:

• --title - ドキュメントのタイトル（必須）

例:

# Create a new document
$SKILL_DIR/scripts/google-docs.py documents create --title "Project Notes"

# Output:
# ✓ Document created successfully
#   Title: Project Notes
#   Document ID: 1abc...xyz
#   URL: https://docs.google.com/document/d/1abc...xyz/edit

documents get

ドキュメントのメタデータと構造を取得します。

$SKILL_DIR/scripts/google-docs.py documents get DOCUMENT_ID

引数:

• document_id - Google Docs ドキュメントの ID

例:

# Get document metadata
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

# Output:
# Title: Project Notes
# Document ID: 1abc...xyz
# Characters: 1234
# Revision ID: abc123

documents read

ドキュメントの内容をプレーンテキスト、Markdown、または PDF として読み取ります。

$SKILL_DIR/scripts/google-docs.py documents read DOCUMENT_ID

引数:

• document_id - Google Docs ドキュメントの ID

オプション:

• --format - 出力形式：markdown（デフォルト。表と見出しを保持）または pdf
• --output、-o - 出力ファイルのパス（pdf 形式で使用）

例:

# Read as markdown (default, preserves tables and headings)
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz

# Export as PDF
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz --format pdf --output document.pdf

# Output as markdown:
# # Heading
#
# This is a paragraph.
#
# | Column 1 | Column 2 |
# |----------|----------|
# | Value 1  | Value 2  |

注: Markdown と PDF のエクスポートには、Google のネイティブ Drive API エクスポート機能を使用します。Markdown では、表、見出し、書式、構造が高い精度で保持されます。どちらも drive.readonly スコープが必要です。

ドキュメントのインポート

ローカルの Markdown ファイルを、ネイティブ形式の Google ドキュメントとしてインポートします。Drive API の HTML から Docs への変換を使用し、テーブル、コードブロック、見出し、太字、斜体、リンク、リストを含む Markdown の書式を忠実に再現します。

$SKILL_DIR/scripts/google-docs.py documents import FILE_PATH [--title TITLE] [--document-id DOC_ID] [--folder-id ID]

引数：

• file_path - Markdown ファイルのローカルパス

オプション：

• --title - ドキュメントのタイトル（デフォルト：最初の H1 見出し、またはファイル名）
• --document-id - 更新する既存のドキュメント ID（内容を置き換えます）
• --folder-id - 新しいドキュメントの親フォルダー ID
• --no-format - インポート後の書式設定をスキップします
• --no-images - ローカル画像の埋め込みをスキップします
• --json - JSON 形式で出力します

使用例：

# Import a markdown file as a new Google Doc
$SKILL_DIR/scripts/google-docs.py documents import ./report.md --title "Monthly Report"

# Import using the first H1 heading as the title
$SKILL_DIR/scripts/google-docs.py documents import ./notes.md

# Update an existing document with new markdown content
$SKILL_DIR/scripts/google-docs.py documents import ./updated.md --document-id 1abc...xyz

# Import without post-import formatting
$SKILL_DIR/scripts/google-docs.py documents import ./raw.md --no-format

# Import without embedding images
$SKILL_DIR/scripts/google-docs.py documents import ./doc.md --no-images

画像： Markdown 内のローカル画像参照（![alt text](path/to/image.png)）は、Google ドキュメント内の元の位置に自動的にインラインで埋め込まれます。パスは Markdown ファイルのディレクトリを基準に解決されます。URL ベースの画像（![alt](https://...)）には対応していないため、省略されます。画像処理をスキップするには --no-images を使用します。

フロントマター： YAML フロントマター（--- で区切られた部分）は、インポート前に Markdown から取り除かれます。Google ドキュメントの内容には含まれません。次のフロントマターフィールドに対応しています。

• title — ドキュメントのタイトル（--title フラグで上書きされます）
• folder_id — 親フォルダー ID（--folder-id フラグで上書きされます）
• line_spacing — 行間の割合（デフォルト：115）
• space_below — 段落の下の間隔（pt）（デフォルト：8）
• pageless — ページレスモードにするには true を設定します

---
title: My Document
line_spacing: 130
space_below: 10
---

書式設定後、見出し、段落、リスト項目の数を示す読みやすさの概要が出力されます。

注： markdown-it-py Python ライブラリと drive.file + documents スコープが必要です。

関連項目： Google Drive へのファイルのアップロード（Markdown 以外）、共有、フォルダーへの整理、ドキュメントのエクスポートには、google-drive スキルを使用します。

content append

ドキュメントの末尾にテキストを追加します。

$SKILL_DIR/scripts/google-docs.py content append DOCUMENT_ID --text "Additional content"

引数：

• document_id - Google ドキュメントのドキュメント ID

オプション：

• --text - 追加するテキスト（必須）

使用例：

# Append text
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."

# Output:
# ✓ Text appended successfully

content insert

ドキュメント内の指定した位置にテキストを挿入します。

$SKILL_DIR/scripts/google-docs.py content insert DOCUMENT_ID --text "Insert this" --index 10

引数：

• document_id - Google ドキュメントのドキュメント ID

オプション：

• --text - 挿入するテキスト（必須）
• --index - 挿入位置（0 から始まります。必須）

使用例：

# Insert text at the beginning (index 1, after title)
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz --text "Introduction\n\n" --index 1

# Output:
# ✓ Text inserted successfully

注： インデックス 0 はドキュメントの内容より前です。インデックス 1 は内容の先頭です。

content delete

ドキュメントから指定した範囲の内容を削除します。

$SKILL_DIR/scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50

引数：

• document_id - Google ドキュメントのドキュメント ID

オプション：

• --start-index - 開始位置（含む。必須）
• --end-index - 終了位置（含まない。必須）

使用例：

# Delete characters 10-50
$SKILL_DIR/scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50

# Output:
# ✓ Content deleted successfully

警告： インデックスの指定には注意してください。誤った範囲を削除すると、ドキュメントの構造が壊れる可能性があります。

content insert-after-anchor

ドキュメント内の構造アンカー（水平線、見出し、またはブックマーク）の後に、Markdown 形式の内容を挿入します。テキストの挿入、見出しスタイル、箇条書き、太字の書式設定、リンクを一度の操作で処理します。

$SKILL_DIR/scripts/google-docs.py content insert-after-anchor DOCUMENT_ID \
  --anchor-type ANCHOR_TYPE --markdown "MARKDOWN_CONTENT"

引数：

• document_id - Google ドキュメントのドキュメント ID

オプション：

• --anchor-type - 検索するアンカーの種類：horizontal_rule、heading、または bookmark（必須）
• --anchor-value - アンカー固有の値：見出しテキスト（heading の場合）、ブックマーク ID（bookmark の場合）、または出現番号（horizontal_rule の場合。デフォルトは 1）
• --markdown - 挿入する Markdown 形式の内容（必須）。改行には \n を使用します。

対応する Markdown：

構文	結果
## Heading	見出し（レベル 1〜6）
**text**	太字のテキスト
[text](url)	ハイパーリンク
- item	箇条書き
- item	ネストされた箇条書き（レベルごとにスペース 2 つでインデント）

使用例：

# Insert after the first horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --markdown '## Status Update\n\n**Summary:**\n- Task completed\n  - Sub-task done\n- [Details](https://example.com)'

# Insert after a specific heading
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type heading \
  --anchor-value "Notes" \
  --markdown '- New note item\n- Another item'

# Insert after the second horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor 1abc...xyz \
  --anchor-type horizontal_rule \
  --anchor-value 2 \
  --markdown '## New Section\n\nParagraph text here.'

書式の適用

テキスト範囲に書式を適用します。

$SKILL_DIR/scripts/google-docs.py formatting apply DOCUMENT_ID \
  --start-index 1 --end-index 20 --bold --italic

引数:

• document_id - Google Docs のドキュメント ID

オプション:

• --start-index - 開始位置。範囲に含まれます（必須）
• --end-index - 終了位置。範囲に含まれません（必須）
• --bold - 太字を適用します
• --italic - 斜体を適用します
• --underline - 下線を適用します
• --font-size SIZE - フォントサイズをポイント単位で設定します

例:

# Make title bold and larger
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 1 --end-index 20 --bold --font-size 18

# Apply italic to a section
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 50 --end-index 100 --italic

# Output:
# ✓ Formatting applied successfully

例

ドキュメントを作成して内容を入力する

# Create a new document
$SKILL_DIR/scripts/google-docs.py documents create --title "Weekly Report"

# Add content
$SKILL_DIR/scripts/google-docs.py content append $DOC_ID --text "Weekly Report\n\n"
$SKILL_DIR/scripts/google-docs.py content append $DOC_ID --text "Summary: This week's accomplishments...\n"

# Format the title
$SKILL_DIR/scripts/google-docs.py formatting apply $DOC_ID --start-index 1 --end-index 14 --bold --font-size 18

# Read it back
$SKILL_DIR/scripts/google-docs.py documents read $DOC_ID

内容を読み取って抽出する

# Get document info
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

# Extract plain text
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz > document.txt

# Get document structure
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz

アンカーの後に書式付きの内容を挿入する

# Insert a formatted status update after a horizontal rule
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor $DOC_ID \
  --anchor-type horizontal_rule \
  --markdown '## Weekly Update\n\n**Completed:**\n- Feature implementation\n  - Backend API\n  - Frontend UI\n- [Project board](https://example.com/board)'

既存の内容を編集する

# Insert a new section
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz \
  --text "\n\nNew Section\n" --index 100

# Format the new section header
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
  --start-index 102 --end-index 113 --bold

# Append more content
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz \
  --text "Additional details about the new section..."

エラー処理

認証エラーとスコープエラーは再試行できません。 コマンドで認証エラー、スコープ不足エラー、または権限拒否エラー（終了コード 1）が発生した場合は、停止してユーザーに知らせてください。再試行したり、自律的に問題を解決しようとしたりしないでください。これらのエラーにはユーザーの操作（ブラウザーでの OAuth 同意）が必要です。OAuth トラブルシューティングガイドを案内してください。

再試行可能なエラー: レート制限（HTTP 429）や一時的なサーバーエラー（HTTP 5xx）は、少し待ってから再試行すると解決する場合があります。それ以外のエラーはすべてユーザーに報告してください。

モデルに関するガイダンス

このスキルは、構造化された入出力を必要とする API 呼び出しを行います。標準的な能力を備えたモデルを推奨します。

トラブルシューティング

ドキュメントが見つからない場合

URL から正しいドキュメント ID を使用していることを確認してください。

• URL: https://docs.google.com/document/d/1abc...xyz/edit
• ドキュメント ID: 1abc...xyz

挿入／削除時のインデックスエラー

documents get を使用して、ドキュメントの構造と有効なインデックス範囲を確認してください。以下の点に注意してください。

• インデックス 0 はすべての内容の前です
• インデックス 1 はドキュメント本文の先頭です
• 最後のインデックスはドキュメントの長さです

API リファレンス

高度な使い方については、以下を参照してください。

• Google Docs API ドキュメント
• ドキュメントの構造
• 書式設定のリファレンス