Guide · Agent skill
How to use the OAuth account connection agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The oauth-setup skill teaches an AI agent how to connect an external OAuth 2.0 account, such as Gmail or another Google API, to itself. You approve access on the provider's own site, and the agent keeps the resulting tokens in an encrypted credential store instead of a plain file. This guide explains what the skill does, how to install it, how to trigger it, and what it needs before you start.
OAuth account connectionspinabot/brigade · MIT Download the skill Quick start
- 1Create a Desktop-app OAuth client. In Google Cloud Console, enable the Gmail API and create an OAuth client ID with Application type set to Desktop app. Set the consent screen to Testing and add your account as a test user.
- 2Install the skill. Download the ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder, or upload the ZIP under Settings, Capabilities, Skills.
- 3Ask the agent to connect your account. Make a plain request such as connecting your Gmail account, and provide the client ID and client secret when asked.
- 4Click the authorization link. The agent returns an authUrl. Open it and approve access on Google's site.
- 5Confirm the connection. Ask the agent to await the flow. If it reports pending, click the link first and then ask again.
- 6Check the connected accounts. Ask the agent for status to confirm the provider, email, scopes, and expiry.
What an agent skill is and what this one does
An agent skill is a folder containing a SKILL.md file that gives an AI agent instructions for a specific task. The agent reads the file when a request matches the skill's description. This skill is named oauth-setup and ships as a single file, SKILL.md.
Its job is to connect an account. The agent uses the built-in oauth_authorize tool to produce a link you click, captures the approval code automatically through a temporary local listener, and stores the tokens sealed in the credential store. Afterwards the agent can call the connected service, for example to send email, without you pasting a password into the chat.
Install the oauth-setup skill
Download the ZIP from the skill's page on this site and unzip it. Then place the oauth-setup folder in one of two locations: ~/.claude/skills/ to make it available to you across projects, or a project's .claude/skills/ folder to limit it to that project.
You can also upload the ZIP in the Claude apps. Go to Settings, then Capabilities, then Skills, and add the file there.
- Personal install: ~/.claude/skills/oauth-setup
- Project install: .claude/skills/oauth-setup inside your project
Prepare a Google OAuth client
Before the agent can start a flow, you need a Google Cloud project with the Gmail API enabled and an OAuth client ID. In Google Cloud Console, go to Credentials, choose Create OAuth client ID, and set Application type to Desktop app. Desktop clients accept a loopback redirect on 127.0.0.1 without you registering the redirect URI in advance. A Web client requires that exact URI to be registered, which is what causes redirect_uri_mismatch errors.
Set the consent screen to Testing and add your own Google account as a test user. Then give the agent the client ID and client secret in the chat.
- Application type must be Desktop app, not Web client
- Gmail API enabled in the project
- Consent screen in Testing, with your account added as a test user
Trigger the skill with a natural request
You do not need special syntax. Ask the agent in plain language whenever you want to connect an account. The skill's description covers requests to connect Gmail, a Google API, or any OAuth account.
The agent will then ask for the client ID and secret if it does not have them, start the flow, and send you a link to click.
- "Connect my Gmail account so you can send emails for me."
- "Set up OAuth for the Google Calendar API on my account."
- "Check which accounts are connected."
Understand the authorization flow
The agent starts the flow with the oauth_authorize tool, using the action start. It passes the provider endpoints, client credentials, and scopes. The skill uses the Gmail send scope https://www.googleapis.com/auth/gmail.send, and adds openid and the userinfo email scope if the account address should be filled in automatically. It also requests offline access and a consent prompt, which are needed to receive a refresh token.
The agent sends you the returned authUrl. After you approve on Google's site, the agent calls await with the flow ID. If the status is pending, you have not clicked yet, and the agent will ask you to click and then check again.
oauth_authorize({ action: "start", provider: "google-gmail", ... })
oauth_authorize({ action: "await", flowId: "<flowId from start>" })Use a connected account to send mail
Once connected, the agent can check what is linked with the status action, which lists each account's provider, email, scopes, and expiry without exposing secrets. To call the API, it requests a token with the token action. That returns a live access token, refreshing it from the sealed refresh token when needed.
The agent then calls the Gmail send endpoint with the token in a Bearer header. The skill says the agent must never read the credential store directly or attempt its own refresh, because the token action is the only supported retrieval path.
- status: lists connected accounts without secrets
- token: returns a usable access token and refreshes it if expired
- Gmail send: POST to the messages/send endpoint with a base64url RFC-822 message
oauth_authorize({ action: "status" })
oauth_authorize({ action: "token", provider: "google-gmail" })Safety notes: scripts and network access
This skill does not run scripts. It does use the network, because it contacts Google's authorization, token, and userinfo endpoints and calls the Gmail API.
Approving access gives the agent ongoing ability to act on the connected account, including sending email. Only connect accounts you are comfortable with the agent using. Client credentials are passed through the chat, so do not use this setup if the Google Cloud project or client secret is shared with people you do not trust.
- No scripts are run by this skill
- Network access is used for Google's OAuth endpoints and the Gmail API
- Tokens stay in the sealed credential store
What people use it for
- Letting an agent send email from your Gmail account without pasting your password into the chat.
- Connecting a Google API so an agent can call it on a user's behalf, as an operator setting up a Brigade-style agent.
- Keeping OAuth tokens sealed in a credential store for a team instead of in config files.
- Checking which accounts an agent is connected to and when their access expires.
Frequently asked questions
How do I install the oauth-setup agent skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, Capabilities, Skills.
What do I need to use this skill?
You need the Brigade agent runtime with the built-in oauth_authorize tool, a Google Cloud project with the Gmail API enabled, and a Desktop-app OAuth client ID and secret. The Google account must be authorized with the consent screen set to Testing and the account added as a test user.
Why do I need a Desktop app client instead of a Web client?
Desktop clients accept any http://127.0.0.1 loopback redirect without pre-registering the redirect URI. A Web client requires that exact URI to be registered, which is what causes redirect_uri_mismatch errors.
Is the oauth-setup skill free?
The skill is published under the MIT licence. This source does not state any price, so check the directory page for current terms.
Does the agent store my Gmail password?
No. You approve access on Google's site, and the agent stores the resulting tokens in an encrypted credential store rather than in a plain file or in the chat.
What if the connection says pending or fails?
Pending means you have not clicked the authorization link yet, so click it and then ask the agent to check again. A redirect_uri_mismatch error usually means the OAuth client is a Web client rather than a Desktop app.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
This skill suits developers and operators who want an agent to send email or call Google APIs on a user's behalf, with tokens kept sealed rather than in config files. It is not a fit if you do not want an agent holding ongoing access to your email, or if your client secret is shared with untrusted people. For API-key-only services, pick a different approach, since this skill covers the OAuth 2.0 flow.
Download the skill