google-drive

Original source / Raw SKILL.md

---
name: google-drive
description: Manage Google Drive files and folders with full CRUD operations via Ruby scripts. Use for file storage operations, folder organization, sharing permissions, searching across Drive, and uploading/downloading files of any type. Works seamlessly with google-sheets and google-docs skills for complete Google Workspace integration.
category: productivity
version: 1.0.0
key_capabilities: list, search, upload, download, share, organize folders, manage permissions
when_to_use: File operations, folder management, permission sharing, Drive-wide search, any file type upload/download
---

# Google Drive Management Skill

## Overview

Provide comprehensive Google Drive file and folder management capabilities through Ruby-based scripts with shared authentication. Enable full CRUD operations (Create, Read, Update, Delete) on Google Drive files and folders.

## When to Use This Skill

Use this skill for ANY Google Drive operations:

- **File Management**: Upload, download, read, update, delete files
- **Folder Management**: Create, list, organize folders
- **Search**: Find files and folders by name, type, or content
- **Sharing**: Manage file and folder permissions
- **Content Reading**: Read text file contents directly
- **Metadata**: View and update file properties

## Authentication

This skill shares authentication with the calendar and contacts skills via `~/.claude/.google/token.json`. All skills use the same OAuth token with scopes:
- `https://www.googleapis.com/auth/calendar` (Calendar access)
- `https://www.googleapis.com/auth/contacts` (Contacts read/write)
- `https://www.googleapis.com/auth/drive` (Google Drive full access)

When any skill refreshes the token, all skills benefit from the updated authentication.

### First-Time Setup

If Google Drive scope not already configured:

1. Ensure `~/.claude/.google/client_secret.json` exists with OAuth credentials
2. Run any Google Drive operation - the script will prompt for authorization
3. The token will be stored and shared with calendar and contacts skills

### Re-authorization for New Scope

Since the Drive scope is new, you'll need to re-authorize once:

```bash
# Delete the existing token to force re-authorization
rm ~/.claude/.google/token.json

# Run any Drive operation to trigger OAuth flow
~/.claude/skills/google-drive/scripts/drive_manager.rb --list
```

Follow the authorization URL and enter the code when prompted.

## Core Script: drive_manager.rb

Location: `scripts/drive_manager.rb`

Comprehensive Ruby script providing all Google Drive operations through the Drive API v3.

### List Files and Folders

Browse your Google Drive:

```bash
# List all files (default: 100 items)
drive_manager.rb --list

# List with custom page size
drive_manager.rb --list --page-size 50

# List only folders
drive_manager.rb --list --type folder

# List only specific file types
drive_manager.rb --list --type "application/pdf"

# Get next page using token from previous response
drive_manager.rb --list --page-token "NEXT_PAGE_TOKEN"
```

Returns JSON array of files with metadata (id, name, mimeType, createdTime, modifiedTime, size, webViewLink).

### Search Files

Find files by name or query:

```bash
# Search by name (partial match)
drive_manager.rb --search "project report"

# Search by exact name
drive_manager.rb --search "Budget 2024.xlsx" --exact

# Search in specific folder
drive_manager.rb --search "invoice" --folder "FOLDER_ID"

# Advanced query (full Drive API query syntax)
drive_manager.rb --query "mimeType='application/pdf' and modifiedTime > '2024-01-01'"
```

### Get File Details

Retrieve complete information about a specific file:

```bash
# Get by file ID
drive_manager.rb --get "FILE_ID"

# Get with download URL
drive_manager.rb --get "FILE_ID" --include-download-url
```

Returns full file metadata including sharing permissions and download links.

### Read File Content

Read text-based file contents directly:

```bash
# Read text file content
drive_manager.rb --read "FILE_ID"

# Read with specific export format (for Google Docs)
drive_manager.rb --read "FILE_ID" --export-format "text/plain"
```

**Supported File Types**:
- Plain text files (.txt)
- Google Docs (exports as text/plain, text/html, or application/pdf)
- Google Sheets (exports as CSV, XLSX, or PDF)
- CSV files
- JSON files
- Markdown files (.md)

### Upload Files

Upload files to Google Drive:

```bash
# Upload file to root
drive_manager.rb --upload "/path/to/file.pdf"

# Upload to specific folder
drive_manager.rb --upload "/path/to/file.pdf" --folder "FOLDER_ID"

# Upload with custom name
drive_manager.rb --upload "/path/to/file.pdf" --name "Custom Name.pdf"

# Upload with description
drive_manager.rb --upload "/path/to/file.pdf" --description "Q4 Financial Report"
```

### Download Files

Download files from Google Drive:

```bash
# Download to current directory
drive_manager.rb --download "FILE_ID"

# Download to specific location
drive_manager.rb --download "FILE_ID" --output "/path/to/save/file.pdf"

# Download Google Docs as PDF
drive_manager.rb --download "FILE_ID" --export-format "application/pdf"

# Download Google Sheets as Excel
drive_manager.rb --download "FILE_ID" --export-format "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
```

### Create Folders

Organize files with folders:

```bash
# Create folder in root
drive_manager.rb --create-folder "Project Files"

# Create folder in specific parent
drive_manager.rb --create-folder "Invoices" --folder "PARENT_FOLDER_ID"

# Create nested folder structure
drive_manager.rb --create-folder "2024/Q4/Reports" --create-path
```

### Update Files

Modify file metadata:

```bash
# Rename file
drive_manager.rb --update "FILE_ID" --name "New Name.pdf"

# Update description
drive_manager.rb --update "FILE_ID" --description "Updated description"

# Move file to different folder
drive_manager.rb --update "FILE_ID" --move-to "NEW_FOLDER_ID"

# Update multiple properties
drive_manager.rb --update "FILE_ID" \
  --name "Report.pdf" \
  --description "Final version" \
  --move-to "FOLDER_ID"
```

### Share Files

Manage file and folder permissions:

```bash
# Share with specific user (reader)
drive_manager.rb --share "FILE_ID" --email "[email protected]" --role reader

# Share with specific user (writer)
drive_manager.rb --share "FILE_ID" --email "[email protected]" --role writer

# Share with anyone with link (reader)
drive_manager.rb --share "FILE_ID" --role reader --anyone

# Make file public
drive_manager.rb --share "FILE_ID" --role reader --anyone

# Share entire folder
drive_manager.rb --share "FOLDER_ID" --email "[email protected]" --role writer
```

**Permission Roles**:
- `reader` - Can view and download
- `commenter` - Can view and comment
- `writer` - Can edit and organize
- `owner` - Full control (transfer ownership)

### Delete Files

Remove files and folders:

```bash
# Move to trash (recoverable)
drive_manager.rb --delete "FILE_ID"

# Permanent delete (non-recoverable)
drive_manager.rb --delete "FILE_ID" --permanent
```

**Warning**: Permanent deletion cannot be undone.

### Copy Files

Duplicate files:

```bash
# Copy file in same location
drive_manager.rb --copy "FILE_ID"

# Copy with new name
drive_manager.rb --copy "FILE_ID" --name "Copy of Document"

# Copy to different folder
drive_manager.rb --copy "FILE_ID" --folder "TARGET_FOLDER_ID"
```

## File Type Reference

See `references/file_types.md` for comprehensive MIME type documentation.

### Common MIME Types

**Documents**:
- Google Docs: `application/vnd.google-apps.document`
- Microsoft Word: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`
- PDF: `application/pdf`
- Plain text: `text/plain`

**Spreadsheets**:
- Google Sheets: `application/vnd.google-apps.spreadsheet`
- Microsoft Excel: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
- CSV: `text/csv`

**Folders**:
- Folder: `application/vnd.google-apps.folder`

## Workflow Patterns

### Finding and Reading a File

```bash
# 1. Search for file
SEARCH_RESULT=$(drive_manager.rb --search "report")

# 2. Extract file ID from results
FILE_ID=$(echo $SEARCH_RESULT | jq -r '.files[0].id')

# 3. Read file content
drive_manager.rb --read "$FILE_ID"
```

### Uploading and Sharing

```bash
# 1. Upload file
UPLOAD_RESULT=$(drive_manager.rb --upload "/path/to/file.pdf" --name "Shared Report.pdf")

# 2. Extract file ID
FILE_ID=$(echo $UPLOAD_RESULT | jq -r '.file.id')

# 3. Share with team
drive_manager.rb --share "$FILE_ID" --email "[email protected]" --role writer

# 4. Get shareable link
drive_manager.rb --get "$FILE_ID" --include-download-url
```

### Organizing Files into Folders

```bash
# 1. Create folder structure
FOLDER_RESULT=$(drive_manager.rb --create-folder "2024/Projects" --create-path)
FOLDER_ID=$(echo $FOLDER_RESULT | jq -r '.folder.id')

# 2. Move existing files
drive_manager.rb --update "FILE_ID_1" --move-to "$FOLDER_ID"
drive_manager.rb --update "FILE_ID_2" --move-to "$FOLDER_ID"

# 3. Upload new files directly to folder
drive_manager.rb --upload "/path/to/new-file.pdf" --folder "$FOLDER_ID"
```

### Bulk Operations

```bash
# Find all PDFs
drive_manager.rb --query "mimeType='application/pdf'" > pdfs.json

# Process each PDF
cat pdfs.json | jq -r '.files[].id' | while read file_id; do
  # Download each
  drive_manager.rb --download "$file_id" --output "/backup/$file_id.pdf"
done
```

## Integration with Other Skills

### Calendar Skill Integration

Share calendar-related documents:

```bash
# Upload meeting notes
drive_manager.rb --upload "meeting-notes.pdf" --name "Team Standup Notes"

# Share with meeting attendees
drive_manager.rb --share "$FILE_ID" --email "[email protected]" --role reader
```

### Contacts Skill Integration

Store contact-related documents:

```bash
# Create contacts folder
FOLDER_ID=$(drive_manager.rb --create-folder "Contact Documents" | jq -r '.folder.id')

# Upload contract for specific contact
drive_manager.rb --upload "contract.pdf" \
  --folder "$FOLDER_ID" \
  --name "John Doe - Service Agreement"
```

### Email Skill Integration

Attach Drive files to emails or save email attachments:

```bash
# Get shareable link for email
LINK=$(drive_manager.rb --get "$FILE_ID" --include-download-url | jq -r '.file.webViewLink')

# Include link in email message
~/.claude/skills/email/send_email.sh "[email protected]" \
  "Check out this document: $LINK"
```

## Error Handling

The script returns JSON with status and error details:

```json
{
  "status": "error",
  "code": "AUTH_ERROR|API_ERROR|FILE_NOT_FOUND|INVALID_ARGS",
  "message": "Detailed error message"
}
```

**Exit Codes**:
- `0` - Success
- `1` - Operation failed
- `2` - Authentication error
- `3` - API error
- `4` - Invalid arguments
- `5` - File not found

## Common Use Cases

### Document Management

```bash
# Upload and organize quarterly reports
drive_manager.rb --create-folder "2024/Q4" --create-path
drive_manager.rb --upload "Q4-report.pdf" --folder "$FOLDER_ID"
drive_manager.rb --share "$FILE_ID" --email "[email protected]" --role reader
```

### Backup Strategy

```bash
# Download all important files for backup
drive_manager.rb --query "starred=true" > starred.json
cat starred.json | jq -r '.files[].id' | while read id; do
  drive_manager.rb --download "$id" --output "/backup/"
done
```

### Collaborative Workspace

```bash
# Create shared project folder
FOLDER_ID=$(drive_manager.rb --create-folder "Team Project" | jq -r '.folder.id')

# Share with team
drive_manager.rb --share "$FOLDER_ID" --email "[email protected]" --role writer

# Upload project files
drive_manager.rb --upload "specs.pdf" --folder "$FOLDER_ID"
drive_manager.rb --upload "design.fig" --folder "$FOLDER_ID"
```

### Content Retrieval

```bash
# Read configuration file from Drive
CONFIG=$(drive_manager.rb --search "config.json" | jq -r '.files[0].id')
drive_manager.rb --read "$CONFIG" > local-config.json
```

## Best Practices

1. **Search Before Upload**: Avoid duplicates by searching first
2. **Use Folders**: Organize files hierarchically for better management
3. **Descriptive Names**: Use clear, searchable file names
4. **Minimal Permissions**: Share with least privilege necessary
5. **Regular Cleanup**: Periodically review and delete unused files
6. **Backup Important Files**: Download critical files to local storage
7. **Check File IDs**: Always verify file IDs before destructive operations

## Troubleshooting

### Authentication Issues

```bash
# Re-authorize if token invalid
rm ~/.claude/.google/token.json
drive_manager.rb --list
```

### Scope Errors

If you see Drive scope-related errors, ensure the token has the Drive scope:

```bash
# Check current scopes
cat ~/.claude/.google/token.json | jq -r '.default.scope'

# Should include: https://www.googleapis.com/auth/drive
```

### File Not Found

```bash
# Verify file exists and you have access
drive_manager.rb --get "FILE_ID"

# Search for file by name
drive_manager.rb --search "filename"
```

### API Quota Limits

Google Drive API has rate limits. If you hit quota:
- Wait a few minutes before retrying
- Reduce batch operation sizes
- Implement exponential backoff for bulk operations

## Advanced Features

### Query Syntax

The `--query` flag supports full Drive API query syntax:

```bash
# Files modified in last 7 days
drive_manager.rb --query "modifiedTime > '2024-10-24'"

# Files larger than 10MB
drive_manager.rb --query "size > 10485760"

# Files shared with me
drive_manager.rb --query "sharedWithMe=true"

# Combine conditions
drive_manager.rb --query "mimeType='application/pdf' and starred=true and trashed=false"
```

### Export Formats

Google Workspace files can be exported in various formats:

**Google Docs**:
- `text/plain` - Plain text
- `text/html` - HTML
- `application/pdf` - PDF
- `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - DOCX

**Google Sheets**:
- `text/csv` - CSV
- `application/pdf` - PDF
- `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - XLSX

**Google Slides**:
- `application/pdf` - PDF
- `application/vnd.openxmlformats-officedocument.presentationml.presentation` - PPTX

## Script Version

Current version: 1.0.0

Run `drive_manager.rb --version` to check installed version.

## Dependencies

- Ruby 3.3.7 (same as contacts and calendar skills)
- `google-apis-drive_v3` gem
- `googleauth` gem
- Shared OAuth credentials with calendar and contacts skills


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/file_types.md

```markdown
# Google Drive File Types Reference

## MIME Type Categories

### Google Workspace Files

**Google Docs**:
- MIME: `application/vnd.google-apps.document`
- Export formats:
  - `text/plain` - Plain text
  - `text/html` - HTML
  - `application/pdf` - PDF
  - `application/vnd.openxmlformats-officedocument.wordprocessingml.document` - Word (.docx)
  - `application/rtf` - Rich Text Format
  - `application/epub+zip` - EPUB

**Google Sheets**:
- MIME: `application/vnd.google-apps.spreadsheet`
- Export formats:
  - `text/csv` - CSV (first sheet only)
  - `application/pdf` - PDF
  - `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` - Excel (.xlsx)
  - `application/vnd.oasis.opendocument.spreadsheet` - OpenDocument (.ods)
  - `text/tab-separated-values` - TSV (first sheet only)

**Google Slides**:
- MIME: `application/vnd.google-apps.presentation`
- Export formats:
  - `application/pdf` - PDF
  - `application/vnd.openxmlformats-officedocument.presentationml.presentation` - PowerPoint (.pptx)
  - `application/vnd.oasis.opendocument.presentation` - OpenDocument (.odp)
  - `text/plain` - Plain text

**Google Forms**:
- MIME: `application/vnd.google-apps.form`
- Export formats:
  - `application/zip` - Form responses as ZIP

**Google Drawings**:
- MIME: `application/vnd.google-apps.drawing`
- Export formats:
  - `application/pdf` - PDF
  - `image/svg+xml` - SVG
  - `image/png` - PNG
  - `image/jpeg` - JPEG

**Google Sites**:
- MIME: `application/vnd.google-apps.site`
- No export available

**Google My Maps**:
- MIME: `application/vnd.google-apps.map`
- Export formats:
  - `application/pdf` - PDF
  - `application/vnd.google-earth.kml+xml` - KML

### Microsoft Office Files

**Word Documents**:
- `.doc`: `application/msword`
- `.docx`: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`

**Excel Spreadsheets**:
- `.xls`: `application/vnd.ms-excel`
- `.xlsx`: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`

**PowerPoint Presentations**:
- `.ppt`: `application/vnd.ms-powerpoint`
- `.pptx`: `application/vnd.openxmlformats-officedocument.presentationml.presentation`

### Document Files

**PDF**:
- MIME: `application/pdf`

**Text Files**:
- Plain text: `text/plain`
- Rich text: `application/rtf`
- Markdown: `text/markdown`
- CSV: `text/csv`
- TSV: `text/tab-separated-values`

**HTML**:
- MIME: `text/html`

**XML**:
- MIME: `text/xml` or `application/xml`

**JSON**:
- MIME: `application/json`

### Image Files

**Common Formats**:
- JPEG: `image/jpeg`
- PNG: `image/png`
- GIF: `image/gif`
- BMP: `image/bmp`
- WebP: `image/webp`
- SVG: `image/svg+xml`
- TIFF: `image/tiff`

**RAW Formats**:
- Various RAW formats have specific MIME types

### Video Files

**Common Formats**:
- MP4: `video/mp4`
- MOV: `video/quicktime`
- AVI: `video/x-msvideo`
- WMV: `video/x-ms-wmv`
- FLV: `video/x-flv`
- WebM: `video/webm`

### Audio Files

**Common Formats**:
- MP3: `audio/mpeg`
- WAV: `audio/wav`
- OGG: `audio/ogg`
- M4A: `audio/mp4`
- FLAC: `audio/flac`

### Archive Files

**Common Formats**:
- ZIP: `application/zip`
- TAR: `application/x-tar`
- GZIP: `application/gzip`
- RAR: `application/vnd.rar`
- 7Z: `application/x-7z-compressed`

### Code Files

**Common Languages**:
- JavaScript: `application/javascript` or `text/javascript`
- Python: `text/x-python`
- Java: `text/x-java-source`
- C/C++: `text/x-c` or `text/x-c++`
- Ruby: `text/x-ruby`
- PHP: `application/x-httpd-php`
- Shell: `text/x-shellscript`

### Folders

**Google Drive Folder**:
- MIME: `application/vnd.google-apps.folder`

## Usage Examples

### Filter by Type

```bash
# List only PDFs
drive_manager.rb --list --type "application/pdf"

# List only Google Docs
drive_manager.rb --list --type "application/vnd.google-apps.document"

# List only folders
drive_manager.rb --list --type folder

# List images (use query for pattern matching)
drive_manager.rb --query "mimeType contains 'image/'"
```

### Export Google Workspace Files

```bash
# Export Google Doc as PDF
drive_manager.rb --download FILE_ID --export-format "application/pdf"

# Export Google Sheet as Excel
drive_manager.rb --download FILE_ID --export-format "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"

# Export Google Slides as PowerPoint
drive_manager.rb --download FILE_ID --export-format "application/vnd.openxmlformats-officedocument.presentationml.presentation"

# Read Google Doc as plain text
drive_manager.rb --read FILE_ID --export-format "text/plain"
```

### Query by MIME Type

```bash
# Find all spreadsheets (Google Sheets and Excel)
drive_manager.rb --query "mimeType contains 'spreadsheet'"

# Find all documents (Google Docs and Word)
drive_manager.rb --query "mimeType contains 'document'"

# Find all images
drive_manager.rb --query "mimeType contains 'image/'"

# Find all videos
drive_manager.rb --query "mimeType contains 'video/'"

# Combine with other criteria
drive_manager.rb --query "mimeType='application/pdf' and modifiedTime > '2024-01-01'"
```

## Common MIME Type Shortcuts

For convenience, the script recognizes these shortcuts:

- `folder` → `application/vnd.google-apps.folder`
- `doc` → `application/vnd.google-apps.document`
- `sheet` → `application/vnd.google-apps.spreadsheet`
- `slide` → `application/vnd.google-apps.presentation`
- `pdf` → `application/pdf`
- `image` → `image/*` (pattern match)
- `video` → `video/*` (pattern match)
- `audio` → `audio/*` (pattern match)

## Best Practices

1. **Use specific MIME types** when possible for faster queries
2. **Export Google Workspace files** to compatible formats for offline use
3. **Pattern matching** with `contains` for finding all files of a category
4. **Combine filters** in queries for precise file discovery
5. **Check MIME type** before attempting to read/export files

## Additional Resources

- [Google Drive API MIME Types](https://developers.google.com/drive/api/guides/mime-types)
- [IANA Media Types Registry](https://www.iana.org/assignments/media-types/media-types.xhtml)
- [Google Workspace Export Formats](https://developers.google.com/drive/api/guides/ref-export-formats)

```