gmail-skill

Files (18)

• .gitignore
• README.md
• SKILL.md
• google-cloud-setup.md · docs/
• package.json
• action-logger.js · scripts/
• auth-utils.js · scripts/auth/
• setup-oauth.js · scripts/auth/
• gmail-drafts.js · scripts/
• gmail-every-paywall-cleanup.js · scripts/
• gmail-filters.js · scripts/
• gmail-forward.js · scripts/
• gmail-labels.js · scripts/
• gmail-read.js · scripts/
• gmail-search.js · scripts/
• gmail-send.js · scripts/
• manage-accounts.js · scripts/
• migrate-tokens.js · scripts/

SKILL.md (first lines)

# Gmail Manager Skill

This skill provides comprehensive Gmail integration through lightweight CLI scripts. All operations are token-efficient and composable.

## First-Time Setup

Before using this skill, you must set up OAuth authentication:

1. **Install dependencies:**
   ```bash
   cd ~/.claude/skills/gmail-skill && npm install
   ```

2. **Set up Google Cloud credentials:**
   - Follow the guide in `docs/google-cloud-setup.md`
   - Download `credentials.json` and save to `scripts/auth/credentials.json`

3. **Authenticate:**
   ```bash
   cd ~/.claude/skills/gmail-skill && npm run setup
   ```

This will open a browser for Google OAuth and save your token locally.

## Multi-Account Support

The Gmail skill supports multiple accounts (e.g., personal and work email):

### Add Additional Accounts

```bash
# Add a second account (from skill directory)
npm run setup -- --account work

# Add a third account
npm run setup -- --account personal
```

Each account needs separate OAuth authentication.

### Manage Accounts

```bash
# List all configured accounts
node scripts/manage-accounts.js --list

# Set default account (used when --account is not specified)
node scripts/manage-accounts.js --set-default work

# Remove an account
node scripts/manage-accounts.js --remove old-account
```

### Using Specific Accounts

All Gmail operations support the `--account` parameter:

```bash
# Send email from work account
node gmail-send.js --account work --to "user@example.com" --subject "..." --body "..."

# Send from personal (or omit --account to use default)
node gmail-send.js --account personal --to "friend@example.com" --subject "..." --body "..."

# Search work emails
node gmail-search.js --account work --query "is:unread"
```

If `--account` is not specified, the default account is used.

## Usage Guidelines

### 1. Read Documentation On-Demand

When first using Gmail operations, read the comprehensive README:
```bash
cat ~/.claude/skills/gmail-skill/README.md
```

This provides detailed usage examples for all operations.

### 2. Execute Scripts via Bash

All scripts are in the `scripts/` directory and output JSON for easy parsing:

```bash
cd ~/.claude/skills/gmail-skill/scripts
```

### 3. Parse JSON Output

All scripts return JSON. Parse the output and present relevant information to the user in a friendly format.

### 4. Chain Operations

Save intermediate results to files when chaining operations:

```bash
# Search for emails
node gmail-search.js --query "from:user@example.com" > /tmp/search-results.json

# Read first message from results
MESSAGE_ID=$(cat /tmp/search-results.json | jq -r '.messages[0].id')
node gmail-read.js --id "$MESSAGE_ID"
```

## Available Operations

### Send Email
```bash
node gmail-send.js --to "user@example.com" --subject "Subject" --body "Body text"
```

### Search Emails
```bash
node gmail-search.js --query "is:unread" --limit 10
```

### Read Message

From benchflow-ai/skillsbench, Apache-2.0.

More from benchflow-ai/skillsbench