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

Google Cloud OAuth Setup Guide

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

Prerequisites

• Google account
• 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 Calendar Integration")
6. Click "Create"
7. Wait for project creation (you'll see a notification)
8. Select your new project from the dropdown

2. Enable Google Calendar API

1. In the Google Cloud Console, click the hamburger menu (☰)
2. Navigate to "APIs & Services" → "Library"
3. Search for "Google Calendar API"
4. Click on "Google Calendar 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 Calendar 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 calendar in the filter 7. Select: https://www.googleapis.com/auth/calendar

• This scope allows full read/write access to calendars and events

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

Test Users: 10. Click "Add Users" 11. Add your Google account email 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 Calendar 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/google-calendar-skill/scripts/auth/credentials.json

2. Verify the file is in the correct location:

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

You should see the file listed.

6. Install Dependencies

cd ~/.claude/skills/google-calendar-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 Calendar 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 Google Calendar
• The token is stored locally on your machine only

8. Verify Setup

Test that everything works:

cd ~/.claude/skills/google-calendar-skill/scripts
node calendar-list.js

You should see JSON output with your calendars.

Test listing events:

node calendar-events-list.js --limit 5

You should see JSON output with upcoming calendar events.

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 Google Calendar 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: Calendar 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

"Calendar API has not been used" Error

Problem: Calendar API is not enabled for your project.

Solution:

1. Go to Google Cloud Console
2. Navigate to APIs & Services → Library
3. Search for "Google Calendar API"
4. Click "Enable"
5. Try authentication again

Security Best Practices

1. Never commit credentials:

   • credentials.json and token.json should never be shared
   • Add them to .gitignore if using version control

2. Token refresh:

   • Tokens are long-lived but may expire
   • Refresh by running npm run setup again if needed

3. Revoke access:

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

4. Scope explanation:

   • The skill uses calendar scope (full read/write access)
   • This allows creating, updating, and deleting calendar events
   • This is the minimum scope needed for full functionality

Additional Resources

• Google Calendar API Documentation
• OAuth 2.0 for Desktop Apps
• Calendar API Scopes

Next Steps

Once setup is complete:

1. Read the main README.md for usage examples
2. Try listing your calendars and events
3. Create a test event
4. Explore search and update functionality

The skill is now ready to use with Claude Code!