robel-auth
Integrate and maintain Robelest Convex Auth in apps by always checking upstream before implementation. Use when adding auth setup, updating auth wiring, migrating between upstream patterns, or troubleshooting @robelest/convex-auth behavior across projects.
Best use case
robel-auth is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Integrate and maintain Robelest Convex Auth in apps by always checking upstream before implementation. Use when adding auth setup, updating auth wiring, migrating between upstream patterns, or troubleshooting @robelest/convex-auth behavior across projects.
Teams using robel-auth should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/robel-auth/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How robel-auth Compares
| Feature / Agent | robel-auth | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Integrate and maintain Robelest Convex Auth in apps by always checking upstream before implementation. Use when adding auth setup, updating auth wiring, migrating between upstream patterns, or troubleshooting @robelest/convex-auth behavior across projects.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Robel auth skill Use this skill when a user asks to implement, update, or debug auth based on `robelest/convex-auth`. This skill is designed to be copied into other repos. ## Non negotiable upstream check before any auth change Run this every time before proposing code or commands. Preferred command: ```bash bash .cursor/skills/robel-auth/scripts/check-upstream.sh ``` Manual checklist if script is unavailable: 1. Read latest `main` README: - `https://raw.githubusercontent.com/robelest/convex-auth/main/README.md` 2. Read latest `release` README: - `https://raw.githubusercontent.com/robelest/convex-auth/release/README.md` 3. Check branch level differences: - `https://github.com/robelest/convex-auth/compare/release...main` 4. Read current self hosting docs if portal or static hosting is involved: - `https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md` - `https://github.com/get-convex/self-hosting` If `main` and `release` conflict, prefer the branch requested by the user. If unspecified, use `release` for stability and explain that choice. ## Important assumptions for this skill - Treat GitHub as source of truth every time. - Do not assume npm package availability. - Validate package availability at execution time. - If npm is unavailable, use a GitHub source install pinned to a branch or commit. - Keep all Convex code type safe and validator complete. ## Clarifying questions to ask first Ask these before editing: 1. Which branch is source of truth for this task, `release` or `main`. 2. Is this a new integration or an update to an existing auth setup. 3. Which framework is used, Vite, Next.js, Expo web, or other. 4. Is self hosted portal/static delivery needed now. 5. Are they okay pinning dependency to a specific Git commit for reproducibility. ## Install and dependency strategy Never assume one install path. 1. Try package registry lookup: - `npm view @robelest/convex-auth version` 2. If package is unavailable or blocked, install from GitHub: - `npm install github:robelest/convex-auth#release` 3. For deterministic builds, pin a commit SHA: - `npm install github:robelest/convex-auth#<commit-sha>` If the project uses pnpm or bun, translate the same GitHub dependency pinning pattern. ## GitHub OAuth setup instructions for end users When the user asks for clearer GitHub auth onboarding text, include this guidance in the README where OAuth providers are explained. Required link: - `https://github.com/settings/developers` Recommended README content: 1. Go to GitHub Developer Settings: - `https://github.com/settings/developers` 2. Create a new OAuth App. 3. Set: - Homepage URL = app frontend URL (same as `SITE_URL`) - Authorization callback URL = `https://<deployment>.convex.site/api/auth/callback/github` 4. Copy Client ID and Client Secret. 5. Set Convex env vars: - `AUTH_GITHUB_ID` - `AUTH_GITHUB_SECRET` 6. Confirm `SITE_URL` is configured. 7. Deploy and test sign in. Important implementation note for this repo: - GitHub auth should be documented with callback path `/api/auth/callback/github`. - In this codebase, GitHub OAuth is conditionally enabled only when `AUTH_GITHUB_ID`, `AUTH_GITHUB_SECRET`, and `CONVEX_SITE_URL` are present. ## Baseline Convex wiring patterns Always verify exact API names from upstream before coding. API names can change over time. Core files typically involved: 1. `convex/convex.config.ts` 2. `convex/auth.ts` 3. `convex/http.ts` 4. frontend auth bootstrap file Expected patterns to verify against upstream docs: - Component registration in `defineApp()` - Auth instance construction - Exported auth helpers - HTTP route registration method name Do not hardcode historical method names without checking current docs first. ## Migration guardrails When upgrading existing apps: 1. Snapshot current auth wiring before edits. 2. Update one surface at a time, config, auth module, then HTTP routes. 3. Keep old and new API mismatch notes in task output. 4. Verify sign in flow and callback routes before moving on. 5. Keep migrations minimal and focused to auth wiring only. ## Self hosting decision point Use `get-convex/self-hosting` only when: - user asks for self hosted static assets, or - auth portal hosting requires it in the selected upstream version. When needed, follow the latest upstream integration docs: - `https://github.com/get-convex/self-hosting` - `https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md` ## Output requirements for any task using this skill Before finishing, always report: 1. Retrieval timestamp for upstream docs. 2. Which branch was used as source of truth and why. 3. Install path selected, npm or GitHub pin, and why. 4. Exact files changed. 5. Exact commands the user should run next. Never claim completion without these five items. ## Source links - `https://github.com/robelest/convex-auth` - `https://github.com/robelest/convex-auth/tree/release` - `https://raw.githubusercontent.com/robelest/convex-auth/main/README.md` - `https://raw.githubusercontent.com/robelest/convex-auth/release/README.md` - `https://github.com/get-convex/self-hosting` - `https://raw.githubusercontent.com/get-convex/self-hosting/main/INTEGRATION.md` - `https://agentskills.io/home`
Related Skills
convex-setup-auth
Set up Convex authentication with proper user management, identity mapping, and access control patterns. Use when implementing auth flows, setting up OAuth providers, or adding role-based access control.
Update project docs
Use this skill after completing any feature, fix, or migration to keep the three core project tracking files in sync.
Create a PRD
Use this skill before any multi-file feature, architectural decision, or complex bug fix.
convex-self-hosting
Integrate Convex static self hosting into existing apps using the latest upstream instructions from get-convex/self-hosting every time. Use when setting up upload APIs, HTTP routes, deployment scripts, migration from external hosting, or troubleshooting static deploy issues across React, Vite, Next.js, and other frontends.
convex-return-validators
Guide for when to use and when not to use return validators in Convex functions. Use this skill whenever the user is writing Convex queries, mutations, or actions and needs guidance on return value validation. Also trigger when the user asks about Convex type safety, runtime validation, AI-generated Convex code, Convex AI rules, Convex security best practices, or when they're debugging return type issues in Convex functions. Trigger this skill when users mention "validators", "returns", "return type", or "exact types" in the context of Convex development. Also trigger when writing or reviewing Convex AI rules or prompts that instruct LLMs how to write Convex code.
convex-doctor
Run convex-doctor static analysis, interpret findings, and fix issues across security, performance, correctness, schema, and architecture categories. Use when running convex-doctor, fixing convex-doctor warnings or errors, improving the convex-doctor score, or when asked about Convex code quality, static analysis, or linting Convex functions.
write
Writing style guide for technical content, social media, blog posts, READMEs, git commits, and developer documentation. Optimized to avoid AI detection patterns. Use when writing any content beyond code.
workflow
Project workflow for PRDs, task tracking, changelog sync, and documentation updates. Use for any non-trivial task that spans multiple steps, touches several files, changes architecture, or needs project tracking updates. Also activates with @update to sync task.md, changelog.md, and files.md after completing work.
sec-check
Security review checklist for Convex functions, auth logic, public queries, admin routes, webhooks, uploads, and AI-generated code. Use when reviewing code that touches user data, PII, or access control.
schema-builder
Design and generate Convex database schemas with proper validation, indexes, and relationships. Use when creating schema.ts or modifying table definitions.
real-time-backend
Build reactive, type-safe, production-grade backends. ALWAYS use this skill when the user asks to build, plan, design, or implement backend features, APIs, data models, server logic, database schemas, web apps, full stack apps, or mobile apps. This includes planning and architecture discussions.
react-effect-decision
Combine React's official "You Might Not Need an Effect" guidance with this project's stricter no direct useEffect stance. Use when writing, reviewing, or refactoring React components that might reach for useEffect, derived state, event relays, reset logic, subscriptions, or client fetching.