Agent Skills

stubIdP ships two Agent Skills in skills/ — portable SKILL.md packages that teach a coding agent how to set up and drive stubIdP for OIDC/OAuth work: first-time local setup, headless E2E login, CI, Docker, dynamic client registration, and Cloudflare Workers, from a plain-language request instead of a typed command. The format is open, not tied to any single tool — Claude Code, Cursor, OpenCode, Codex, and other agents that load SKILL.md packages can all use them.

local-oidc-provider

First-time setup: getting a local OIDC provider running and wiring an app’s OIDC client to it. Reach for this when there’s no real IdP credentials yet, IAM is blocking provisioning, or dev needs to happen offline.

stubidp

Everything past first setup: headless/automated login for E2E suites (Playwright, Cypress), GitHub Actions/CI, Docker, dynamic client registration for shared test IdPs, and Cloudflare Workers deployment.

Install

npx skills (any agent)

npx skills is an open installer for SKILL.md packages — it detects which agent you’re running and drops the skill into that agent’s directory for you:

npx skills add cerberauth/stubidp --skill local-oidc-provider
npx skills add cerberauth/stubidp --skill stubidp

Claude Code (manual)

Claude Code auto-discovers skills from .claude/skills/ (project-level) or ~/.claude/skills/ (personal, all projects). A plain top-level skills/ directory — which is how these ship in the repo — isn’t picked up on its own.

Inside a stubidp checkout, symlink the repo’s skills/ directory in:

git clone https://github.com/cerberauth/stubidp.git
cd stubidp
ln -s ../skills .claude/skills

In any other project, copy the ones you want into your personal skills directory so they’re available everywhere:

git clone https://github.com/cerberauth/stubidp.git /tmp/stubidp
cp -r /tmp/stubidp/skills/local-oidc-provider \
      /tmp/stubidp/skills/stubidp \
      ~/.claude/skills/

Other agents (manual)

The skills are plain SKILL.md packages with no stubIdP-specific conventions — a name/description frontmatter header plus Markdown instructions, with a references/ subfolder the agent reads on demand. Check your agent’s docs for where it discovers SKILL.md files (often a configurable skills directory or a plugin/marketplace mechanism) and point it at the folders under skills/.

Either way, each skill assumes npx @cerberauth/stubidp can run (Node.js on PATH) — see Getting Started.

Example prompts

You say	Skill that fires	What happens
”I need a local OIDC provider to test login, no real IdP yet”	local-oidc-provider	Starts stubIdP with a redirect URI, wires up client ID/secret, points the app’s OIDC client config at it
”Set up better-auth / NextAuth against a fake IdP”	local-oidc-provider	Runs the matching --preset, returns the client config snippet
”Run stubIdP headless in my Playwright/Cypress suite”	stubidp	Configures skip-prompt auto-approval so the login redirect completes without UI interaction
”Add stubIdP to my GitHub Actions workflow”	stubidp	Adds a background-process step that starts stubIdP before the test job and tears it down after
”I need one shared test IdP multiple services can register against”	stubidp	Enables dynamic client registration (RFC 7591/7592) so services POST /register at runtime

Tip

Start with local-oidc-provider for first-run/first-wiring questions, and stubidp once the work moves to automation, CI, or a shared/persistent deployment. Both skills cross-reference each other, so an agent that only has one installed still gets pointed at the other when needed.

Under the hood

stubidp ships supporting reference material it reads on demand, beyond the SKILL.md itself:

• stubidp/references/cli-flags.md — the full CLI flag and environment variable reference
• stubidp/references/endpoints.md — the full OIDC discovery/authorization/token/JWKS endpoint reference

See the skills’ source on GitHub for the full triggering logic and decision tables each one follows.