核心用法
md-to-gdoc 是一个专注于 Markdown 到 Google Docs 格式转换的自动化工具技能。其核心工作流程遵循两步确定性策略：首先创建一个空白的 Google Doc，随后通过 gog docs update --format=markdown 命令将 Markdown 内容注入并自动应用 Google Docs 原生格式。
用户通过命令行调用脚本 scripts/md-to-gdoc.sh，传入 Markdown 文件路径及可选参数（标题、目标文件夹ID、指定Google账户）。技能严格依赖 gog（Google Workspace CLI）进行身份验证和API操作，同时借助 python3 完成JSON解析。关键约束在于必须使用 update --format=markdown 路径，而非 write 或 create --file，这是唯一能正确通过API应用Google Docs标题样式的官方途径。
显著优点
格式保真度高：能够完整转换六级标题层级（Heading 1-6）、粗体、行内代码、代码块、引用、列表、超链接，甚至Markdown表格也能转为原生Google Docs表格。
流程可靠性：采用"先创建空文档再更新内容"的两步策略，避免了直接创建带内容文档时常见的格式丢失问题，输出结果具有确定性。
身份验证灵活：支持多Google账户管理，可通过 --account 指定或回退到默认账户，适应团队协作场景。
错误预警机制：当检测到Markdown缺少 # 标题标记时主动发出警告，帮助用户提前修正源文件。
潜在缺点与局限性
依赖外部CLI生态：核心功能完全绑定 gog 工具，需用户提前完成 gog auth add <email> 认证流程，增加了环境配置门槛。
格式渲染瑕疵：斜体（*italic*）因gog CLI的inline解析器缺陷可能无法渲染；无序/有序列表仅使用文本前缀符号（•、1.）而非Google Docs原生列表对象，丧失部分交互特性；水平线被降级为40个连字符的文本模拟。
无自动标题修复：虽然会警告缺失#标记的标题，但不会自动为"看起来像标题的纯文本"添加标记，仍需人工预处理。
适合的目标群体
- 技术写作团队：需要将Git仓库中的Markdown文档（如README、技术规范）同步到Google Workspace进行协作审阅
- 学术研究人员：整理Markdown笔记后转换为符合机构格式要求的Google Docs提交材料
- 产品经理与运营：将Markdown形式的需求文档、PRD快速转换为可评论、可共享的协作文档
- 开发者工具链用户：已在工作流中集成
gogCLI，追求命令行自动化而非手动复制粘贴
常规使用风险
认证过期风险：gog 的OAuth令牌可能过期，表现为"Empty doc created"或授权错误，需定期执行 gog auth list 检查并重新 auth add。
API依赖风险：功能完全依赖Google Docs API的update端点，若Google调整API行为或 gog 版本滞后，可能导致格式映射失效。
路径解析风险：脚本路径 scripts/md-to-gdoc.sh 要求相对此skill目录解析，在复杂目录结构或符号链接环境下可能触发路径错误。
Python环境风险：JSON解析依赖系统 python3，在精简容器环境或Python版本冲突场景下可能执行失败。