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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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:

# Share with specific user (reader)
drive_manager.rb --share "FILE_ID" --email "user@example.com" --role reader

# Share with specific user (writer)
drive_manager.rb --share "FILE_ID" --email "user@example.com" --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 "team@example.com" --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:

# 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:

# 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

# 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

# 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 "team@example.com" --role writer

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

Organizing Files into Folders

# 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

# 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:

# 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 "attendee@example.com" --role reader

Contacts Skill Integration

Store contact-related documents:

# 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:

# 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 "recipient@example.com" \
  "Check out this document: $LINK"

Error Handling

The script returns JSON with status and error details:

{
  "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

# 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 "executive@company.com" --role reader

Backup Strategy

# 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

# 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 "team@company.com" --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

# 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

# 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:

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

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

File Not Found

# 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:

# 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