⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

auth

benja-pauls@benja-pauls⭐ 2 stars· last commit 7mo ago· 0 open issues

Understand and customize authentication in this project. Use when: adding auth to routes, swapping auth providers (Clerk, Auth0, custom SSO), debugging auth issues, or understanding the UserInfo contract and get_current_user dependency.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐ 2 on GitHubGitHub ↗

New / niche

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

SerpentStack


Agent skills are how Stripe merges 1,300+ agent-generated PRs per week and Shopify operates with agents as a core part of engineering. But skills are scattered across registries with no unified way to find or install them.

SerpentStack searches every major skill registry and MCP server directory at once — Anthropic, skills.sh, awesome-agent-skills, public GitHub, and the MCP Registry — with a single command. One CLI to search, install, and manage skills and discover MCP servers for any AI coding agent.

npm install -g serpentstack

Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf, and any tool that reads the Agent Skills open standard. Zero dependencies. Requires Node 22+.


Why SerpentStack?

Skills and MCP servers are scattered across isolated registries. There's no unified way to find what exists.

skills.shAnthropicawesome-agent-skillsGlamamcp.soSerpentStack
Skills:white_check_mark::white_check_mark::white_check_mark::white_check_mark: all
MCP servers:white_check_mark::white_check_mark::white_check_mark: all
Single CLI search:white_check_mark:
Install from any source:white_check_mark:
Project-aware recommendations:white_check_mark:
Auto-generate missing skills:white_check_mark:

One search, every source. Skills and MCP servers together, clearly labeled.


Quick Start

serpentstack search "react testing"        # search every registry
serpentstack add clerk                     # install by name
serpentstack add stripe/agent-toolkit      # install from a GitHub repo
serpentstack discover                      # get recommendations for your project

That's it. Skills are installed to .skills/<name>/SKILL.md and your agents pick them up automatically.


Search

Search across all major skill registries and MCP server directories with one command. Results are ranked by relevance, clearly split into Skills and MCP Servers so you always know what you're looking at.

serpentstack search "auth oauth"
serpentstack search "stripe payments"
serpentstack search "postgres database"
serpentstack search "docker deploy"
  ── Skills (3) ──────────────────────────────────────

   1. clerk  anthropic
      Authentication and user management with Clerk
      $ serpentstack add anthropics/skills/clerk

   2. better-auth  skills.sh
      Type-safe authentication framework for TypeScript
      $ serpentstack add better-auth/best-practices

   3. oauth-patterns  awesome
      OAuth 2.0 and OpenID Connect integration patterns
      $ serpentstack add nichochar/oauth-patterns

  ── MCP Servers (2) ─────────────────────────────────

   1. supabase  mcp
      Manage Supabase projects, databases, edge functions, and auth
      Claude Code: claude mcp add supabase -- npx -y supabase-mcp-server
      Docs:        github.com/supabase-community/supabase-mcp

   2. neon  mcp
      Serverless Postgres with branching, schema migrations, and database management
      Claude Code: claude mcp add --transport http neon https://mcp.neon.tech/sse
      Docs:        github.com/neondatabase/mcp-server-neon

Skills and MCP servers are clearly labeled: anthropic skills.sh awesome github for skills, mcp for MCP servers. Skills teach agents how to build; MCP servers give agents tools to use — you often want both.


Install

Install skills from any source — a registry name, a GitHub repo, or a URL. SerpentStack resolves the source, fetches the SKILL.md, and drops it into your .skills/ directory.

serpentstack add clerk                           # resolve via registries
serpentstack add anthropics/skills/clerk          # specific GitHub path
serpentstack add stripe/agent-toolkit             # GitHub repo
serpentstack add --force clerk                    # overwrite existing

If no community skill exists, SerpentStack auto-generates a context-rich stub by pulling the project's README, package metadata, install commands, and docs URL from GitHub. You get a useful starting point instead of nothing.

serpentstack add fastify
# → Generated fastify → .skills/fastify/SKILL.md
#   Source: github.com/fastify/fastify
#   Docs:   fastify.dev

Discover

Analyze your project and get skill and MCP server recommendations tailored to your actual stack. SerpentStack reads your dependency files, detects frameworks/services/tools, and searches registries for matching skills and MCP servers — skipping skills you already have installed.

cd your-project
serpentstack discover
  Your stack
  Languages:    javascript, typescript
  Frameworks:   react, nextjs
  Services:     clerk, stripe, prisma
  Tools:        vitest, tailwindcss, eslint

  ── Services ────────────────────────────────────────
  clerk  anthropic
  $ serpentstack add anthropics/skills/clerk

  stripe-best-practices  skills.sh
  $ serpentstack add stripe/agent-toolkit
  ...

  ── MCP Servers (3) ─────────────────────────────────
  stripe  mcp
  $ claude mcp add stripe -- npx -y @stripe/mcp

  neon  mcp
  $ claude mcp add --transport http neon https://mcp.neon.tech/sse
  ...

  12 skill recommendations, 3 MCP servers based on your stack.
  3 skills already installed.

Detects: JavaScript/TypeScript, Python, Go, Rust, Ruby — and 50+ frameworks, services, and tools within each.


Base Skills

SerpentStack ships 10 production-quality skills you can install into any project. These aren't descriptions — they contain complete, copy-paste templates with real imports and type signatures. Every skill ends with a verification step so agents can confirm their own work.

serpentstack skills                     # install all 10 base skills
serpentstack skills update              # update to latest versions
SkillWhat it teaches agents
scaffoldEnd-to-end resource generation: model, schema, service, route, migration, tests, frontend types
authJWT, owners

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .skills/auth/SKILL.md6.3 KBa93db09c3186upstream ↗
    ---
    name: auth
    description: "Understand and customize authentication in this project. Use when: adding auth to routes, swapping auth providers (Clerk, Auth0, custom SSO), debugging auth issues, or understanding the UserInfo contract and get_current_user dependency."
    ---
    
    # Auth
    
    SerpentStack ships with working local JWT authentication (register, login, token validation). This skill explains the auth architecture and how to swap providers.
    
    ## How Auth Works (Built-in)
    
    ### Architecture
    
    ```
    POST /api/v1/auth/register  →  UserService.register()  →  bcrypt hash  →  DB  →  JWT
    POST /api/v1/auth/login     →  UserService.authenticate()  →  verify hash  →  JWT
    GET  /api/v1/auth/me        →  get_current_user dependency  →  decode JWT  →  UserResponse
    
    Any protected route:
        @router.delete("/{id}")
        async def delete(user: UserInfo = Depends(get_current_user)):
            # user.user_id, user.email available here
    ```
    
    ### Key Files
    
    | File | Role |
    |---|---|
    | `backend/app/routes/auth.py` | Auth routes + `get_current_user` dependency |
    | `backend/app/services/user.py` | Registration, authentication, password hashing |
    | `backend/app/models/user.py` | User SQLAlchemy model (email, hashed_password) |
    | `backend/app/schemas/user.py` | Request/response schemas (register, login, token) |
    | `backend/app/middleware/auth.py` | Optional global auth middleware (not enabled by default) |
    
    ### The `UserInfo` Contract
    
    All protected routes receive a `UserInfo` object via dependency injection:
    
    ```python
    class UserInfo(BaseModel):
        user_id: str
        email: str | None = None
        name: str | None = None
        raw_claims: dict[str, Any] = {}
    ```
    
    **This is the interface between auth and the rest of the app.** When swapping providers, keep this shape — every route that uses `Depends(get_current_user)` depends on it.
    
    ## Protecting a Route
    
    Add `Depends(get_current_user)` to any route that requires authentication:
    
    ```python
    from app.routes.auth import UserInfo, get_current_user
    
    @router.post("")
    async def create_thing(
        payload: ThingCreate,
        user: UserInfo = Depends(get_current_user),  # ← requires valid JWT
        db: AsyncSession = Depends(get_db),
        service: ThingService = Depends(get_thing_service),
    ) -> ThingResponse:
        thing = await service.create(payload, owner_id=user.user_id)
        await db.commit()
        return ThingResponse.model_validate(thing)
    ```
    
    For optional auth (authenticated if token present, anonymous otherwise):
    
    ```python
    from app.routes.auth import get_optional_user
    
    @router.get("")
    async def list_things(
        user: UserInfo | None = Depends(get_optional_user),
    ) -> list[ThingResponse]:
        # user is None if no token, UserInfo if authenticated
        ...
    ```
    
    ## Swapping to an External Provider
    
    To replace the built-in JWT auth with Clerk, Auth0, or another provider:
    
    ### Step 1: Replace `get_current_user` in `routes/auth.py`
    
    The **only function you need to change** is `get_current_user`. Replace JWT decode with your provider's token validation:
    
    **For Clerk** — see [Clerk FastAPI guide](https://clerk.com/docs/references/fastapi/overview):
    ```python
    from jwt import PyJWKClient
    
    jwks_client = PyJWKClient("https://your-clerk-domain/.well-known/jwks.json")
    
    async def get_current_user(
        credentials: HTTPAuthorizationCredentials | None = Security(bearer_scheme),
    ) -> UserInfo:
        if credentials is None:
            raise HTTPException(status_code=401, detail="Not authenticated")
    
        token = credentials.credentials
        signing_key = jwks_client.get_signing_key_from_jwt(token)
        payload = jwt.decode(token, signing_key.key, algorithms=["RS256"])
    
        return UserInfo(
            user_id=payload["sub"],
            email=payload.get("email"),
            name=payload.get("name"),
            raw_claims=payload,
        )
    ```
    
    **For Auth0** — see [Auth0 FastAPI guide](https://auth0.com/docs/quickstart/backend/python/01-authorization):
    ```python
    jwks_client = PyJWKClient("https://your-tenant.auth0.com/.well-known/jwks.json")
    
    async def get_current_user(...) -> UserInfo:
        # Same pattern, add audience validation:
        payload = jwt.decode(
            token, signing_key.key, algorithms=["RS256"],
            audience="your-api-audience",
            issuer="https://your-tenant.auth0.com/",
        )
        return UserInfo(user_id=payload["sub"], email=payload.get("email"), ...)
    ```
    
    ### Step 2: Remove unused files (optional)
    
    If you no longer need local registration/login:
    - Remove `backend/app/services/user.py`
    - Remove `backend/app/models/user.py` (and its import in `models/__init__.py`)
    - Remove `backend/app/schemas/user.py`
    - Remove the `/register` and `/login` routes from `routes/auth.py`
    - Remove `passlib[bcrypt]` from `pyproject.toml`
    
    ### Step 3: Update environment variables
    
    Add your provider's config to `.env`:
    ```bash
    # For Clerk:
    CLERK_JWKS_URL=https://your-clerk-domain/.well-known/jwks.json
    
    # For Auth0:
    AUTH0_DOMAIN=your-tenant.auth0.com
    AUTH0_AUDIENCE=your-api-audience
    ```
    
    ### What stays the same
    
    - `UserInfo` shape — all routes keep working
    - `Depends(get_current_user)` pattern — no route changes needed
    - `get_optional_user` — works with any provider
    - Frontend token storage pattern — still sends `Authorization: Bearer <token>`
    
    ## Testing Auth
    
    ```bash
    # Register a user
    curl -X POST http://localhost:8000/api/v1/auth/register \
      -H "Content-Type: application/json" \
      -d '{"email": "[email protected]", "password": "testpass123"}'
    
    # Login
    curl -X POST http://localhost:8000/api/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{"email": "[email protected]", "password": "testpass123"}'
    
    # Use the token
    TOKEN="<access_token from login response>"
    curl http://localhost:8000/api/v1/auth/me \
      -H "Authorization: Bearer $TOKEN"
    
    # Protected route (delete item)
    curl -X DELETE http://localhost:8000/api/v1/items/<item-id> \
      -H "Authorization: Bearer $TOKEN"
    ```
    
    ## Troubleshooting
    
    | Problem | Cause | Fix |
    |---|---|---|
    | 401 on every request | Missing or malformed `Authorization: Bearer <token>` header | Check header format, ensure token isn't expired |
    | 422 on register | Password too short or invalid email | Password must be ≥8 chars, email must be valid |
    | 409 on register | Email already taken | Use a different email or login instead |
    | `jwt.InvalidTokenError` in logs | Token signed with wrong key or expired | Check `SECRET_KEY` matches between token creation and validation |
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/benja-pauls-serpentstack-skills-auth.md

// REPO STATS

2 stars
0 open issues
Last commit: 7mo ago