home / skills / abdullahbeam / nexus-design-abdullah / google-master

google-master skill

safe

This skill provides shared Google integration resources for authentication, error handling, and API patterns used by gmail, docs, sheets, and calendar.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill google-master

Review the files below or copy the command above to add this skill to your agents.

Files (5)

SKILL.md

6.7 KB

---
name: google-master
description: Shared resource library for Google integration skills. DO NOT load directly - provides common references (setup, API docs, error handling, authentication) and scripts used by gmail, google-docs, google-sheets, google-calendar, and future Google skills.
---

# Google Master

**This is NOT a user-facing skill.** It's a shared resource library referenced by all Google integration skills.

## Purpose

Provides shared resources to eliminate duplication across:
- `gmail` - Email operations (read, send, reply, forward)
- `google-docs` - Document operations (read, write, create, export)
- `google-sheets` - Spreadsheet operations (read, write, append)
- `google-calendar` - Calendar operations (events, availability, scheduling)

**Instead of loading this skill**, users directly invoke the specific skill they need above.

---

## Architecture: DRY Principle

**Problem solved:** Google skills would have duplicated content (OAuth setup, credentials management, error handling, API patterns).

**Solution:** Extract shared content into `google-master/references/` and `google-master/scripts/`, then reference from each skill.

**Result:**
- Single OAuth flow for all Google services
- One credentials source (`.env` file with GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID)
- One unified token with all scopes
- Consistent error handling across skills

---

## Shared Resources

All Google skills reference these resources (progressive disclosure).

### scripts/

#### Authentication & Configuration

**[google_auth.py](scripts/google_auth.py)** - Unified OAuth for all Google services
```bash
python google_auth.py --check [--service SERVICE] [--json]
python google_auth.py --login [--service SERVICE]
python google_auth.py --logout
python google_auth.py --status
```

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `--check` | No | - | Check if authenticated and ready |
| `--login` | No | - | Initiate OAuth login flow |
| `--logout` | No | - | Remove stored token |
| `--status` | No | - | Show detailed auth status |
| `--service` | No | all | Specific service: gmail, docs, sheets, calendar, or all |
| `--json` | No | False | Output as JSON |

**Exit codes:**
- 0 = configured and ready
- 1 = needs login (credentials exist but not authenticated)
- 2 = not configured (missing credentials or dependencies)

**When to Use:** Run this FIRST before any Google operation. Called automatically by individual skills.

---

**[check_google_config.py](scripts/check_google_config.py)** - Pre-flight validation
```bash
python check_google_config.py [--json]
```

| Argument | Required | Default | Description |
|----------|----------|---------|-------------|
| `--json` | No | False | Output structured JSON for AI consumption |

**When to Use:** Quick check if Google integration is configured. Use for diagnostics.

---

### references/

**[setup-guide.md](references/setup-guide.md)** - Complete setup wizard
- Creating Google Cloud project
- Enabling APIs (Gmail, Docs, Sheets, Calendar)
- Creating OAuth 2.0 credentials
- Adding credentials to `.env` file
- First-time authentication flow

**[error-handling.md](references/error-handling.md)** - Troubleshooting
- Common errors and solutions
- HTTP error codes (401, 403, 404)
- Scope/permission issues
- Rate limiting
- Token refresh failures

**[api-patterns.md](references/api-patterns.md)** - Common patterns
- Authentication headers
- Pagination
- Batch requests
- Error responses

---

## Service Scopes

The unified token requests all scopes on first login:

| Service | Scopes |
|---------|--------|
| Gmail | gmail.readonly, gmail.send, gmail.compose, gmail.modify, gmail.labels |
| Docs | documents, drive |
| Sheets | spreadsheets, drive.readonly |
| Calendar | calendar, calendar.events |

**Note:** User grants all permissions once, then all Google skills work.

---

## File Locations

| File | Location | Purpose |
|------|----------|---------|
| OAuth credentials | `.env` (GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID) | App identity from Google Cloud |
| Access token | `01-memory/integrations/google-token.json` | User's authenticated token |

---

## How Skills Reference This

Each skill imports the shared auth module:

```python
# In any Google skill's operations script
import sys
from pathlib import Path

# Add google-master to path
NEXUS_ROOT = Path(__file__).resolve().parents[4]  # Adjust based on skill location
sys.path.insert(0, str(NEXUS_ROOT / "00-system/skills/google/google-master/scripts"))

from google_auth import get_credentials, get_service

# Get authenticated service
gmail = get_service('gmail', 'v1')
docs = get_service('docs', 'v1')
sheets = get_service('sheets', 'v4')
calendar = get_service('calendar', 'v3')
```

---

## Intelligent Error Detection Flow

When a Google skill fails due to missing configuration, the AI should:

### Step 1: Run Config Check with JSON Output

```bash
python 00-system/skills/google/google-master/scripts/check_google_config.py --json
```

### Step 2: Parse the `ai_action` Field

| ai_action | What to Do |
|-----------|------------|
| `proceed` | Config OK, continue with operation |
| `install_dependencies` | Run: `pip install google-auth google-auth-oauthlib google-api-python-client` |
| `need_credentials` | Guide user to create OAuth credentials in Google Cloud Console |
| `need_login` | Run: `python google_auth.py --login` |

### Step 3: Help User Fix Issues

If credentials missing:
1. Direct user to: https://console.cloud.google.com/
2. Guide through: APIs & Services > Credentials > Create OAuth Client ID (Desktop app)
3. Copy Client ID and Client Secret, add to `.env`:
   ```
   GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-client-secret
   GOOGLE_PROJECT_ID=your-project-id
   ```
4. Run `--login` to authenticate

---

## Usage Example

**User says:** "send an email to [email protected]"

**What happens:**
1. AI loads `gmail` skill (NOT google-master)
2. `gmail` SKILL.md says: "Run pre-flight check first"
3. AI executes: `python google-master/scripts/google_auth.py --check --service gmail`
4. If exit code 0: proceed with gmail_operations.py
5. If exit code 1: run `--login` automatically
6. If exit code 2: load error-handling.md, guide user through setup

**google-master is NEVER loaded directly** - it's just a resource library.

---

## Adding New Google Services

To add a new Google service (e.g., Google Drive, Google Tasks):

1. Add scopes to `SCOPES` dict in `google_auth.py`
2. Create new skill folder with operations script
3. Import `get_service()` from google-master
4. Document in this SKILL.md

---

**Version**: 1.0
**Created**: 2025-12-17
**Updated**: 2025-12-17
**Status**: Production Ready

Overview

This skill is a shared resource library that centralizes authentication, configuration, and common patterns for Google integrations. It is not loaded directly; instead, gmail, google-docs, google-sheets, google-calendar, and future Google skills import its scripts and references. The goal is to provide a single OAuth flow, unified token and consistent error handling so individual skills remain thin and focused.

How this skill works

The skill exposes a unified OAuth script and helper functions to obtain credentials and Google API service clients. It includes pre-flight check scripts, configuration validators, and documentation for setup, API patterns, and error handling. Individual Google skills import its google_auth utilities to get authenticated service objects and to run configuration checks before performing operations.

When to use it

Before any Google operation: run the auth check to confirm credentials and token status
As a pre-flight diagnostic when a Google skill reports authentication, permission, or configuration errors
During setup or troubleshooting to validate environment variables and installed dependencies
When adding a new Google-based skill to reuse authentication and error-handling patterns

Best practices

Run the provided check script first (automated by individual skills) to detect missing credentials or dependencies
Keep OAuth client values in the .env file: GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_PROJECT_ID
Request broad but appropriate scopes once so the unified token supports all Google services used
Use the shared error-handling guide to map HTTP errors to user-friendly remediation steps
Import get_service() from the library rather than reimplementing service construction in each skill

Example use cases

Send or read email via the gmail skill; the gmail skill calls the library to ensure auth and return a Gmail service client
Create, read, or export docs with google-docs while relying on shared Drive and Docs scopes
Read, write, or append spreadsheets; the sheets skill uses the shared token and pagination helpers
Create or modify calendar events; the calendar skill uses the unified OAuth token and availability patterns
Add a new Google service by extending the SCOPES dict and importing get_service() from this library

FAQ

What should I do if the auth check returns a non-zero exit code?

Run the check with --json to get the recommended ai_action. If it says need_credentials, create OAuth credentials in Google Cloud and add them to .env; if need_login, run google_auth.py --login.

Where is the access token stored and how is it refreshed?

The access token is saved to 01-memory/integrations/google-token.json; the shared auth script handles refresh and token lifecycle automatically, and will surface refresh failures in the error-handling guide.