How to use the OAuth and OIDC Expert agent skill

What the oauth-expert skill makes the agent do

Agent skills are folders of written instructions that an AI agent loads when a task matches them. The oauth-expert skill is a single SKILL.md file. When it is loaded, the agent answers questions and reviews designs for logging users in and granting app access using OAuth 2.0 and OpenID Connect.

The guidance steers toward current practice: Authorization Code flow with PKCE for public clients such as SPAs, mobile apps and CLI tools, short-lived access tokens, careful JWT validation, safe token storage, and the Backend-for-Frontend (BFF) pattern for single-page apps. It also covers scope design, refresh token handling, token revocation, multi-tenant identity, step-up authentication, token exchange (RFC 8693) and the device authorization flow.

• It works from written guidance only.
• It does not connect to any identity provider.
• It does not change your code by itself.

Install the oauth-expert skill

Download the ZIP for this skill from this page. The skill is distributed as a folder containing SKILL.md, so you can use it in either of two ways.

For Claude Code, unzip the download into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want it only for that project.

In the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills

Trigger the skill with natural requests

You do not need a special command. Describe the auth problem in plain language that mentions OAuth, OIDC, PKCE, tokens or login, and the agent can match the request to the skill. Give context such as the app type (SPA, mobile, server, CLI) and the identity provider if you have one, because the guidance depends on the client type.

The skill is strongest on design questions and reviews, so describe what your code or plan currently does and ask what to change.

• "Which OAuth flow should my React SPA use to log users in?"
• "Review this token refresh logic for security problems."
• "How should my mobile app store refresh tokens?"
• "Design a service-to-service token flow where the backend calls our orders API for a user."
• "Check whether my JWT validation covers issuer, audience and expiry."

Examples of what you get back

For a single-page app, the skill points toward the BFF pattern: the BFF server runs the OAuth flow and keeps tokens in HTTP-only cookies so tokens stay out of JavaScript. For a mobile or CLI client, it steers toward Authorization Code with PKCE, explaining that you generate a random code_verifier, derive the code_challenge with S256, send the challenge in the authorize request and the verifier in the token exchange.

For a review, the skill checks against its pitfalls list: tokens in localStorage, a missing state parameter, JWTs accepted without an audience check, and custom token formats instead of standard JWT libraries and specifications.

What the skill needs and how it runs

The skill lists no requirements. It runs no scripts and uses no network access, so it does not call an identity provider, fetch a discovery document or send your data anywhere. Everything it does is reasoning over the text you give it and its own instructions.

Because it is guidance rather than a library, you still write, test and deploy the code yourself, using well-tested JWT and OAuth/OIDC libraries.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no
• Files: SKILL.md

Safety notes

Because the skill runs no scripts and makes no network calls, the main safety question is whether its advice fits your system. The guidance is general. It does not know your identity provider's settings, your threat model or your regulatory needs.

Treat its output as a checklist to verify, not as a sign-off. For production systems, have a security review of your actual configuration.

• Verify token lifetimes, rotation and revocation against your identity provider's documentation.
• Test JWT validation with real and forged tokens before relying on it.
• Do not paste live secrets, client secrets or production tokens into the chat.

Tips for better results

Be specific about the client type and where tokens currently live. Ask for a review of one flow at a time, and include the relevant code or a sequence of requests so the agent can point to exact problems.

• State whether the app is public (SPA, mobile, CLI) or confidential (server-side).
• Name the grant or flow you are using now.
• Ask for the reasoning behind each recommendation so you can check it.