Port content improvements from Claude Code authstack

plugins/agent-auth/agents/setup-scalekit.md

@@ -18,7 +18,7 @@ Hard rules:
 - NEVER ask the user to paste SCALEKIT_CLIENT_SECRET into chat.
 - NEVER hardcode credentials in code samples; always use environment variables.
 - Prefer creating a local verification script (verify.js / verify.py / verify.go / Verify.java) and running it, but only if the user wants you to write files.
-- When using agent auth for nodejs, use npm install @scalekit-sdk/node@2.2.0-beta.1
+- When using agent auth for nodejs, use npm install @scalekit-sdk/node
 
 Workflow:
 1) Determine language/runtime (Node.js, Python, Go, Java) and where env vars should live (.env, shell, CI secrets).

plugins/agent-auth/rules/live-metadata-first.mdc

@@ -0,0 +1,24 @@
+---
+description: Treat live Agent Auth metadata as the source of truth for tool names, connector coverage, and schemas. Static docs are directional guidance, not guaranteed truth.
+alwaysApply: true
+---
+
+# Live Metadata First
+
+Treat live Agent Auth metadata as the source of truth for:
+
+- tool names
+- connector coverage
+- `input_schema`
+- `output_schema`
+
+## Implications
+
+- Static connector notes are not exhaustive.
+- Example code is not a catalog.
+- Schema discovery should happen before guessing tool inputs.
+- When credentials are available, prefer live lookup over prose documentation.
+
+## Fallback behavior
+
+If live credentials are unavailable, docs can still guide setup and workflow design, but they must be presented as directional guidance rather than guaranteed current truth.

plugins/agent-auth/rules/terminology.mdc

@@ -0,0 +1,23 @@
+---
+description: Enforces consistent Agent Auth terminology across skills, code, and docs. Prevents confusing connector, connection, and connected account.
+alwaysApply: true
+---
+
+# Terminology
+
+Use these terms consistently:
+
+- **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
+
+## Preferred wording
+
+- Prefer `connector` in explanations to users.
+- Use `provider` only when the SDK or API field literally uses that name.
+- Do not imply that `connection_name` is always the same as the connector slug.
+
+## Why this rule exists
+
+The old language mixed `provider`, `connector`, and `connection_name` too freely. This rule keeps the Agent Auth model stable across skills and docs.

plugins/agent-auth/rules/tool-selection.mdc

@@ -0,0 +1,27 @@
+---
+description: Keep the tool set as small as possible before handing it to an LLM. Too many tools degrade selection accuracy and parameter filling.
+alwaysApply: true
+---
+
+# Tool Selection
+
+Keep the tool set as small as possible before handing it to an LLM.
+
+## Rules
+
+- Start from the workflow, not the full catalog.
+- Discover only the connector or tool family relevant to the task.
+- Inspect `input_schema` before execution when required fields are unclear.
+- Avoid sending broad connector-wide tool lists to the model unless the task truly needs them.
+
+## Why this matters
+
+Too many tools degrade tool selection and parameter filling. Constraining the tool set improves both latency and correctness.
+
+## Practical pattern
+
+1. Identify the user goal.
+2. Discover a narrow candidate set.
+3. Inspect schema.
+4. Validate with one live execution if needed.
+5. Wire only the proven tools into the agent workflow.

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.
+
 **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
 
@@ -302,3 +313,8 @@ For an overview of supported providers and their capabilities, see [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 `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,15 @@ 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 `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/rules/redirect-urls.mdc

@@ -0,0 +1,27 @@
+---
+description: Enforces redirect URL rules for all OAuth and OIDC flows. Catches trailing-slash mismatches, scheme errors, and port mismatches before they cause auth failures.
+alwaysApply: true
+globs: ["**/*.{js,ts,py,go,java}"]
+---
+
+# Redirect URL Rules
+
+All OAuth and OIDC flows in Scalekit require registered redirect URLs.
+
+## Rules
+
+- The `redirect_uri` parameter in authorization requests must exactly match a URL registered in the Scalekit dashboard.
+- Register both development (`http://localhost:*`) and production (`https://`) redirect URLs.
+- The `post_logout_redirect_uri` must also be allowlisted in the dashboard under Post Logout URLs.
+- Never use wildcard redirect URLs in production.
+
+## Common mistakes
+
+- Trailing slash mismatch: `https://app.com/callback` vs `https://app.com/callback/`.
+- Scheme mismatch: `http://` registered but `https://` used in code (or vice versa).
+- Port mismatch in development: registering `:3000` but the app runs on `:3001`.
+
+## Where to configure
+
+Scalekit Dashboard → Settings → Redirect URLs (for auth callbacks)
+Scalekit Dashboard → Settings → Post Logout URLs (for logout redirects)

plugins/full-stack-auth/rules/terminology.mdc

@@ -0,0 +1,23 @@
+---
+description: Enforces consistent Scalekit product naming across full-stack-auth, modular-sso, modular-scim, and mcp-auth plugins. Prevents mixing old and new terminology.
+alwaysApply: true
+---
+
+# Terminology
+
+Use these terms consistently:
+
+- **Full Stack Auth (FSA)**: Scalekit manages the entire auth lifecycle (login, sessions, users).
+- **Modular SSO**: enterprise SSO integration where the app manages its own users and sessions. Scalekit handles only the SSO handshake.
+- **SCIM provisioning**: directory sync for automatic user and group lifecycle management via webhooks.
+- **Admin portal**: customer-facing iframe for self-serve SSO and SCIM configuration.
+- **MCP server auth**: OAuth 2.1 authorization for Model Context Protocol servers.
+
+## Preferred wording
+
+- Use `Modular SSO` when the app manages its own sessions. Use `Full Stack Auth SSO` when Scalekit manages everything.
+- Do not mix Agent Auth terminology (connectors, connected accounts, tools) in auth contexts. Agent Auth is about agent-to-tool authentication.
+
+## Why this rule exists
+
+The product surfaces (Full Stack Auth, Modular SSO, SCIM, MCP Auth) overlap but serve different architectures. This rule prevents confusion when the agent switches between plugins.

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,10 @@ 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.

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

@@ -39,6 +39,25 @@ Activate when the user asks to:
 
 ---
 
+## Critical prerequisites
+
+- MCP OAuth 2.1 auth only works with **Streamable HTTP transport** — SSE and stdio transports do not support auth.
+- Your MCP server must be registered in the Scalekit dashboard before tokens can be validated.
+- HTTPS is required in production (HTTP is acceptable for localhost development).
+
+## Implementation approaches
+
+| Approach | Framework | Complexity | Best for |
+|---|---|---|---|
+| FastMCP + Scalekit provider | Python | Low | Simple MCP servers, quick start |
+| FastAPI + FastMCP | Python | Medium | Apps needing advanced authorization and existing FastAPI routes |
+| Express.js + custom middleware | Node.js | Medium | Node.js apps, fine-grained token control |
+
+Each approach has a dedicated skill with full walkthroughs:
+- `mcp-auth-fastmcp-scalekit` — FastMCP + Scalekit provider
+- `mcp-auth-fastapi-fastmcp-scalekit` — FastAPI + FastMCP
+- `mcp-auth-expressjs-scalekit` — Express.js with custom middleware
+
 ## Procedure
 
 ### 1) Scalekit dashboard setup (resource server registration)
@@ -121,3 +140,9 @@ See `references/SECURITY.md`. Minimum:
 - Deep technical notes: `references/REFERENCE.md`
 - Scope design patterns: `references/SCOPES.md`
 - Production hardening: `references/SECURITY.md`
+
+## 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 (`mcp-auth-fastmcp-scalekit`, `mcp-auth-expressjs-scalekit`, `mcp-auth-fastapi-fastmcp-scalekit`) 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

@@ -404,7 +404,7 @@ Prevent failed redirects by checking SSO configuration before redirecting:
 
 **Node.js:**
 ```javascript
-const domain = email.split('@').toLowerCase(); [reddit](https://www.reddit.com/r/ClaudeAI/comments/1qb1024/ultimate_claude_skillmd_autobuilds_any_fullstack/)
+const domain = email.split('@').pop().toLowerCase();
 
 const connections = await scalekit.connections.listConnectionsByDomain({
   domain
@@ -571,4 +571,9 @@ app.post('/logout', (req, res) => {
 **Use progressive enhancement**: Start with basic SSO, add advanced features iteratively
 
 **Monitor authentication flows**: Track success rates and common failure points
-```
+
+## 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.