Google Doc Format

Convert markdown files into cleanly formatted Google Docs with native tables, headings, bold, lists, and clickable links using gog docs create --file.

Security Scan

The SKILL.md requires a local 'gog' CLI, shell tools (python3, grep, head) and authenticated access to Google Drive (including delete/rename/move), but the skill metadata declares no binaries, credentials, or install steps — this mismatch and the presence of destructive operations are concerning.

Purpose & Capability

The skill description (convert markdown to Google Docs) is plausible, but the runtime instructions assume a local 'gog' CLI and utilities (cat, grep, python3, head) and Drive access (create, rename, delete, move). The registry metadata lists no required binaries or credentials — that's inconsistent. Creating/deleting Google Docs legitimately requires Drive API auth/scopes, which are not declared.

Instruction Scope

Instructions tell the agent to write temp files, run 'gog docs create --file', verify structure, and to rename/delete/move docs (destructive operations). They also include shell pipelines and a truncated python snippet. The instructions therefore operate on local filesystem and remote Google Drive and perform irreversible actions, but give no guardrails or explicit user consent steps.

Install Mechanism

There is no install spec (instruction-only), which reduces disk/write risk. However, the skill implicitly depends on an external CLI ('gog') and standard unix tools; the absence of a declared install or required-binaries list is a mismatch worth noting.

Credentials

No environment variables, credentials, or config paths are declared, yet the workflow requires authenticated Google Drive operations and likely relies on locally stored OAuth tokens or CLI auth state. The skill also uses --force delete operations that would need broad Drive permissions; requesting such access without declaring it is disproportionate.

Persistence & Privilege

The skill does not request always:true and has no install-time persistence. Autonomous invocation is allowed (default) — this is expected for skills, but combined with the other concerns it means the agent could perform destructive Drive ops if run.

What to consider before installing

This skill's instructions assume you already have the 'gog' CLI, python3 and basic shell utilities, and an authenticated Google Drive session with permission to create/rename/delete/move documents — but the skill metadata doesn't declare these requirements. Before installing or enabling: (1) verify where and how 'gog' is installed and what auth it uses; (2) do not grant broad Drive scopes; test against a throwaway Google account and folder first; (3) watch out for the --force delete/rename commands — ensure human confirmation is required before destructive actions; (4) ask the publisher to declare required binaries and exact auth scopes and to provide the missing/truncated python command; and (5) if you allow autonomous runs, restrict the skill or require manual approval for operations that modify or delete Drive files.

Google Doc Format Skill

Create professionally formatted Google Docs from markdown using gog docs create --file. The key insight: markdown tables and formatting render properly as native Google Docs elements when passed through the --file flag.

Core Method

Always use gog docs create with --file to import markdown. Never use gog docs write or gog docs insert for full documents — those don't parse markdown tables.

gog docs create "Doc Title" --file source.md --parent "FOLDER_ID" --pageless --force --no-input

Flags:

• --file — Import markdown file (required for proper table rendering)
• --parent — Google Drive folder ID
• --pageless — Use pageless layout (recommended for reports/audits)
• --force — Skip confirmations

Markdown → Google Docs Mapping

Markdown	Google Docs Element
# Heading 1	HEADING_1
## Heading 2	HEADING_2
### Heading 3	HEADING_3
**bold text**	Bold text
*italic text*	Italic text
- item or * item	Bullet list
1. item	Numbered list
| col1 | col2 |	Native TABLE element
[link text](url)	Clickable hyperlink
---	Horizontal rule
> blockquote	Indented text

Table Formatting Rules

Markdown pipe tables render as native Google Docs tables — this is the main value of this skill. Tables are the element most likely to break when creating docs any other way.

Correct format:

| # | Document | Link |
|---|----------|------|
| 01 | Technical SEO Audit | [Open doc](https://docs.google.com/document/d/DOC_ID/edit) |
| 02 | On-Page SEO Audit | [Open doc](https://docs.google.com/document/d/DOC_ID/edit) |

What NOT to do:

• ❌ Tab-separated values (no \t between columns)
• ❌ Plain text pretending to be a table
• ❌ Using gog docs write with raw text (doesn't parse markdown)
• ❌ Putting tables inside code blocks (won't render as tables)

Document Templates

Master Index / Link Index Doc

# Project Name — Deliverables Master Index

*Last updated: DATE*

---

## 📋 Section Name

### Subsection

| # | Document | Link |
|---|----------|------|
| 01 | Document Name | [Open doc](https://docs.google.com/document/d/DOC_ID/edit) |
| 02 | Document Name | [Open doc](https://docs.google.com/document/d/DOC_ID/edit) |

---

## 🎨 Another Section

### Subsection

| # | Document | Link |
|---|----------|------|
| 01 | Document Name | [Open doc](https://docs.google.com/document/d/DOC_ID/edit) |

---

## 📂 Folder Structure

- **Root:** Folder Name
  - **Subfolder**
    - Document 1
    - Document 2

Audit/Report Doc

# Report Title: Descriptive Subtitle

**URL:** /page-slug/
**Target Keywords:** keyword1, keyword2, keyword3
**Meta Title:** SEO Title (60 chars)
**Meta Description:** Meta description (155 chars)

---

## Section Heading

Body paragraph with **bold key terms** and normal text.

### Subsection

| Metric | 2024 | 2023 | Change |
|--------|------|------|--------|
| Value 1 | 232 | 274 | -15% |

**Key takeaway:** Summary sentence after the table.

### Another Subsection

- **Bold label** — Description text
- **Bold label** — Description text

Workflow

1. Write markdown to temp file — cat > /tmp/doc_name.md << 'EOF'
2. Create doc — gog docs create "Title" --file /tmp/doc_name.md --parent FOLDER_ID --pageless --force --no-input
3. Verify structure — gog docs structure DOC_ID --no-input | grep -i table
4. Verify content — gog docs cat DOC_ID --no-input | head -20

Verification Checklist

After creating, verify:

• gog docs structure shows TABLE elements (not just NORMAL_TEXT with pipe characters)
• Table row counts match expected dimensions (e.g., [table 6x3])
• Links are clickable: [Open doc](url) renders as hyperlinks
• Heading hierarchy is correct (H1 > H2 > H3)
• Bold text renders (check structure output for inline formatting)

Replacing an Existing Doc

To replace a badly formatted doc:

1. Create new doc with --file flag
2. Verify formatting on the new doc
3. Rename new doc to match old name: gog drive rename NEW_ID "Original Name" --force --no-input
4. Delete old doc: gog drive delete OLD_ID --force --no-input
5. Move new doc to correct folder if needed: gog drive move NEW_ID --parent FOLDER_ID --force --no-input

Common Issues

Problem	Cause	Fix
Tables show as pipe-separated text	Used gog docs write instead of --file	Recreate with gog docs create --file
Links not clickable	Used plain URLs, not markdown link syntax	Use [text](url) format
No headings	Used underline-style headings	Use # prefix headings
Missing bold	Used HTML <b> tags	Use **text** markdown
Rate limit (429)	Too many API calls in short time	Add sleep 3 between operations

Rate Limiting

Google Docs API has per-minute write quotas. When creating multiple docs:

• Add sleep 3 between create operations
• If you get 429 errors, wait 60 seconds and retry
• For large batches (5+ docs), add sleep 5 between each

Getting Doc IDs for Link Tables

To build a link index:

1. List folder contents: gog drive ls --parent FOLDER_ID --json --no-input
2. Extract IDs and names with: python3 -c "import json,sys; data=json.load(sys.stdin); [print(f'{f[\"name\"]} | {f[\"id\"]}') for f in data.get('files',[])]"
3. Build Google Doc URLs: https://docs.google.com/document/d/DOC_ID/edit