google-docs by odyssey4me/agent-skills
npx skills add https://github.com/odyssey4me/agent-skills --skill google-docs与 Google Docs 交互,实现文档创建、编辑和内容管理。
依赖项:pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml markdown
安装后,验证技能是否配置正确:
$SKILL_DIR/scripts/google-docs.py check
这将检查:
如果缺少任何内容,检查命令将提供设置说明。
Google Docs 使用 OAuth 2.0 进行身份验证。完整的设置说明请参阅:
创建 ~/.config/agent-skills/google.yaml:
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
oauth_client:
client_id: your-client-id.apps.googleusercontent.com
client_secret: your-client-secret
运行 $SKILL_DIR/scripts/google-docs.py check 以触发 OAuth 流程并验证设置。
出现作用域或身份验证错误时,请参阅 OAuth 故障排除指南。
有关每个命令的读/写分类,请参阅 permissions.md。
验证配置和连接性。
$SKILL_DIR/scripts/google-docs.py check
此命令验证:
存储 OAuth 2.0 客户端凭据,用于自定义 OAuth 流程。
$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 客户端密钥(必需)清除存储的 OAuth 令牌。下一个需要身份验证的命令将自动触发重新身份验证。
$SKILL_DIR/scripts/google-docs.py auth reset
当您遇到作用域或身份验证错误时使用此命令。
显示当前的 OAuth 令牌信息,无需进行 API 调用。
$SKILL_DIR/scripts/google-docs.py auth status
显示:是否存储了令牌、授予的作用域、刷新令牌是否存在、令牌过期时间以及客户端 ID。
创建一个新的空白 Google 文档。
$SKILL_DIR/scripts/google-docs.py documents create --title "My Document"
选项:
--title - 文档标题(必需)示例:
# 创建一个新文档
$SKILL_DIR/scripts/google-docs.py documents create --title "Project Notes"
# 输出:
# ✓ 文档创建成功
# 标题:Project Notes
# 文档 ID:1abc...xyz
# URL:https://docs.google.com/document/d/1abc...xyz/edit
获取文档元数据和结构。
$SKILL_DIR/scripts/google-docs.py documents get DOCUMENT_ID
参数:
document_id - Google Docs 文档 ID示例:
# 获取文档元数据
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz
# 输出:
# 标题:Project Notes
# 文档 ID:1abc...xyz
# 字符数:1234
# 修订 ID:abc123
以纯文本、markdown 或 PDF 格式读取文档内容。
$SKILL_DIR/scripts/google-docs.py documents read DOCUMENT_ID
参数:
document_id - Google Docs 文档 ID选项:
--format - 输出格式:markdown(默认,保留表格和标题)或 pdf--output, -o - 输出文件路径(与 pdf 格式一起使用)示例:
# 以 markdown 格式读取(默认,保留表格和标题)
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz
# 导出为 PDF
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz --format pdf --output document.pdf
# 以 markdown 格式输出:
# # 标题
#
# 这是一个段落。
#
# | 列 1 | 列 2 |
# |----------|----------|
# | 值 1 | 值 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--json - 以 JSON 格式输出示例:
# 将 markdown 文件作为新的 Google 文档导入
$SKILL_DIR/scripts/google-docs.py documents import ./report.md --title "Monthly Report"
# 使用第一个 H1 标题作为标题导入
$SKILL_DIR/scripts/google-docs.py documents import ./notes.md
# 使用新的 markdown 内容更新现有文档
$SKILL_DIR/scripts/google-docs.py documents import ./updated.md --document-id 1abc...xyz
注意: 需要 markdown Python 库(pip install --user markdown)和 drive.file 作用域。
将文本追加到文档末尾。
$SKILL_DIR/scripts/google-docs.py content append DOCUMENT_ID --text "Additional content"
参数:
document_id - Google Docs 文档 ID选项:
--text - 要追加的文本(必需)示例:
# 追加文本
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."
# 输出:
# ✓ 文本追加成功
在文档的特定位置插入文本。
$SKILL_DIR/scripts/google-docs.py content insert DOCUMENT_ID --text "Insert this" --index 10
参数:
document_id - Google Docs 文档 ID选项:
--text - 要插入的文本(必需)--index - 要插入的位置,从 0 开始计数(必需)示例:
# 在开头插入文本(索引 1,标题之后)
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz --text "Introduction\n\n" --index 1
# 输出:
# ✓ 文本插入成功
注意: 索引 0 在文档内容之前。索引 1 在内容开头。
从文档中删除一段内容。
$SKILL_DIR/scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50
参数:
document_id - Google Docs 文档 ID选项:
--start-index - 起始位置,包含(必需)--end-index - 结束位置,不包含(必需)示例:
# 删除字符 10-50
$SKILL_DIR/scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50
# 输出:
# ✓ 内容删除成功
警告: 使用索引时要小心。删除错误的范围可能会损坏文档结构。
在文档中的结构锚点(水平线、标题或书签)之后插入 markdown 格式的内容。在单个操作中处理文本插入、标题样式、项目符号列表、粗体格式和链接。
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor DOCUMENT_ID \
--anchor-type ANCHOR_TYPE --markdown "MARKDOWN_CONTENT"
参数:
document_id - Google Docs 文档 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 个空格) |
示例:
# 在第一条水平线之后插入
$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)'
# 在特定标题之后插入
$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'
# 在第二条水平线之后插入
$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 - 设置字体大小(以磅为单位)示例:
# 使标题加粗并变大
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
--start-index 1 --end-index 20 --bold --font-size 18
# 对某个部分应用斜体
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
--start-index 50 --end-index 100 --italic
# 输出:
# ✓ 格式应用成功
# 创建一个新文档
$SKILL_DIR/scripts/google-docs.py documents create --title "Weekly Report"
# 添加内容
$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"
# 格式化标题
$SKILL_DIR/scripts/google-docs.py formatting apply $DOC_ID --start-index 1 --end-index 14 --bold --font-size 18
# 读回内容
$SKILL_DIR/scripts/google-docs.py documents read $DOC_ID
# 获取文档信息
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz
# 提取纯文本
$SKILL_DIR/scripts/google-docs.py documents read 1abc...xyz > document.txt
# 获取文档结构
$SKILL_DIR/scripts/google-docs.py documents get 1abc...xyz
# 在水平线后插入格式化的状态更新
$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)'
# 插入一个新部分
$SKILL_DIR/scripts/google-docs.py content insert 1abc...xyz \
--text "\n\nNew Section\n" --index 100
# 格式化新部分标题
$SKILL_DIR/scripts/google-docs.py formatting apply 1abc...xyz \
--start-index 102 --end-index 113 --bold
# 追加更多内容
$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:
https://docs.google.com/document/d/1abc...xyz/edit1abc...xyz使用 documents get 查看文档结构和有效的索引范围。请记住:
有关高级用法,请参阅:
每周安装次数
131
仓库
GitHub Stars
2
首次出现
2026年1月27日
安全审计
安装于
opencode119
cursor115
gemini-cli114
codex113
github-copilot110
amp104
Interact with Google Docs for document creation, editing, and content management.
Dependencies : pip install --user google-auth google-auth-oauthlib google-api-python-client keyring pyyaml markdown
After installation, verify the skill is properly configured:
$SKILL_DIR/scripts/google-docs.py check
This will check:
If anything is missing, the check command will provide setup instructions.
Google Docs uses OAuth 2.0 for authentication. For complete setup instructions, see:
Create ~/.config/agent-skills/google.yaml:
oauth_client:
client_id: your-client-id.apps.googleusercontent.com
client_secret: your-client-secret
Run $SKILL_DIR/scripts/google-docs.py check to trigger OAuth flow and verify setup.
On scope or authentication errors, see the OAuth troubleshooting guide.
See permissions.md for read/write classification of each command.
Verify configuration and connectivity.
$SKILL_DIR/scripts/google-docs.py check
This validates:
Store OAuth 2.0 client credentials for custom OAuth flow.
$SKILL_DIR/scripts/google-docs.py auth setup \
--client-id YOUR_CLIENT_ID \
--client-secret YOUR_CLIENT_SECRET
Credentials are saved to ~/.config/agent-skills/google-docs.yaml.
Options:
--client-id - OAuth 2.0 client ID (required)--client-secret - OAuth 2.0 client secret (required)Clear stored OAuth token. The next command that needs authentication will trigger re-authentication automatically.
$SKILL_DIR/scripts/google-docs.py auth reset
Use this when you encounter scope or authentication errors.
Show current OAuth token information without making API calls.
$SKILL_DIR/scripts/google-docs.py auth status
Displays: whether a token is stored, granted scopes, refresh token presence, token expiry, and client ID.
Create a new blank Google Doc.
$SKILL_DIR/scripts/google-docs.py documents create --title "My Document"
Options:
--title - Document title (required)Example:
# 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
Get document metadata and structure.
$SKILL_DIR/scripts/google-docs.py documents get DOCUMENT_ID
Arguments:
document_id - The Google Docs document IDExample:
# 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
Read document content as plain text, markdown, or PDF.
$SKILL_DIR/scripts/google-docs.py documents read DOCUMENT_ID
Arguments:
document_id - The Google Docs document IDOptions:
--format - Output format: markdown (default, preserves tables and headings) or pdf--output, -o - Output file path (used with pdf format)Example:
# 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 |
Note: Markdown and PDF export use Google's native Drive API export. Markdown preserves tables, headings, formatting, and structure with high fidelity. Both require the drive.readonly scope.
Import a local markdown file as a natively formatted Google Doc. Uses Drive API HTML-to-Docs conversion for full markdown fidelity including tables, code blocks, headings, bold, italic, links, and lists.
$SKILL_DIR/scripts/google-docs.py documents import FILE_PATH [--title TITLE] [--document-id DOC_ID] [--folder-id ID]
Arguments:
file_path - Local path to a markdown fileOptions:
--title - Document title (default: first H1 heading, or filename)--document-id - Existing document ID to update (replaces content)--folder-id - Parent folder ID for new documents--json - Output as JSONExamples:
# 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
Note: Requires the markdown Python library (pip install --user markdown) and the drive.file scope.
Append text to the end of a document.
$SKILL_DIR/scripts/google-docs.py content append DOCUMENT_ID --text "Additional content"
Arguments:
document_id - The Google Docs document IDOptions:
--text - Text to append (required)Example:
# Append text
$SKILL_DIR/scripts/google-docs.py content append 1abc...xyz --text "Meeting notes from today..."
# Output:
# ✓ Text appended successfully
Insert text at a specific position in the document.
$SKILL_DIR/scripts/google-docs.py content insert DOCUMENT_ID --text "Insert this" --index 10
Arguments:
document_id - The Google Docs document IDOptions:
--text - Text to insert (required)--index - Position to insert at, 0-based (required)Example:
# 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
Note: Index 0 is before the document content. Index 1 is at the beginning of content.
Delete a range of content from the document.
$SKILL_DIR/scripts/google-docs.py content delete DOCUMENT_ID --start-index 10 --end-index 50
Arguments:
document_id - The Google Docs document IDOptions:
--start-index - Start position, inclusive (required)--end-index - End position, exclusive (required)Example:
# Delete characters 10-50
$SKILL_DIR/scripts/google-docs.py content delete 1abc...xyz --start-index 10 --end-index 50
# Output:
# ✓ Content deleted successfully
Warning: Be careful with indices. Deleting the wrong range can corrupt document structure.
Insert markdown-formatted content after a structural anchor (horizontal rule, heading, or bookmark) in a document. Handles text insertion, heading styles, bullet lists, bold formatting, and links in a single operation.
$SKILL_DIR/scripts/google-docs.py content insert-after-anchor DOCUMENT_ID \
--anchor-type ANCHOR_TYPE --markdown "MARKDOWN_CONTENT"
Arguments:
document_id - The Google Docs document IDOptions:
--anchor-type - Type of anchor to find: horizontal_rule, heading, or bookmark (required)--anchor-value - Anchor-specific value: heading text (for heading), bookmark ID (for bookmark), or occurrence number (for horizontal_rule, default 1)--markdown - Markdown-formatted content to insert (required). Use \n for newlines.Supported markdown:
| Syntax | Result |
|---|---|
## Heading | Heading (levels 1-6) |
**text** | Bold text |
[text](url) | Hyperlink |
- item | Bullet list |
- item | Nested bullet (indent 2 spaces per level) |
Examples:
# 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.'
Apply text formatting to a range of text.
$SKILL_DIR/scripts/google-docs.py formatting apply DOCUMENT_ID \
--start-index 1 --end-index 20 --bold --italic
Arguments:
document_id - The Google Docs document IDOptions:
--start-index - Start position, inclusive (required)--end-index - End position, exclusive (required)--bold - Apply bold formatting--italic - Apply italic formatting--underline - Apply underline formatting--font-size SIZE - Set font size in pointsExample:
# 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..."
Authentication and scope errors are not retryable. If a command fails with an authentication error, insufficient scope error, or permission denied error (exit code 1), stop and inform the user. Do not retry or attempt to fix the issue autonomously — these errors require user interaction (browser-based OAuth consent). Point the user to the OAuth troubleshooting guide.
Retryable errors : Rate limiting (HTTP 429) and temporary server errors (HTTP 5xx) may succeed on retry after a brief wait. All other errors should be reported to the user.
This skill makes API calls requiring structured input/output. A standard-capability model is recommended.
Make sure you're using the correct document ID from the URL:
https://docs.google.com/document/d/1abc...xyz/edit1abc...xyzUse documents get to see the document structure and valid index ranges. Remember:
For advanced usage, see:
Weekly Installs
131
Repository
GitHub Stars
2
First Seen
Jan 27, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykFail
Installed on
opencode119
cursor115
gemini-cli114
codex113
github-copilot110
amp104
Skills CLI 使用指南:AI Agent 技能包管理器安装与管理教程
44,900 周安装