scalekit-code-doctor

Scalekit Code Doctor

Before doing anything else, read the reference files bundled next to this SKILL.md under references/ (open with the file tool from the skill package directory):

• references/REFERENCE.md — Every correct SDK method signature and REST endpoint
• references/COMMON-MISTAKES.md — Known anti-patterns with wrong → right corrections
• references/EXAMPLE-REPOS.md — GitHub repos with working examples by framework

Never hallucinate a method name, parameter, or import — if it's not in the reference, verify against live sources before using it.

Guardrails

• MUST cross-reference every SDK method, parameter, and import against references/REFERENCE.md (or a live source per Step 5); MUST NOT guess or hallucinate an API that isn't verified there.
• MUST confirm the target SDK/language and product area (SaaSKit vs AgentKit) before generating or reviewing code; MUST NOT assume context that wasn't identified in Step 2.
• MUST state "This method could not be verified" when a call can't be confirmed; MUST NOT output code containing an unverified method call.

Step 1 — Detect mode

Generate mode — User describes what they want but has no code yet. Review mode — User provides existing code for validation.

If unclear, ask: "Do you want me to generate a fresh code example, or review existing code?"

Step 2 — Identify context

Language	Package	Import
Node.js / TypeScript	@scalekit-sdk/node	import { ScalekitClient } from '@scalekit-sdk/node'
Python	scalekit-sdk-python	from scalekit import ScalekitClient
Go	scalekit-sdk-go	import scalekit "github.com/scalekit-inc/scalekit-sdk-go/v2"
Java	scalekit-sdk-java	import com.scalekit.ScalekitClient;

Product area: SaaSKit (SSO, login, sessions, RBAC, SCIM) or AgentKit (connections, tool calling, MCP auth).

Step 3 — Generate mode

Output should be illustration-ready: self-contained, essential path only, correct imports, framework-idiomatic, 1–2 pages max.

Correct SaaSKit login+callback example (Node.js/Express):

import { ScalekitClient } from '@scalekit-sdk/node';
import crypto from 'crypto';

const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL!,
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!
);

const REDIRECT_URI = 'https://yourapp.com/auth/callback';

// Login — generate auth URL with CSRF state
app.get('/auth/login', (req, res) => {
  const state = crypto.randomBytes(32).toString('base64url');
  res.cookie('oauth_state', state, { httpOnly: true, sameSite: 'lax', secure: true });
  const authUrl = scalekit.getAuthorizationUrl(REDIRECT_URI, { state });
  res.redirect(authUrl);
});

// Callback — validate state, exchange code, store session
app.get('/auth/callback', async (req, res) => {
  const { code, state } = req.query;
  if (state !== req.cookies.oauth_state) return res.status(403).send('CSRF mismatch');

  const result = await scalekit.authenticateWithCode(code as string, REDIRECT_URI);
  req.session.user = { id: result.user.id, email: result.user.email };
  req.session.idToken = result.idToken;
  res.redirect('/dashboard');
});

// Logout — clear local + end IdP session
app.post('/auth/logout', (req, res) => {
  const logoutUrl = scalekit.getLogoutUrl({
    idTokenHint: req.session.idToken,
    postLogoutRedirectUri: 'https://yourapp.com',
  });
  req.session.destroy(() => res.redirect(logoutUrl));
});

Correct AgentKit connected-account example (Node.js):

import { ScalekitClient } from '@scalekit-sdk/node';

const scalekit = new ScalekitClient(
  process.env.SCALEKIT_ENVIRONMENT_URL!, // alias: SCALEKIT_ENV_URL in some samples
  process.env.SCALEKIT_CLIENT_ID!,
  process.env.SCALEKIT_CLIENT_SECRET!
);
const { connectedAccounts } = scalekit;

// connectionName = exact dashboard Connection Name (not necessarily the connector slug)
const { connectedAccount } = await connectedAccounts.getOrCreateConnectedAccount({
  connectionName: 'gmail',
  identifier: 'user_123',
});
if (connectedAccount?.status !== 'ACTIVE') {
  const { link } = await connectedAccounts.getMagicLinkForConnectedAccount({
    connectionName: 'gmail',
    identifier: 'user_123',
  });
  console.log('Authorize:', link); // user completes OAuth in browser
}

Mandatory checks before outputting generated code — cross-reference every SDK call against references/REFERENCE.md:

• Method names exist for the target SDK
• Parameters match in name, order, and type
• Import path is exactly correct
• Environment variable names follow Scalekit conventions (SCALEKIT_ENVIRONMENT_URL preferred)

Step 4 — Review mode

Check these categories in order:

1. SDK correctness — Every method name, parameter, import, and return type matches references/REFERENCE.md.

2. Auth flow completeness — Login has a callback. Callback validates state. Logout calls getLogoutUrl(). Token refresh exists if offline_access is used. IdP-initiated login handled if applicable.

3. Security — Cookies: httpOnly, secure, sameSite: 'lax'. State: cryptographically random. Redirects: only relative paths. Secrets: from env vars. Webhooks: signature verified before processing.

4. Environment — Prefer SCALEKIT_ENVIRONMENT_URL, SCALEKIT_CLIENT_ID, SCALEKIT_CLIENT_SECRET. Some samples/docs use SCALEKIT_ENV_URL for the same URL value — treat them as aliases when reviewing; generate new code with SCALEKIT_ENVIRONMENT_URL. Redirect URI matches dashboard. Domain format: https://<subdomain>.scalekit.com.

5. Best practices — Client is singleton. Error handling uses typed exceptions. window.location.href for OAuth redirects (not router.push).

Output for each finding: What's wrong → Why it matters → Corrected code.

Step 5 — Unknown methods

Resolution order when a method isn't in references/REFERENCE.md:

Priority	Source
1	Embedded references/REFERENCE.md
2	Live SDK reference: https://raw.githubusercontent.com/scalekit-inc/scalekit-sdk-{node,python,go,java}/main/REFERENCE.md
3	REST API: https://docs.scalekit.com/apis
4	State explicitly: "This method could not be verified."

Never output code containing an unverified method call.

Documentation

Resource	URL
REST API reference	https://docs.scalekit.com/apis
LLM doc index	https://docs.scalekit.com/llms.txt
SaaSKit docs	https://docs.scalekit.com/_llms-txt/saaskit-complete.txt
AgentKit docs	https://docs.scalekit.com/_llms-txt/agentkit.txt
MCP Auth docs	https://docs.scalekit.com/_llms-txt/mcp-authentication.txt

For framework-specific example repos, see references/EXAMPLE-REPOS.md.