Port content improvements from Claude Code authstack

plugins/agent-auth/skills/agent-auth/SKILL.md

@@ -7,6 +7,17 @@ description: Integrates Scalekit Agent Auth into a project to handle OAuth flows
 
 Scalekit handles the full OAuth lifecycle — authorization, token storage, and refresh — so agents can act on behalf of users in Gmail, Slack, Notion, Calendar, and other connectors.
 
+## Mental model
+
+Keep these terms straight:
+
+- **connector**: the integration (e.g., Gmail, Slack, Salesforce)
+- **connection**: the environment-level dashboard configuration
+- **connected account**: the per-user authorization record
+- **tool**: the executable action exposed by a connector
+
+Prefer live tool discovery over hand-maintained catalogs. If the user needs the current tool list or schema, use the Scalekit SDK's tool discovery methods rather than relying solely on static docs.
+
 **Required env vars**: `SCALEKIT_CLIENT_ID`, `SCALEKIT_CLIENT_SECRET`, `SCALEKIT_ENV_URL`
 → Get from [app.scalekit.com](https://app.scalekit.com): Developers → Settings → API Credentials
 
@@ -39,7 +50,7 @@ actions = scalekit.actions
 
 **Node.js**
 ```bash
-npm install @scalekit-sdk/node@2.2.0-beta.1
+npm install @scalekit-sdk/node
 ```
 ```typescript
 import { ScalekitClient } from '@scalekit-sdk/node';
@@ -223,7 +234,7 @@ for (const msg of messages) {
 Replace `"gmail"` with any supported connector name: `slack`, `notion`, `calendar`, etc.
 The SDK workflow (Steps 1–3) is identical for all connectors. Only the downstream API call (Step 4) changes.
 
-For connector-specific API details, see [CONNECTORS.md](CONNECTORS.md).
+For connector-specific API details, see [agent-connectors](../references/agent-connectors/README.md).
 
 ## Building agents
 
@@ -299,6 +310,10 @@ For code samples and implementation examples by framework, see [code-samples.md]
 
 For an overview of supported providers and their capabilities, see [providers.md](../references/providers.md).
 
-For comprehensive token management including refresh, security, and monitoring, see [token-management.md](../references/token-management.md).
-
 For configuring your own OAuth credentials per connector (whitelabeling, dedicated quotas), see [byoc.md](../references/byoc.md).
+
+## When to switch skills
+
+- Use `building-agent-mcp-server` when the user wants to expose Agent Auth tools over the MCP protocol.
+- Use `integrating-agent-auth` for a concise integration checklist without the full Gmail walkthrough.
+- Use `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist.

plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md

@@ -156,3 +156,16 @@ asyncio.run(main())
 > **Note — MCP client compatibility:** You can test this MCP server with popular clients like MCP Inspector, Claude Desktop, and other spec-compliant implementations. Note that ChatGPT's beta connector feature may not work properly as it's still in beta and doesn't fully adhere to the MCP specification yet.
 
 Full working example: [github.com/scalekit-inc/python-connect-demos/tree/main/mcp](https://github.com/scalekit-inc/python-connect-demos/tree/main/mcp)
+
+## Deep reference
+
+- Connected accounts lifecycle and states: [connected-accounts.md](../../references/connected-accounts.md)
+- Connection configuration: [connections.md](../../references/connections.md)
+- Code samples by framework: [code-samples.md](../../references/code-samples.md)
+- Bring your own OAuth credentials: [byoc.md](../../references/byoc.md)
+
+## When to switch skills
+
+- Use `agent-auth` when the user wants to integrate Agent Auth directly (SDK, not MCP).
+- Use `integrating-agent-auth` for a concise integration checklist.
+- Use `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist.

plugins/agent-auth/skills/integrating-agent-auth/SKILL.md

@@ -95,3 +95,9 @@ Always refresh your view of the connected account immediately before making the
 - In web apps, redirect users to the authorization link instead of only printing it.
 - For agent workflows, keep user identity stable so the same person maps to the same connected account record.
 - Review token handling separately from third-party API logic so auth failures are easy to isolate.
+
+## When to switch skills
+
+- Use `agent-auth` for the full integration walkthrough with Gmail examples and framework agents.
+- Use `building-agent-mcp-server` when the user wants to expose Agent Auth tools over the MCP protocol.
+- Use `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist.

plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md

@@ -60,3 +60,9 @@ Work through each section in order — earlier sections are blockers for later o
 - OAuth authorization completion rate (initiated vs completed)
 - Per-service API error rates (distinguish auth errors from service errors)
 - Token expiry distribution (are tokens being refreshed proactively?)
+
+## Deep reference
+
+- Connected accounts lifecycle and states: [connected-accounts.md](../../references/connected-accounts.md)
+- Connection configuration: [connections.md](../../references/connections.md)
+- Bring your own OAuth credentials: [byoc.md](../../references/byoc.md)

plugins/full-stack-auth/skills/full-stack-auth/SKILL.md

@@ -5,6 +5,17 @@ description: Implements Scalekit full-stack authentication (FSA) including sign-
 
 # Scalekit Full-Stack Authentication
 
+## Mental model
+
+Scalekit acts as an OIDC/OAuth 2.0 provider for your application:
+
+- **Auth URL**: redirects the user to Scalekit's login page (or their IdP for SSO)
+- **Callback**: exchanges the authorization code for tokens (ID, access, refresh)
+- **Access token**: short-lived, carries roles and permissions
+- **Refresh token**: long-lived, used to renew access tokens without re-login
+
+One integration enables: magic links, social sign-ins, enterprise SSO, workspaces, MCP authentication, SCIM provisioning, and user management.
+
 ## Setup
 
 Install the SDK and set credentials in `.env`:
@@ -93,3 +104,11 @@ All SDK methods follow the same pattern across languages with minor naming conve
 ## What this unlocks
 
 One integration enables: Magic Link & OTP, social sign-ins, enterprise SSO, workspaces, MCP authentication, SCIM provisioning, and user management.
+
+## When to switch skills
+
+- Use `modular-sso` (in the modular-sso plugin) when the app manages its own users and sessions and needs only SSO.
+- Use `modular-scim` (in the modular-scim plugin) for SCIM provisioning alongside existing auth.
+- Use `mcp-auth` (in the mcp-auth plugin) for OAuth 2.1 authorization on MCP servers.
+- Use `production-readiness-scalekit` for a pre-launch checklist.
+- Use a framework-specific skill (e.g., `implementing-scalekit-nextjs-auth`, `implementing-scalekit-django-auth`) for step-by-step guides in your stack.

plugins/mcp-auth/skills/mcp-auth/SKILL.md

@@ -69,7 +69,7 @@ MCP OAuth Setup:
 
 **Node.js:**
 ```bash
-npm install @scalekit-sdk/node@2.2.0-beta.1
+npm install @scalekit-sdk/node
 ```
 
 **Python:**
@@ -448,3 +448,9 @@ All examples include:
 - Executes tool calls for authorized requests
 
 This separation ensures clean boundaries: Scalekit handles identity and token issuance, your server focuses on business logic.
+
+## When to switch skills
+
+- Use `full-stack-auth` (in the full-stack-auth plugin) for browser-based authentication flows.
+- Use `production-readiness-scalekit` for a pre-launch MCP auth checklist.
+- Use a framework-specific sub-skill (`add-auth-fastmcp`, `express-mcp-server`, `fastapi-fastmcp`) for a guided implementation in your stack.

plugins/modular-scim/skills/modular-scim/SKILL.md

@@ -228,3 +228,9 @@ After deploying the webhook endpoint:
 - Full Go/Java SDK examples → [REFERENCE.md](REFERENCE.md)
 - Webhook event payload schemas → [EVENTS.md](EVENTS.md)
 - RBAC group-to-role mapping patterns → [RBAC.md](RBAC.md)
+
+## When to switch skills
+
+- Use `full-stack-auth` (in the full-stack-auth plugin) when building login/signup flows, not just provisioning.
+- Use `modular-sso` (in the modular-sso plugin) for enterprise SSO alongside SCIM.
+- Use `production-readiness-scalekit` for a pre-launch provisioning checklist.

plugins/modular-sso/skills/modular-sso/SKILL.md

@@ -69,3 +69,9 @@ const authUrl = scalekit.getAuthorizationUrl(
 - Treat IdP-initiated login as a translation into a secure SP-initiated flow, not as a shortcut around normal callback handling.
 - Keep enterprise onboarding decisions explicit: who creates the connection, how users are mapped, and where login is initiated.
 - Map validated claims into the app's existing user model and session model instead of duplicating local account logic.
+
+## When to switch skills
+
+- Use `full-stack-auth` (in the full-stack-auth plugin) when Scalekit should manage the full auth lifecycle (login, sessions, users).
+- Use `modular-scim` (in the modular-scim plugin) for SCIM provisioning alongside SSO.
+- Use `production-readiness-scalekit` for a pre-launch SSO checklist.