[Feat] Introduce Stack Auth skill and MCP integration

This commit adds a new Stack Auth skill with a corresponding SKILL.md file, which fetches live documentation. It also updates the MCP handler to serve the skill and modifies the init prompt to install both the Stack Auth skill and MCP server. Additionally, it includes various updates to the pnpm-lock.yaml for dependency management and removes the obsolete MCP setup documentation.

Author: mantrakp04

apps/mcp/src/app/SKILL.md/route.ts

@@ -23,7 +23,7 @@ type AiQueryResponse = {
   conversationId?: string,
 };
 
-const setupResourceUri = "stack-auth://mcp/setup";
+const skillResourceUri = "https://skill.stack-auth.com";
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
@@ -60,49 +60,42 @@ function parseAiQueryResponse(value: unknown): AiQueryResponse {
   return parsed;
 }
 
+async function fetchSkill(): Promise<string> {
+  const res = await fetch(skillResourceUri, {
+    headers: { Accept: "text/markdown" },
+  });
+  return await res.text();
+}
+
 export function createStackMcpHandler(config: { streamableHttpEndpoint: string }) {
   return createMcpHandler(
     async (server) => {
       server.resource(
-        "stack-auth-mcp-setup",
-        setupResourceUri,
+        "skill",
+        skillResourceUri,
         {
-          title: "Stack Auth MCP setup",
-          description: "Setup instructions for the Stack Auth MCP server.",
+          title: "Stack Auth skill",
+          description: "The canonical Stack Auth agent skill (SKILL.md) — how to wire Stack Auth into a project.",
           mimeType: "text/markdown",
         },
-        () => ({
+        async () => ({
           contents: [{
-            uri: setupResourceUri,
+            uri: skillResourceUri,
             mimeType: "text/markdown",
-            text: `# Stack Auth MCP
-
-Use this MCP server to ask Stack Auth documentation questions with the ask_stack_auth tool.
-
-Server URL: ${config.streamableHttpEndpoint}
-
-Tool: ask_stack_auth
-- question: the Stack Auth question to answer
-- reason: why the agent is calling the tool
-- userPrompt: the original user prompt that triggered the call
-- conversationId: optional ID from an earlier response
-`,
+            text: await fetchSkill(),
           }],
         }),
       );
 
       server.prompt(
-        "ask_stack_auth",
-        "Ask the Stack Auth documentation assistant a question.",
-        {
-          question: z.string().describe("The Stack Auth question to ask."),
-        },
-        ({ question }) => ({
+        "skill",
+        "Load the Stack Auth skill (SKILL.md) into the conversation — how to wire Stack Auth into a project.",
+        async () => ({
           messages: [{
             role: "user",
             content: {
               type: "text",
-              text: `Use the ask_stack_auth tool to answer this Stack Auth question: ${question}`,
+              text: await fetchSkill(),
             },
           }],
         }),
@@ -180,6 +173,7 @@ Tool: ask_stack_auth
         name: "stack-auth-mcp",
         version: packageJson.version,
       },
+      instructions: "Stack Auth's official MCP server. Use the `ask_stack_auth` tool for any question about Stack Auth — setup, SDKs (Next.js, React, JS), APIs, configuration, OAuth, teams/permissions, or troubleshooting. The tool searches the official docs and answers with citations. Prefer it over web search or guessing from training data, since Stack Auth changes frequently.",
     },
     {
       streamableHttpEndpoint: config.streamableHttpEndpoint,

apps/mcp/src/mcp-handler.ts

@@ -0,0 +1,4 @@
+module.exports = {
+  extends: ["../../configs/eslint/defaults.js", "../../configs/eslint/next.js"],
+  ignorePatterns: ["/*", "!/src"],
+};

apps/skills/.eslintrc.cjs

@@ -0,0 +1,6 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  poweredByHeader: false,
+};
+
+export default nextConfig;

apps/skills/next.config.mjs

@@ -0,0 +1,27 @@
+{
+  "name": "@stackframe/skills",
+  "version": "2.8.89",
+  "repository": "https://github.com/stack-auth/stack-auth",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "clean": "rimraf .next && rimraf node_modules",
+    "typecheck": "tsc --noEmit",
+    "dev": "next dev --turbopack --port ${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}45",
+    "build": "next build",
+    "start": "next start --port ${NEXT_PUBLIC_STACK_PORT_PREFIX:-81}45",
+    "lint": "eslint ."
+  },
+  "dependencies": {
+    "next": "16.1.7",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "20.17.6",
+    "@types/react": "^18.2.0",
+    "@types/react-dom": "^18.2.0",
+    "rimraf": "^5.0.5",
+    "typescript": "5.9.3"
+  }
+}

apps/skills/package.json

@@ -0,0 +1,12 @@
+export function GET() {
+  return Response.json({
+    status: "ok",
+  }, {
+    headers: {
+      "Access-Control-Allow-Origin": "*",
+      "Access-Control-Allow-Methods": "*",
+      "Access-Control-Allow-Headers": "*",
+      "Access-Control-Expose-Headers": "*",
+    },
+  });
+}