Preface

Almost every web project encounters requirements such as login, registration, OAuth third-party authorization, session management, and route protection. In the Next.js ecosystem, Auth.js (formerly NextAuth.js) has become the mainstream solution. However, its official documentation covers multiple links including dependency installation, key generation, provider configuration, Route Handlers, and Server Component authentication, which makes it easy for beginners to miss steps or misconfigure environment variables.

adding-auth is a workflow instruction from the community skill list awesome-cursor-skills. It encapsulates the integration steps of Auth.js v5 under the Next.js App Router into a reusable SKILL.md. When you say “add login to the project”, “connect GitHub OAuth”, or “protect a certain page” in AI programming tools like Cursor or Codex CLI, the Agent will execute the 8-step checklist in the Skill instead of exploring the documentation from scratch.

What is this

adding-auth is an Agent Skill configuration file maintained at spencerpauly/awesome-cursor-skills/resources/adding-auth, curated and收录 by the community, and not officially produced by Auth.js.

Its positioning is very clear: when users put forward requirements related to authentication, login, registration, OAuth, session management, guide the AI to complete the integration using NextAuth.js (Auth.js v5), covering OAuth provider configuration, session read/write and route protection. The main text of the Skill is highly consistent with the steps in the Auth.js official installation documentation, which belongs to the type of “translating official best practices into an executable checklist for Agents”.

Core Features and Highlights

After cross-verifying with the official SKILL.md and Auth.js documentation, this Skill covers the following capabilities:

  1. Dependencies and Environment: Install next-auth@beta, use npx auth secret to generate and write AUTH_SECRET (the only required environment variable for Auth.js v5).
  2. Centralized Configuration: Create auth.ts at the project root, export Next.js integrated APIs such as handlers, signIn, signOut, and auth.
  3. App Router Routing: Mount GET/POST handlers at app/api/auth/[...nextauth]/route.ts.
  4. OAuth Providers: Built-in GitHub and Google examples, with environment variables using the AUTH_ prefix such as AUTH_GITHUB_ID and AUTH_GITHUB_SECRET, which can be automatically inferred by Auth.js.
  5. Login UI: Guide the creation of components that call signIn / signOut, or use built-in methods like <SignIn />.
  6. Route Protection: Call auth() in Server Components or Middleware, and redirect to the login page when not logged in.
  7. Optional Persistence: When a database is needed to store users or sessions, you can connect official Adapters such as @auth/drizzle-adapter and @auth/prisma-adapter.
  8. Dual Routing Mode Explanation: Use auth() for App Router; Pages Router can still use getServerSession and useSession.

The value of the Skill lies in: authentication is a rigid demand for web projects, but Auth.js has many configuration items and breaking changes in the version migration (v4 → v5). After固化 the steps, the Agent will not easily skip key generation or miss writing the Route Handler, which is especially friendly for beginners.

Installation and Activation

The Skill uses the universal SKILL.md format and can be used in a variety of AI programming tools. The following methods are from official or community documents, and you can choose any one of them.

Method 1: Manual Copy (Compatible with All Cursor Versions)

The awesome-cursor-skills README states: Skills should be placed in .cursor/skills/ (user-level) or .cursor/skills/ within the project, and the Agent will automatically discover them.

# Execute at the project root or user directory
mkdir -p .cursor/skills/adding-auth
curl -o .cursor/skills/adding-auth/SKILL.md \
  https://raw.githubusercontent.com/spencerpauly/awesome-cursor-skills/main/resources/adding-auth/SKILL.md

Method 2: Skills CLI (One-click Installation for Multiple Agents)

Vercel Skills CLI supports installing specified Skills from GitHub repositories to Cursor, Codex, etc.:

# List available Skills in the repository
npx skills add spencerpauly/awesome-cursor-skills --list

# Only install adding-auth and specify Cursor
npx skills add spencerpauly/awesome-cursor-skills --skill adding-auth -a cursor

# Install to Codex CLI at the same time
npx skills add spencerpauly/awesome-cursor-skills --skill adding-auth -a codex

The default Skill directory for Codex CLI is ~/.codex/skills/, and for Cursor is ~/.cursor/skills/ or the project’s .cursor/skills/ (subject to CLI detection).

Method 3: Codex Built-in $skill-installer

In the Codex session, you can use the built-in installer to pull Skill directories from GitHub (applicable to OpenAI official skill libraries and custom repository URLs). If the community Skill is not included in the OpenAI curated list, you can try to provide the complete GitHub path for installation; restart Codex after installation to load the new Skill.

No additional “switch” is required after installation: the Agent will automatically load the complete instructions when the task matches according to the description in the SKILL.md frontmatter.

Typical Usage Examples

Trigger Method

The Skill declares that it should be called in the following scenarios—you only need to describe the requirements in natural language:

  • “Add GitHub login to this Next.js project”
  • “Connect Google OAuth and protect the /dashboard page”
  • “Implement a logout button and session management”

In Cursor, you can also explicitly reference @adding-auth or /skills in the conversation (the specific entry depends on the current Cursor version).

Integration Flow the Agent Will Execute

The following steps are excerpted from the original Skill and are consistent with the Auth.js installation guide, which is convenient for you to check whether the Agent’s output meets expectations.

1. Install Dependencies

npm install next-auth@beta

2. Generate Secret Key

npx auth secret

This command will write AUTH_SECRET into .env.local.

3. Create auth.ts

import NextAuth from "next-auth";
import GitHub from "next-auth/providers/github";
import Google from "next-auth/providers/google";

export const { handlers, signIn, signOut, auth } = NextAuth({
  providers: [GitHub, Google],
});

4. Add Route Handler

At app/api/auth/[...nextauth]/route.ts:

import { handlers } from "@/auth";
export const { GET, POST } = handlers;

5. Configure Environment Variables

AUTH_SECRET=...
AUTH_GITHUB_ID=...
AUTH_GITHUB_SECRET=...
AUTH_GOOGLE_ID=...
AUTH_GOOGLE_SECRET=...

6. Add Login/Logout UI

Create Server Actions or client components that call signIn and signOut.

7. Protect Routes

import { auth } from "@/auth";
import { redirect } from "next/navigation";

export default async function ProtectedPage() {
  const session = await auth();
  if (!session) redirect("/api/auth/signin");
  return <div>Welcome {session.user?.name}</div>;
}

8. (Optional) Database Adapter

When you need to persist users or sessions, install the corresponding Adapter and configure it in NextAuth({ ... }).

Applicable Scenarios and Notes

Who It Is Suitable For

  • Developers using Next.js App Router (or hybrid projects in the process of gradual migration) who want to quickly access OAuth login.
  • Teams that are already using Agents like Cursor / Codex and want to turn “adding authentication” into a repeatable standard operation to reduce missing environment variable configurations.
  • Teams that need common OAuth services such as GitHub and Google, or expand providers like Credentials and Email on this basis.

Usage Restrictions and Notes

  1. Version and Package Name: The Skill is targeted at Auth.js v5 (next-auth@beta). If the project is still on v4, the configuration method is different, and you need to refer to Migrating to v5 instead of mechanically applying this Skill.
  2. Environment Variable Naming: v5 recommends using the AUTH_ prefix; NEXTAUTH_SECRET and NEXTAUTH_URL can be omitted in most scenarios. If you encounter reverse proxy problems in the production environment, you can set AUTH_TRUST_HOST or AUTH_URL.
  3. Production Deployment: The Skill notes that you can add NEXTAUTH_URL; the official v5 documentation states that most platforms can automatically infer the Host, but the OAuth callback URL must be correctly registered in the Provider console (in the form of https://your-domain/api/auth/callback/github).
  4. Session Data: The Skill recommends that only the minimum necessary user information be stored in the Session, and complete data should be read from the database to avoid oversized JWT or sensitive field leaks.
  5. Pages Router: The Skill only briefly mentions getServerSession / useSession; pure Pages projects should refer to the official Auth.js Pages documentation, and manually correct the Agent’s output when necessary.
  6. Security: OAuth Client Secret and AUTH_SECRET should only be placed in environment variables, and should not be hard-coded into auth.ts or submitted to Git.

Summary

adding-auth splits the authentication integration of Auth.js v5 in Next.js into an 8-step executable checklist, which is suitable as a standard playbook for AI programming assistants to handle “adding login, OAuth, session, and route protection”. It does not change the capability boundary of Auth.js itself, but reduces the omission rate during Agent integration, which is particularly practical for web projects with rigid authentication needs.

Official Skill address: https://github.com/spencerpauly/awesome-cursor-skills/tree/main/resources/adding-auth

Auth.js official documentation: https://authjs.dev