{"skill":{"slug":"google-docs-formatter","displayName":"Google Docs Formatter","summary":"Instruction-only workflow for formatting, editing, and creating Google Docs using the existing gog skill/CLI. Use when a user asks to format a Google Doc, co...","description":"---\nname: google-docs-formatter\ndescription: Instruction-only workflow for formatting, editing, and creating Google Docs using the existing gog skill/CLI. Use when a user asks to format a Google Doc, convert Markdown into a Google Doc, update sections, preserve structure, or fix Google Docs formatting. Relies on gog for all Google Docs/Drive API operations; contains no scripts or direct API clients.\n---\n\n# Google Docs Formatter\n\nUse this skill to format or update Google Docs through the existing `gog` skill/CLI. This skill is instruction-only: do not introduce new API clients, scripts, dependencies, or credential flows.\n\n## Core rule\n\nRely on `gog` for all Google Docs and Drive operations. If the gog skill is not loaded and command details are needed, load the `gog` skill first.\n\nPrefer Google Docs-native workflows over DOCX conversion. Avoid third-party proxy services unless the user explicitly requests them.\n\n## Safety and approval\n\nBefore any write operation, state the target document and intended change, then get explicit user approval unless the user has already clearly approved that exact change.\n\nAlways ask before:\n- `gog docs clear`\n- replacing the full document body\n- large multi-section replacements\n- deleting text ranges\n- changing a shared/work document whose ownership or audience is unclear\n\nSafe to do without extra approval when already working on the user-approved doc:\n- inspect metadata/structure\n- export/read content\n- prepare Markdown locally\n- run dry-run style checks if supported\n\n## Standard workflow\n\n1. Identify the target doc.\n   - Accept a Google Docs URL or document ID.\n   - Extract the ID from URLs like `https://docs.google.com/document/d/<DOC_ID>/...`.\n\n2. Inspect before editing.\n   ```bash\n   gog docs info <DOC_ID> --json\n   gog docs structure <DOC_ID>\n   gog docs export <DOC_ID> --format md --out /tmp/doc.md\n   ```\n\n3. Decide the edit strategy.\n   - New document from Markdown: use `gog docs create --file`.\n   - Replace a known placeholder or section: use `gog docs find-replace --format markdown`.\n   - Small textual fix: use `gog docs edit` or `gog docs sed`.\n   - Append content: use `gog docs write --append` or `gog docs insert`.\n   - Full rewrite: only after explicit approval; prefer creating a copy first.\n\n4. Prepare content as Markdown.\n   - Use Markdown headings, bullets, numbered lists, tables, bold/italic, and links.\n   - Keep semantic structure simple; Google Docs conversion is more reliable with clean Markdown.\n   - For images, use supported Markdown image syntax only if `gog docs create` / `find-replace --format markdown` supports the source.\n\n5. Apply the change with `gog`.\n\n6. Verify after editing.\n   ```bash\n   gog docs structure <DOC_ID>\n   gog docs export <DOC_ID> --format md --out /tmp/doc-after.md\n   ```\n   Compare the exported Markdown or structure against the intended result.\n\n7. Report concisely.\n   - What changed\n   - Any limitations observed\n   - Link or doc ID if useful\n\n## Common operations\n\n### Create a formatted Google Doc from Markdown\n\nPrepare a local Markdown file, then:\n\n```bash\ngog docs create \"Document title\" --file /path/to/content.md\n```\n\nUse this instead of Markdown → DOCX → Drive upload unless the user specifically needs DOCX behavior.\n\n### Replace a placeholder with formatted Markdown\n\nBest when the document contains a marker such as `{{SECTION_DRAFT}}`.\n\n```bash\ngog docs find-replace <DOC_ID> '{{SECTION_DRAFT}}' --content-file /path/to/section.md --format markdown --first\n```\n\nPrefer `--first` when replacing a unique placeholder to avoid accidental repeated changes.\n\n### Replace an existing section\n\nIf possible, first ask the user to add or approve stable markers around the section:\n\n```text\n<!-- START: SECTION_NAME -->\nold content\n<!-- END: SECTION_NAME -->\n```\n\nThen replace the bounded content with `gog docs find-replace --format markdown` using a prepared Markdown file.\n\nIf there are no stable markers, use `gog docs structure` to identify paragraphs and proceed carefully. Do not guess destructive ranges.\n\n### Small text edits\n\n```bash\ngog docs edit <DOC_ID> \"old text\" \"new text\" --match-case\n```\n\nFor regex-style replacements:\n\n```bash\ngog docs sed <DOC_ID> 's/old pattern/new text/g'\n```\n\nUse regex edits only when the match is unambiguous.\n\n### Append content\n\n```bash\ngog docs write <DOC_ID> --file /path/to/content.md --append\n```\n\nIf Markdown formatting is required, prefer placeholder replacement with `--format markdown` when available.\n\n### Full document rewrite\n\nOnly after explicit approval. Prefer making a copy first:\n\n```bash\ngog docs copy <DOC_ID> \"Backup before rewrite\"\ngog docs clear <DOC_ID>\ngog docs write <DOC_ID> --file /path/to/content.md\n```\n\nTell the user if the write path preserves only text rather than rich Markdown formatting; use `create --file` or `find-replace --format markdown` for rich Markdown conversion.\n\n## Formatting guidance\n\nUse simple, robust Markdown:\n\n```markdown\n# Title\n\n## Section\n\nShort paragraph.\n\n- Bullet one\n- Bullet two\n\n| Column A | Column B |\n| --- | --- |\n| Value A | Value B |\n\n**Bold** and *italic* text.\n```\n\nAvoid fragile formatting unless tested:\n- deeply nested lists\n- complex merged tables\n- unusual HTML\n- custom fonts/colors not expressible through Markdown\n\nFor advanced visual formatting not supported by `gog`, explain the limitation and propose the nearest `gog`-supported alternative.\n\n## When to stop and ask\n\nAsk the user before proceeding if:\n- the document ID is ambiguous\n- the requested formatting requires capabilities not exposed by `gog`\n- the edit would delete or overwrite substantial content\n- the exported/inspected structure does not match expectations\n- `gog` reports auth/scope errors\n\nDo not install other Google Docs skills just to complete formatting. This skill is meant to compose with `gog`, not replace it.\n","topics":["Docs"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":339,"installsAllTime":12,"installsCurrent":0,"stars":0,"versions":1},"createdAt":1778420553416,"updatedAt":1778492892498},"latestVersion":{"version":"1.0.0","createdAt":1778420553416,"changelog":"Initial instruction-only workflow for formatting, editing, and creating Google Docs with gog CLI.","license":"MIT-0"},"metadata":null,"owner":{"handle":"sebastiangansca","userId":"s17ed68ade61thwbnwjp8c70td862me5","displayName":"Sebastian Gansca","image":"https://avatars.githubusercontent.com/u/89026773?v=4"},"moderation":null}