How to use the Gmail Job Lead Importer agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions and scripts that an AI agent can load and use when a request matches the skill's purpose. This skill is named career-ops-plugin-gmail and is licensed under MIT.

Once installed and configured, the agent can run a single command that reads emails under a Gmail label you choose. It pulls job posting links from emails that pass a sender-authenticity check (DMARC), filters out tracking and unsubscribe links, and passes each job's title, URL, company and location to the career-ops engine. The engine adds new entries to your pipeline and skips ones it already has. The skill also keeps a record of which emails it has processed so it does not reread them.

• Reads only emails under the Gmail label you configure
• Keeps only links from emails that pass DMARC
• Removes tracking and unsubscribe links
• Hands title, URL, company and location to career-ops

What you need before installing

This skill only feeds the career-ops pipeline, so you need career-ops already set up. It also needs Node.js, a Google OAuth Desktop client, and a Gmail refresh token. You also need a Gmail account with a labelled folder for job alerts.

• Node.js
• A career-ops installation with config/plugins.yml
• A Google OAuth Desktop client providing GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET
• A Gmail refresh token stored as GMAIL_REFRESH_TOKEN in .env
• A Gmail account with a labelled job-alert folder

How to install the skill

Download the ZIP from the directory page and unzip it. You can install it in one of two ways. For Claude Code, place the unzipped folder in ~/.claude/skills/ for all your projects, or in a project's .claude/skills/ folder for just that project. In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

The package contains four files: skill.md, manifest.json, index.mjs and _helpers.mjs.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How to set up Gmail access and the label

Put GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET and GMAIL_REFRESH_TOKEN in your .env file. The client is an OAuth Desktop client, and the refresh token comes from the consent flow. Then configure the label and how far back to look in config/plugins.yml.

• label sets the Gmail label to read, for example Job Leads
• days_back sets how many days of email to look through

How to run it and ask your agent

The underlying command is node plugins.mjs run gmail, which ingests new leads from the configured label. You can ask your agent in plain language, for example: "Check my Job Leads label for new job alerts and add them to the pipeline." The agent should use this skill when the request matches its purpose.

New jobs are written to the pipeline only after the engine checks them against what is already there, so duplicates are not added twice. Processed emails are tracked in data/gmail-state.json under your data root.

• Example request: "Pull this week's job leads from my Job Leads label."
• Example request: "Import new job alerts from Gmail into career-ops."
• Example request: "Run the Gmail lead import and tell me how many new jobs were added."

Safety notes: scripts and network access

This skill runs scripts and uses the network. It connects to Gmail using your OAuth credentials and reads email content under the label you set. Because it needs a refresh token with ongoing access, only use it if you are comfortable granting that access. Review the files in the package before installing, and keep your .env file private.

If you are not comfortable giving a tool access to your Gmail account, this skill is not a good fit. You can still gather job alerts manually and add them to career-ops yourself.

• Reads email content under the configured label
• Requires a refresh token with ongoing access
• Keep .env and GMAIL_REFRESH_TOKEN private

Tips for getting reliable results

Use a dedicated Gmail label so the skill reads only job alerts. Start with a small days_back value to test, then increase it if needed. Because the skill remembers processed messages, repeat runs only pick up new emails.

• Create a label used only for job alerts
• Start with a small days_back value
• Check data/gmail-state.json if you want to see what has been processed