gsheet2md

SPREADSHEET_ID

Requirements

• OAuth credentials at

  ~/.config/google-sheets/oauth-token.json

  with:

  • client_id

  • client_secret

  • refresh_token

• Google Sheets API enabled for that OAuth app

Output Policy

• Use the installed script from the skill directory, but write any authored markdown into

  ./docs

  of the current workspace.
• If

  ./docs

  does not exist, create it before writing files.
• Do not save generated documents into the installed skill directory.

Usage

Step 1: Resolve the installed script path

SKILL.md

<skill-dir>/scripts/read_sheet.py

Step 2: Fetch sheet data

python3 <skill-dir>/scripts/read_sheet.py --spreadsheet-id <SPREADSHEET_ID> --sheet-name <SHEET_NAME>

Step 3: Convert to readable markdown

• Understanding the data structure
• Formatting sections with clear headings, tables, and lists
• Writing short descriptions where needed
• Organizing the content for human readers
• Saving the final markdown file under

  ./docs/<derived-sheet-name>.md

  in the current workspace

Parameters

--spreadsheet-id

--sheet-name

--credentials

~/.config/google-sheets/oauth-token.json

--output

--format

json

table

text

--raw

Example

# Fetch as JSON
python3 <skill-dir>/scripts/read_sheet.py \
  --spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" \
  --sheet-name "Sheet1"

# Fetch as markdown table
python3 <skill-dir>/scripts/read_sheet.py \
  --spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" \
  --format table

# Save raw output directly into the current workspace docs folder
mkdir -p ./docs
python3 <skill-dir>/scripts/read_sheet.py \
  --spreadsheet-id "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms" \
  --format table \
  --output ./docs/sheet1.md

OAuth Credentials Format

{
  "type": "oauth",
  "client_id": "your-client-id.apps.googleusercontent.com",
  "client_secret": "your-client-secret",
  "refresh_token": "your-refresh-token"
}

Workflow For Markdown Output

1. Run the script to fetch the sheet data.
2. Inspect the returned structure before formatting it.
3. Ensure

   ./docs

   exists in the current workspace. If

   ./docs

   does not exist, create it.
4. Write a markdown document that matches the content shape instead of forcing a fixed template.
5. Save the markdown document under

   ./docs/

   using a filename derived from the sheet name.