Add temporary skill output

Author: ethan-huo

README.md

@@ -228,6 +228,13 @@ This writes:
 The generated skill instructs agents to discover tools with focused schema
 selectors and call MCP tools through mcpx.
 
+For temporary agent guidance without writing `.agents/skills`, print a one-server
+skill to stdout:
+
+```bash
+mcpx @skill --show slack
+```
+
 ## Skill
 
 General mcpx skill definition lives at `skills/mcpx/SKILL.md`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpx",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "license": "MIT",
   "bin": {
     "mcpx": "./src/main.ts"

skills/mcpx/SKILL.md

@@ -159,6 +159,16 @@ Use the generated project skill as the project-specific router. It should name
 servers the user has already made available; do not use this flow to register or
 authenticate new MCP servers.
 
+For temporary agent guidance without writing `.agents/skills`, print a
+single-server skill to stdout:
+
+```bash
+mcpx @skill --show slack
+```
+
+Use this when the user asks for a one-off service action during the current
+agent session and does not want persistent project skills.
+
 ## References
 
 mcpx maintains a background daemon (`mcpxd`) for session reuse and notification

src/router.ts

@@ -73,6 +73,12 @@ const skillInput = s(
         v.description("Comma-separated MCP server names, for example posthog,sentry"),
       ),
     ),
+    show: v.optional(
+      v.pipe(
+        v.string(),
+        v.description("Print a temporary skill for one MCP server without writing files"),
+      ),
+    ),
   }),
 );
 
@@ -154,9 +160,12 @@ function buildRouter(service: ProjectService): Router {
     ),
     "@skill": c
       .meta({
-        description:
-          "Generate a project skill that teaches agents which global MCP servers to use.",
-        examples: ["mcpx @skill", "mcpx @skill --servers posthog,sentry"],
+        description: "Generate a project skill or print a temporary server skill for agents.",
+        examples: [
+          "mcpx @skill",
+          "mcpx @skill --servers posthog,sentry",
+          "mcpx @skill --show slack",
+        ],
       })
       .input(skillInput),
   };
@@ -302,7 +311,7 @@ function buildHandlers(service: ProjectService, cwd: string): Record<string, unk
     },
   };
 
-  handlers["@skill"] = async (options: HandlerOptions<{ servers?: string }>) => {
+  handlers["@skill"] = async (options: HandlerOptions<{ servers?: string; show?: string }>) => {
     await runSkillCommand(service, cwd, options.input);
   };
 

src/skill-command.ts

@@ -1,10 +1,11 @@
 import { cancel, isCancel, multiselect } from "@clack/prompts";
 
-import { readMcpxSkillServers, writeMcpxSkill } from "./skill-template";
+import { buildMcpxSkillMarkdown, readMcpxSkillServers, writeMcpxSkill } from "./skill-template";
 import type { ProjectService } from "./project-service";
 
 export type SkillCommandInput = {
   servers?: string;
+  show?: string;
 };
 
 export async function runSkillCommand(
@@ -19,6 +20,15 @@ export async function runSkillCommand(
     );
   }
 
+  if (input.show !== undefined) {
+    if (input.servers !== undefined) {
+      throw new Error("--show cannot be combined with --servers.");
+    }
+    const server = normalizeShownServer(input.show, availableServers);
+    process.stdout.write(buildMcpxSkillMarkdown([server], { projectLocal: false }));
+    return;
+  }
+
   const selectedServers =
     input.servers === undefined
       ? await promptForServers(availableServers, await readMcpxSkillServers(cwd))
@@ -67,3 +77,16 @@ function normalizeSelectedServers(value: string, availableServers: string[]): st
 
   return [...new Set(selected)].sort();
 }
+
+function normalizeShownServer(value: string, availableServers: string[]): string {
+  const server = value.trim();
+  if (server.length === 0 || server.includes(",")) {
+    throw new Error("Select exactly one MCP server for --show.");
+  }
+
+  const available = new Set(availableServers);
+  if (!available.has(server)) {
+    throw new Error(`Unknown MCP server: ${server}`);
+  }
+  return server;
+}

src/skill-template.ts

@@ -8,6 +8,10 @@ export type SkillTemplateInput = {
   servers: string[];
 };
 
+type SkillMarkdownOptions = {
+  projectLocal?: boolean;
+};
+
 export function mcpxSkillPath(cwd: string): string {
   return path.join(cwd, ".agents", "skills", "mcpx", "SKILL.md");
 }
@@ -22,10 +26,17 @@ export function buildSchemaSelector(servers: string[]): string {
   return `.{${servers.join(",")}}`;
 }
 
-export function buildMcpxSkillMarkdown(servers: string[]): string {
+export function buildMcpxSkillMarkdown(
+  servers: string[],
+  options: SkillMarkdownOptions = {},
+): string {
+  const projectLocal = options.projectLocal ?? true;
   const selector = buildSchemaSelector(servers);
   const serverList = servers.map((server) => `- ${server}`).join("\n");
-  const description = `Use project-approved MCP tools through mcpx. Trigger when the user asks to inspect or operate services backed by these MCP servers: ${servers.join(", ")}.`;
+  const description = projectLocal
+    ? `Use project-approved MCP tools through mcpx. Trigger when the user asks to inspect or operate services backed by these MCP servers: ${servers.join(", ")}.`
+    : `Use configured MCP tools through mcpx. Trigger when the user asks to inspect or operate services backed by these MCP servers: ${servers.join(", ")}.`;
+  const scope = projectLocal ? "project-approved" : "configured";
 
   return `---
 name: ${JSON.stringify("mcpx")}
@@ -35,7 +46,7 @@ description: ${JSON.stringify(description)}
 
 # MCPX
 
-Use this skill when the task needs one of these MCP servers:
+Use this skill when the task needs one of these ${scope} MCP servers:
 
 ${serverList}
 

tests/skill-command.test.ts

@@ -0,0 +1,70 @@
+import { mkdtemp, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { describe, expect, it } from "bun:test";
+
+import { runSkillCommand } from "../src/skill-command";
+import type { ProjectService } from "../src/project-service";
+
+function fixtureService(): ProjectService {
+  return {
+    config: {
+      version: 1,
+      servers: {
+        slack: {
+          transport: "stdio",
+          command: "slack-mcp",
+          tools: [],
+        },
+      },
+    },
+    ensureServerReady: async () => {
+      throw new Error("not used");
+    },
+    reauthenticateServer: async () => {
+      throw new Error("not used");
+    },
+    save: async () => {},
+  };
+}
+
+async function captureStdout(run: () => Promise<void>): Promise<string> {
+  const originalWrite = process.stdout.write;
+  let output = "";
+  process.stdout.write = ((chunk: string | Uint8Array) => {
+    output += chunk.toString();
+    return true;
+  }) as typeof process.stdout.write;
+
+  try {
+    await run();
+    return output;
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+}
+
+describe("mcpx skill command", () => {
+  it("prints a temporary server skill without writing project files", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "mcpx-skill-show-"));
+    const output = await captureStdout(async () => {
+      await runSkillCommand(fixtureService(), cwd, { show: "slack" });
+    });
+
+    expect(output).toContain('servers: ["slack"]');
+    expect(output).toContain("configured MCP servers");
+    expect(output).toContain('mcpx --schema=".slack"');
+    await expect(
+      readFile(join(cwd, ".agents", "skills", "mcpx", "SKILL.md"), "utf8"),
+    ).rejects.toThrow();
+  });
+
+  it("rejects mixing temporary show and project skill generation", async () => {
+    const cwd = await mkdtemp(join(tmpdir(), "mcpx-skill-show-"));
+
+    await expect(
+      runSkillCommand(fixtureService(), cwd, { servers: "slack", show: "slack" }),
+    ).rejects.toThrow("--show cannot be combined with --servers.");
+  });
+});

tests/skill-template.test.ts

@@ -4,7 +4,12 @@ import { join } from "node:path";
 
 import { describe, expect, it } from "bun:test";
 
-import { buildSchemaSelector, parseMcpxSkillServers, writeMcpxSkill } from "../src/skill-template";
+import {
+  buildMcpxSkillMarkdown,
+  buildSchemaSelector,
+  parseMcpxSkillServers,
+  writeMcpxSkill,
+} from "../src/skill-template";
 
 describe("mcpx skill template", () => {
   it("builds argc schema selectors for selected servers", () => {
@@ -31,6 +36,15 @@ describe("mcpx skill template", () => {
     expect(content).toContain("mcpx <server> <tool> --input @- <<'JSON'");
   });
 
+  it("builds temporary mcpx skill markdown without project-local wording", () => {
+    const content = buildMcpxSkillMarkdown(["slack"], { projectLocal: false });
+
+    expect(content).toContain('servers: ["slack"]');
+    expect(content).toContain("configured MCP servers");
+    expect(content).not.toContain("project-approved MCP servers");
+    expect(content).toContain('mcpx --schema=".slack"');
+  });
+
   it("parses selected servers from existing skill frontmatter", () => {
     expect(
       parseMcpxSkillServers(`---