SkillCompiler/data/skills-bench/tasks-extra/scheduling-email-assistant/environment/skills/gmail-skill/docs/google-cloud-setup.md

Google Cloud OAuth Setup Guide

Complete guide to setting up Google Cloud credentials for Gmail API access.

Prerequisites

• Google account (Gmail)
• Web browser
• Terminal access

Step-by-Step Setup

1. Create Google Cloud Project

1. Go to Google Cloud Console
2. Sign in with your Google account
3. Click the project dropdown at the top
4. Click "New Project"
5. Enter project name (e.g., "Claude Gmail Integration")
6. Click "Create"
7. Wait for project creation (you'll see a notification)
8. Select your new project from the dropdown

2. Enable Gmail API

1. In the Google Cloud Console, click the hamburger menu (☰)
2. Navigate to "APIs & Services" → "Library"
3. Search for "Gmail API"
4. Click on "Gmail API"
5. Click the "Enable" button
6. Wait for API to be enabled

3. Configure OAuth Consent Screen

1. In the left sidebar, click "OAuth consent screen"
2. Select "External" user type
3. Click "Create"

Fill in App Information:

• App name: Claude Gmail Skill (or your preferred name)
• User support email: Your email address
• Developer contact email: Your email address

4. Click "Save and Continue"

Scopes: 5. Click "Add or Remove Scopes" 6. Search for gmail in the filter 7. Select: https://www.googleapis.com/auth/gmail.modify

• This scope allows read, send, and modify (but not delete) emails

8. Click "Update"
9. Click "Save and Continue"

Test Users: 10. Click "Add Users" 11. Add your Gmail address 12. Click "Add" 13. Click "Save and Continue"

Summary: 14. Review the information 15. Click "Back to Dashboard"

4. Create OAuth Credentials

1. In the left sidebar, click "Credentials"
2. Click "+ Create Credentials" at the top
3. Select "OAuth client ID"

Configure OAuth Client: 4. Application type: Select "Desktop app" 5. Name: Claude Gmail Client (or your preferred name) 6. Click "Create"

Download Credentials: 7. A dialog will appear with your Client ID and Secret 8. Click "Download JSON" 9. Save the file as credentials.json

5. Save Credentials to Skill

1. Move the downloaded file to the skill's auth directory:

mv ~/Downloads/credentials.json ~/.claude/skills/gmail-skill/scripts/auth/credentials.json

2. Verify the file is in the correct location:

ls -la ~/.claude/skills/gmail-skill/scripts/auth/credentials.json

You should see the file listed.

6. Install Dependencies

cd ~/.claude/skills/gmail-skill
npm install

7. Run OAuth Setup

npm run setup

This will:

1. Open your browser automatically
2. Ask you to sign in to Google
3. Show a consent screen asking for Gmail permissions
4. Redirect to localhost (you'll see a success message)
5. Save the OAuth token to scripts/auth/token.json

Important Security Notes:

• Click "Continue" when you see the "App isn't verified" warning (this is expected for personal projects)
• Review the permissions carefully - you're granting access to your Gmail
• The token is stored locally on your machine only

8. Verify Setup

Test that everything works:

cd ~/.claude/skills/gmail-skill/scripts
node gmail-search.js --query "is:inbox" --limit 1

You should see JSON output with one email from your inbox.

Troubleshooting

"App isn't verified" Warning

Problem: Google shows a warning that the app isn't verified.

Solution: This is normal for personal projects. Click "Advanced" → "Go to [App Name] (unsafe)" → "Continue".

"Access blocked: This app's request is invalid"

Problem: OAuth consent screen not configured correctly.

Solution:

1. Go to OAuth consent screen
2. Ensure you added your email as a test user
3. Ensure Gmail API scope is added
4. Try authentication again

"Token not found" Error

Problem: OAuth setup didn't complete successfully.

Solution:

1. Check that credentials.json exists in scripts/auth/
2. Run npm run setup again
3. Complete the browser authentication flow
4. Verify token.json was created in scripts/auth/

"The user has not granted the app" Error

Problem: Gmail API scope wasn't granted during OAuth flow.

Solution:

1. Delete scripts/auth/token.json
2. Run npm run setup again
3. Carefully review permissions and click "Allow"

"Invalid client" Error

Problem: credentials.json is corrupted or incorrect.

Solution:

1. Go back to Google Cloud Console
2. Download credentials again
3. Replace scripts/auth/credentials.json
4. Run npm run setup again

Security Best Practices

1. Never commit credentials:

   • credentials.json and token.json are in .gitignore
   • Never share these files publicly

2. Token refresh:

   • Tokens expire periodically
   • Refresh by running npm run setup again

3. Revoke access:

   • Go to Google Account Security
   • Find your app and click "Remove Access"

4. Limit scope:

   • The skill uses gmail.modify scope (read/send/modify)
   • This does NOT allow permanent email deletion
   • This is the minimum scope needed for full functionality

Additional Resources

• Gmail API Documentation
• OAuth 2.0 for Desktop Apps
• Gmail API Scopes

Next Steps

Once setup is complete:

1. Read the main README.md for usage examples
2. Try sending a test email
3. Explore the search functionality
4. Set up labels and drafts as needed

The skill is now ready to use with Claude Code!