MonoCloud Quickstart Router
This skill detects the project's stack and points you at the correct MonoCloud skill. Do not try to write integration code from this skill — load the framework-specific skill and follow its SKILL.md.
Step 1 — Detect the framework
Run the bundled detector. It scans the working directory (or a path you pass) and prints the recommended skill plus its reasoning:
node scripts/detect.js # current dir
node scripts/detect.js /path/to/app
The detector handles these signals:
| Signal in project |
Skill to use |
"next" in package.json dependencies |
monocloud-auth-nextjs |
"@monocloud/auth-nextjs" already installed |
monocloud-auth-nextjs |
"@monocloud/management" already installed |
monocloud-management-js |
"fastify" in package.json (no next) |
monocloud-auth-fastify |
"express" in package.json (no next/fastify) |
monocloud-auth-express |
*.csproj referencing MonoCloud.Management |
monocloud-management-dotnet |
Any *.csproj (no MonoCloud yet, .NET project) |
monocloud-management-dotnet (management) — for auth on .NET, MonoCloud doesn't yet ship a dedicated agent skill; use the docs link in the project. |
If two skills could apply (e.g. an Express API in a Next.js monorepo), prefer the more specific match in the app or package you're editing, not the workspace root.
Step 2 — Confirm with the user (only if ambiguous)
If detection is ambiguous (e.g. multiple package.json files in a monorepo, or both "express" and "@monocloud/management" declared), ask the user which app they want to wire up before proceeding.
Step 3 — Load the framework skill
Once you know which skill to use, stop reading this file and switch to that skill's SKILL.md. The framework skill owns:
- Installation command
- Environment variables (these differ per SDK — see "Env-var families" below)
- File layout (middleware/proxy location, DI registration, etc.)
- Code patterns
- Troubleshooting
Env-var families (for quick reference)
MonoCloud uses prefix-namespaced env vars per SDK. Don't mix them.
| Prefix |
SDK |
MONOCLOUD_AUTH_* |
@monocloud/auth-nextjs (frontend / Next.js session auth) |
MONOCLOUD_BACKEND_* |
@monocloud/backend-node/{express,fastify} (API token validation) |
MC_MANAGEMENT_* |
@monocloud/management (JS Management API SDK) |
MonoCloud:Management:* (config keys, not env) |
MonoCloud.Management (.NET Management API SDK) |
Skills catalog
monocloud-auth-nextjs — Sign-in/sign-up, sessions, route protection, components, hooks for Next.js (App + Pages Router).monocloud-auth-express — JWT / introspection token validation, scope + group enforcement for Express APIs.monocloud-auth-fastify — Same engine as above, with a Fastify onRequest hook.monocloud-management-js — @monocloud/management — programmatic admin: users, clients, groups, resources, keys, logs, options, branding, trust stores.monocloud-management-dotnet — MonoCloud.Management NuGet — same surface in .NET with DI registration.
Don't guess — verify after wiring
After the framework skill has been applied, run that skill's diagnostic:
node skills/<skill-folder>/scripts/verify.js
For example: node skills/monocloud-auth-nextjs/scripts/verify.js. The diagnostic checks env vars and that the SDK appears in package.json.
Deeper reference
references/concepts.md — tenant URL, OIDC vs Management APIs, public vs confidential clients.
1---2name: monocloud-quickstart3description: Use this skill FIRST whenever a user asks to add MonoCloud (authentication or management) to a project but hasn't said which framework. It detects the project type by reading `package.json`, `*.csproj`, `requirements.txt`, etc., then routes to the correct framework-specific MonoCloud skill (`monocloud-auth-nextjs`, `monocloud-auth-express`, `monocloud-auth-fastify`, `monocloud-management-js`, `monocloud-management-dotnet`). Also use when the user says "set up MonoCloud", "add MonoCloud login", "integrate MonoCloud", "use the MonoCloud SDK", or "manage users programmatically with MonoCloud" without naming a stack.4license: MIT5---6
7# MonoCloud Quickstart Router
8
9This skill detects the project's stack and points you at the correct MonoCloud skill. **Do not try to write integration code from this skill** — load the framework-specific skill and follow its `SKILL.md`.
10
11## Step 1 — Detect the framework
12
13Run the bundled detector. It scans the working directory (or a path you pass) and prints the recommended skill plus its reasoning:
14
15```bash
16node scripts/detect.js # current dir
17node scripts/detect.js /path/to/app
18```
19
20The detector handles these signals:
21
22| Signal in project | Skill to use |
23|---|---|
24| `"next"` in `package.json` dependencies | `monocloud-auth-nextjs` |
25| `"@monocloud/auth-nextjs"` already installed | `monocloud-auth-nextjs` |
26| `"@monocloud/management"` already installed | `monocloud-management-js` |
27| `"fastify"` in `package.json` (no `next`) | `monocloud-auth-fastify` |
28| `"express"` in `package.json` (no `next`/`fastify`) | `monocloud-auth-express` |
29| `*.csproj` referencing `MonoCloud.Management` | `monocloud-management-dotnet` |
30| Any `*.csproj` (no MonoCloud yet, .NET project) | `monocloud-management-dotnet` (management) — for auth on .NET, MonoCloud doesn't yet ship a dedicated agent skill; use the docs link in the project. |
31
32If two skills could apply (e.g. an Express API in a Next.js monorepo), prefer the more specific match in the **app or package you're editing**, not the workspace root.
33
34## Step 2 — Confirm with the user (only if ambiguous)
35
36If detection is ambiguous (e.g. multiple `package.json` files in a monorepo, or both `"express"` and `"@monocloud/management"` declared), ask the user which app they want to wire up before proceeding.
37
38## Step 3 — Load the framework skill
39
40Once you know which skill to use, **stop reading this file** and switch to that skill's `SKILL.md`. The framework skill owns:
41
42- Installation command
43- Environment variables (these differ per SDK — see "Env-var families" below)
44- File layout (middleware/proxy location, DI registration, etc.)
45- Code patterns
46- Troubleshooting
47
48## Env-var families (for quick reference)
49
50MonoCloud uses **prefix-namespaced** env vars per SDK. Don't mix them.
51
52| Prefix | SDK |
53|---|---|
54| `MONOCLOUD_AUTH_*` | `@monocloud/auth-nextjs` (frontend / Next.js session auth) |
55| `MONOCLOUD_BACKEND_*` | `@monocloud/backend-node/{express,fastify}` (API token validation) |
56| `MC_MANAGEMENT_*` | `@monocloud/management` (JS Management API SDK) |
57| `MonoCloud:Management:*` (config keys, not env) | `MonoCloud.Management` (.NET Management API SDK) |
58
59## Skills catalog
60
61- [`monocloud-auth-nextjs`](../monocloud-auth-nextjs/SKILL.md) — Sign-in/sign-up, sessions, route protection, components, hooks for Next.js (App + Pages Router).
62- [`monocloud-auth-express`](../monocloud-auth-express/SKILL.md) — JWT / introspection token validation, scope + group enforcement for Express APIs.
63- [`monocloud-auth-fastify`](../monocloud-auth-fastify/SKILL.md) — Same engine as above, with a Fastify `onRequest` hook.
64- [`monocloud-management-js`](../monocloud-management-js/SKILL.md) — `@monocloud/management` — programmatic admin: users, clients, groups, resources, keys, logs, options, branding, trust stores.
65- [`monocloud-management-dotnet`](../monocloud-management-dotnet/SKILL.md) — `MonoCloud.Management` NuGet — same surface in .NET with DI registration.
66
67## Don't guess — verify after wiring
68
69After the framework skill has been applied, run that skill's diagnostic:
70
71```bash
72node skills/<skill-folder>/scripts/verify.js
73```
74
75For example: `node skills/monocloud-auth-nextjs/scripts/verify.js`. The diagnostic checks env vars and that the SDK appears in `package.json`.
76
77## Deeper reference
78
79- [`references/concepts.md`](references/concepts.md) — tenant URL, OIDC vs Management APIs, public vs confidential clients.
aibot88