From 985e79430e1625b6ac1fd9f65fabe1a6af441bf4 Mon Sep 17 00:00:00 2001 From: Saif Shines Date: Tue, 12 May 2026 21:49:49 +0530 Subject: [PATCH] Port content improvements from Claude Code authstack Skill improvements across all 5 plugins: - Add mental model sections (agent-auth, full-stack-auth) - Add 'When to switch skills' routing tables (all 7 entry skills) - Add deep reference backlinks (building-agent-mcp-server, production-readiness) - Remove stale beta SDK version pin (agent-auth, mcp-auth, setup-scalekit) - Fix broken CONNECTORS.md link (agent-auth) - Remove broken token-management.md reference (agent-auth) - Fix stale Reddit link and code bug in modular-sso - Fix auth type claim in agent-connectors README Coverage gap fixes: - Add 4 missing connector docs (Attention, Chorus, Clari Copilot, Google Slides) - Update agent-connectors README with missing entries --- plugins/agent-auth/agents/setup-scalekit.md | 2 +- .../references/agent-connectors/README.md | 6 +++- .../references/agent-connectors/attention.md | 3 ++ .../references/agent-connectors/chorus.md | 3 ++ .../agent-connectors/clari_copilot.md | 3 ++ .../agent-connectors/google_slides.md | 32 +++++++++++++++++++ plugins/agent-auth/skills/agent-auth/SKILL.md | 22 ++++++++++--- .../skills/building-agent-mcp-server/SKILL.md | 12 +++++++ .../production-readiness-scalekit/SKILL.md | 6 ++++ .../skills/full-stack-auth/SKILL.md | 19 +++++++++++ plugins/mcp-auth/skills/mcp-auth/SKILL.md | 8 ++++- .../modular-scim/skills/modular-scim/SKILL.md | 6 ++++ .../modular-sso/skills/modular-sso/SKILL.md | 9 ++++-- 13 files changed, 122 insertions(+), 9 deletions(-) create mode 100644 plugins/agent-auth/references/agent-connectors/attention.md create mode 100644 plugins/agent-auth/references/agent-connectors/chorus.md create mode 100644 plugins/agent-auth/references/agent-connectors/clari_copilot.md create mode 100644 plugins/agent-auth/references/agent-connectors/google_slides.md diff --git a/plugins/agent-auth/agents/setup-scalekit.md b/plugins/agent-auth/agents/setup-scalekit.md index 7227f6f..ed43763 100644 --- a/plugins/agent-auth/agents/setup-scalekit.md +++ b/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). diff --git a/plugins/agent-auth/references/agent-connectors/README.md b/plugins/agent-auth/references/agent-connectors/README.md index a91420e..807653a 100644 --- a/plugins/agent-auth/references/agent-connectors/README.md +++ b/plugins/agent-auth/references/agent-connectors/README.md @@ -8,7 +8,10 @@ This directory contains documentation for all supported agent connectors in the |-----------|-------------|-----------| | [Airtable](airtable.md) | Connect to Airtable bases for data management | OAuth 2.0 | | [Asana](asana.md) | Project management and task tracking | OAuth 2.0 | +| [Attention](attention.md) | AI insights, conversations, teams, and workflows | API Key | | [BigQuery](bigquery.md) | Google BigQuery data warehouse | OAuth 2.0 | +| [Chorus](chorus.md) | Sync calls, transcripts, conversation intelligence, and analytics | Basic Auth | +| [Clari Copilot](clari_copilot.md) | Sales call transcripts, analytics, call data, and insights | API Key | | [ClickUp](clickup.md) | Project management and collaboration | OAuth 2.0 | | [Confluence](confluence.md) | Atlassian Confluence wiki pages | OAuth 2.0 | | [Dropbox](dropbox.md) | File storage and sharing | OAuth 2.0 | @@ -23,6 +26,7 @@ This directory contains documentation for all supported agent connectors in the | [Google Forms](google_forms.md) | Google Forms survey creation | OAuth 2.0 | | [Google Meet](google_meets.md) | Google Meet video conferencing | OAuth 2.0 | | [Google Sheets](google_sheets.md) | Google Sheets spreadsheet editing | OAuth 2.0 | +| [Google Slides](google_slides.md) | Create, read, and modify presentations programmatically | OAuth 2.0 | | [Gong](gong.md) | Sales conversation intelligence | OAuth 2.0 | | [HubSpot](hubspot.md) | CRM and marketing automation | OAuth 2.0 | | [Intercom](intercom.md) | Customer messaging platform | OAuth 2.0 | @@ -57,7 +61,7 @@ Each connector documentation includes: ## Authentication -All connectors support OAuth 2.0 authentication through the Agent Auth platform. You'll need to: +Connectors support OAuth 2.0, API Key, or Basic Auth authentication through the Agent Auth platform. You'll need to: 1. Create a connection for the desired service 2. Configure OAuth credentials in your connection diff --git a/plugins/agent-auth/references/agent-connectors/attention.md b/plugins/agent-auth/references/agent-connectors/attention.md new file mode 100644 index 0000000..9af975e --- /dev/null +++ b/plugins/agent-auth/references/agent-connectors/attention.md @@ -0,0 +1,3 @@ +Connect to Attention for AI insights, conversations, teams, and workflows + +Supports authentication: API Key diff --git a/plugins/agent-auth/references/agent-connectors/chorus.md b/plugins/agent-auth/references/agent-connectors/chorus.md new file mode 100644 index 0000000..b57dd23 --- /dev/null +++ b/plugins/agent-auth/references/agent-connectors/chorus.md @@ -0,0 +1,3 @@ +Connect to Chorus.ai to sync calls, transcripts, conversation intelligence, and analytics. + +Supports authentication: Basic Auth diff --git a/plugins/agent-auth/references/agent-connectors/clari_copilot.md b/plugins/agent-auth/references/agent-connectors/clari_copilot.md new file mode 100644 index 0000000..2949e94 --- /dev/null +++ b/plugins/agent-auth/references/agent-connectors/clari_copilot.md @@ -0,0 +1,3 @@ +Connect to Clari Copilot for sales call transcripts, analytics, call data, and insights. + +Supports authentication: API Key diff --git a/plugins/agent-auth/references/agent-connectors/google_slides.md b/plugins/agent-auth/references/agent-connectors/google_slides.md new file mode 100644 index 0000000..242ef37 --- /dev/null +++ b/plugins/agent-auth/references/agent-connectors/google_slides.md @@ -0,0 +1,32 @@ +Connect to Google Slides to create, read, and modify presentations programmatically. + +Supports authentication: OAuth 2.0 + +## Table of Contents + +- [Tool list](#tool-list) + +--- + +## Tool list + +## `googleslides_create_presentation` + +Create a new Google Slides presentation with an optional title. + +| Properties | Description | Type | +| --- | --- | --- | +| `schema_version` | Optional schema version to use for tool execution | string | null | +| `title` | Title of the new presentation | string | null | +| `tool_version` | Optional tool version to use for execution | string | null | + +## `googleslides_read_presentation` + +Read the complete structure and content of a Google Slides presentation including slides, text, images, shapes, and metadata. + +| Properties | Description | Type | +| --- | --- | --- | +| `fields` | Fields to include in the response | string | null | +| `presentation_id` | The ID of the Google Slides presentation to read | string | +| `schema_version` | Optional schema version to use for tool execution | string | null | +| `tool_version` | Optional tool version to use for execution | string | null | diff --git a/plugins/agent-auth/skills/agent-auth/SKILL.md b/plugins/agent-auth/skills/agent-auth/SKILL.md index 05bf999..c413dd4 100644 --- a/plugins/agent-auth/skills/agent-auth/SKILL.md +++ b/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,9 @@ 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 `production-readiness-scalekit` when the user is going live or needs a pre-launch checklist. diff --git a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md b/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md index b8e85b7..b23dab9 100644 --- a/plugins/agent-auth/skills/building-agent-mcp-server/SKILL.md +++ b/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. diff --git a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md b/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md index 152ffd3..7d59e99 100644 --- a/plugins/agent-auth/skills/production-readiness-scalekit/SKILL.md +++ b/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) diff --git a/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md b/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md index 389d2f1..fbfcf79 100644 --- a/plugins/full-stack-auth/skills/full-stack-auth/SKILL.md +++ b/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. diff --git a/plugins/mcp-auth/skills/mcp-auth/SKILL.md b/plugins/mcp-auth/skills/mcp-auth/SKILL.md index f7e3e16..58abb77 100644 --- a/plugins/mcp-auth/skills/mcp-auth/SKILL.md +++ b/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. diff --git a/plugins/modular-scim/skills/modular-scim/SKILL.md b/plugins/modular-scim/skills/modular-scim/SKILL.md index 00446e7..448c7f9 100644 --- a/plugins/modular-scim/skills/modular-scim/SKILL.md +++ b/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. diff --git a/plugins/modular-sso/skills/modular-sso/SKILL.md b/plugins/modular-sso/skills/modular-sso/SKILL.md index 15aa426..75de278 100644 --- a/plugins/modular-sso/skills/modular-sso/SKILL.md +++ b/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 -``` \ No newline at end of file + +## 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. \ No newline at end of file