feat: install skills from a source, view their files, and let agents change Tools

apps/server/package.json

@@ -51,6 +51,7 @@
     "node-pty": "^1.2.0-beta.15",
     "playwright-core": "1.60.0",
     "proper-lockfile": "4.1.2",
+    "skills": "1.7.1",
     "stream-chain": "^4.2.5",
     "stream-json": "3.6.0",
     "yaml": "catalog:",

apps/server/src/auth/RpcAuthorization.ts

@@ -142,6 +142,10 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.pullRequestsLabelCandidates]: AuthOrchestrationReadScope,
   [WS_METHODS.sourceControlLookupRepository]: AuthOrchestrationReadScope,
   [WS_METHODS.subscribeProjectClones]: AuthOrchestrationReadScope,
+  // The server lists skill folders itself; a client never names a path.
+  [WS_METHODS.skillsInspect]: AuthFilesystemReadScope,
+  // A preview unpacks a source into a temp folder and deletes it.
+  [WS_METHODS.skillsPreview]: AuthFilesystemReadScope,
   [WS_METHODS.projectsListEntries]: AuthFilesystemReadScope,
   [WS_METHODS.projectsReadFile]: AuthFilesystemReadScope,
   [WS_METHODS.projectsSearchContents]: AuthFilesystemReadScope,

apps/server/src/bin.ts

@@ -20,6 +20,10 @@ if (
   if (command === "acp-mcp-bridge" || command === "acp-mcp-call") {
     const { runAcpMcpCliFastPath } = await import("./mcp/AcpMcpStdioBridge.ts");
     await runAcpMcpCliFastPath(command, process.argv.slice(3));
+  } else if (command === "skills-cli") {
+    // Option parsing belongs to the skills CLI, so it skips the T3 CLI entirely.
+    const { runSkillsCli } = await import("./cli/skillsCli.ts");
+    await runSkillsCli(process.argv.slice(3));
   } else {
     const { runCli } = await import("./binCli.ts");
     runCli();

apps/server/src/binCli.ts

@@ -8,6 +8,7 @@ import * as CliError from "effect/cli/CliError";
 import * as NetService from "@t3tools/shared/Net";
 import packageJson from "../package.json" with { type: "json" };
 import { acpMcpBridgeCommand, acpMcpCallCommand } from "./cli/acpMcpBridge.ts";
+import { skillsCliCommand } from "./cli/skillsCli.ts";
 import { authCommand } from "./cli/auth.ts";
 import { appCommand } from "./cli/app.ts";
 import { browserCommand } from "./cli/browser.ts";
@@ -67,6 +68,7 @@ export const makeCli = ({ cloudEnabled = hasCloudPublicConfig } = {}) =>
       ),
       acpMcpBridgeCommand,
       acpMcpCallCommand,
+      skillsCliCommand,
       startCommand,
       serveCommand,
       appCommand,

apps/server/src/cli/skillsCli.ts

@@ -0,0 +1,24 @@
+import * as Effect from "effect/Effect";
+import { Argument, Command } from "effect/cli";
+
+/**
+ * `t3 skills-cli <args…>` runs the bundled `skills` CLI (vercel-labs/skills),
+ * the installer `npx skills` runs. The server spawns it through this hidden
+ * subcommand so installs need no Node or npm of their own: the CLI is part of
+ * this build, and runs as a child so its `process.exit` and prompts stay out
+ * of the server.
+ */
+export async function runSkillsCli(args: ReadonlyArray<string>): Promise<void> {
+  // The CLI reads its command from argv[2] onward.
+  process.argv = [process.argv[0] ?? "node", "skills", ...args];
+  await import("skills/dist/cli.mjs");
+}
+
+/** Real invocations dispatch through the bin.ts fast path before the CLI graph loads. */
+export const skillsCliCommand = Command.make("skills-cli", {
+  args: Argument.String("args").pipe(Argument.variadic()),
+}).pipe(
+  Command.withDescription("Run the bundled skills installer."),
+  Command.unlisted,
+  Command.withHandler(({ args }) => Effect.promise(() => runSkillsCli(args))),
+);

apps/server/src/mcp/McpHttpServer.ts

@@ -26,7 +26,9 @@ import * as OrchestratorMcpService from "./OrchestratorMcpService.ts";
 import { PreviewControlsToolkit } from "./toolkits/previewControls/tools.ts";
 import * as PreviewControlsHandlers from "./toolkits/previewControls/handlers.ts";
 import { EnvironmentToolkit } from "./toolkits/environment/tools.ts";
+import { ToolsToolkit } from "./toolkits/tools/tools.ts";
 import * as EnvironmentHandlers from "./toolkits/environment/handlers.ts";
+import * as ToolsHandlers from "./toolkits/tools/handlers.ts";
 import { ProjectToolkit } from "./toolkits/project/tools.ts";
 import * as ProjectHandlers from "./toolkits/project/handlers.ts";
 import { AttachmentToolkit } from "./toolkits/attachment/tools.ts";
@@ -818,6 +820,8 @@ const layerEnvironmentRegistration = toolkitRegistration(
 
 const layerProjectRegistration = toolkitRegistration(ProjectToolkit, ProjectHandlers.layer);
 
+const layerToolsRegistration = toolkitRegistration(ToolsToolkit, ToolsHandlers.layer);
+
 export const layerAttachmentToolkit = toolkitRegistration(
   AttachmentToolkit,
   AttachmentHandlers.layer,
@@ -857,6 +861,7 @@ export const layer = Layer.mergeAll(
   layerAttachmentToolkit,
   layerProjectRegistration,
   layerEnvironmentRegistration,
+  layerToolsRegistration,
   layerPreviewControlsRegistration,
   layerWorktreeToolkitRegistration,
   layerPullRequestsToolkit,

apps/server/src/mcp/toolkits/tools/handlers.test.ts

@@ -0,0 +1,123 @@
+import { expect, it } from "@effect/vitest";
+import {
+  DEFAULT_SERVER_SETTINGS,
+  EnvironmentId,
+  ProjectId,
+  ProviderInstanceId,
+  type ServerSettings,
+  type ServerSettingsPatch,
+  ThreadId,
+} from "@t3tools/contracts";
+import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
+
+import * as Environment from "../../../environment/ServerEnvironment.ts";
+import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts";
+import * as ThreadManagement from "../../../orchestration-v2/ThreadManagementService.ts";
+import * as ProjectService from "../../../project/ProjectService.ts";
+import * as Settings from "../../../serverSettings.ts";
+import * as SkillLibrary from "../../../skills/SkillLibrary.ts";
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import { liveThreadShell } from "../../McpToolAccess.testkit.ts";
+import * as ToolsHandlers from "./handlers.ts";
+import { ToolsToolkit } from "./tools.ts";
+
+const environmentId = EnvironmentId.make("environment:tools");
+const threadId = ThreadId.make("thread:tools");
+const projectId = ProjectId.make("project:tools");
+
+const initial: ServerSettings = {
+  ...DEFAULT_SERVER_SETTINGS,
+  disabledSkills: ["grill-me"],
+  mcpServers: {
+    context7: {
+      enabled: true,
+      transport: {
+        type: "stdio",
+        command: "npx",
+        args: ["-y", "@upstash/context7-mcp"],
+        env: [{ name: "CONTEXT7_API_KEY", value: "secret", sensitive: true }],
+      },
+    },
+  },
+};
+
+it.effect("switches skills and servers for a project as one patch, and never returns secrets", () =>
+  Effect.gen(function* () {
+    const settings = yield* Ref.make(initial);
+    const patches = yield* Ref.make<ReadonlyArray<ServerSettingsPatch>>([]);
+    const layerDependencies = Layer.mergeAll(
+      ThreadCommandExecutor.layer,
+      Layer.succeed(McpInvocationContext.McpInvocationContext, {
+        environmentId,
+        requestNamespace: "provider:tools",
+        thread: {
+          threadId,
+          providerSessionId: "provider:tools",
+          providerInstanceId: ProviderInstanceId.make("codex"),
+        },
+        client: undefined,
+        capabilities: new Set(["orchestration" as const]),
+        issuedAt: 0,
+      }),
+      Layer.mock(ThreadManagement.ThreadManagementService)({
+        getThreadShell: () => Effect.succeed(liveThreadShell(threadId)),
+      }),
+      Layer.mock(Environment.ServerEnvironment)({
+        getDescriptor: Effect.succeed({
+          environmentId,
+          label: "Test",
+          platform: { os: "linux", arch: "x64" },
+          serverVersion: "0.0.0",
+          capabilities: { repositoryIdentity: false },
+        }),
+      }),
+      Layer.mock(Settings.ServerSettingsService)({
+        getSettings: Ref.get(settings),
+        updateSettings: (patch) =>
+          Ref.update(patches, (list) => [...list, patch]).pipe(
+            Effect.andThen(
+              Ref.updateAndGet(settings, (current) => applyServerSettingsPatch(current, patch)),
+            ),
+          ),
+      }),
+      Layer.mock(ProjectService.ProjectService)({}),
+      Layer.mock(SkillLibrary.SkillLibrary)({}),
+    );
+    yield* Effect.gen(function* () {
+      const toolkit = yield* ToolsToolkit;
+      const result = yield* toolkit
+        .handle("t3_tools_update", {
+          projectId,
+          skills: [
+            { name: "grill-me", enabled: true },
+            { name: "tdd", enabled: false },
+          ],
+          mcpServers: [{ name: "context7", enabled: false }],
+        })
+        .pipe(Stream.unwrap, Stream.runCollect);
+      expect(result.at(-1)?.result).toEqual({
+        disabledSkills: ["tdd"],
+        mcpServers: [{ name: "context7", enabled: false, summary: "npx -y @upstash/context7-mcp" }],
+      });
+      // One write, so the project never sits half-changed.
+      expect(yield* Ref.get(patches)).toHaveLength(1);
+      expect((yield* Ref.get(settings)).projectSettingsOverrides[projectId]).toEqual({
+        disabledSkills: { "grill-me": false, tdd: true },
+        mcpServers: { context7: { enabled: false } },
+      });
+      // The environment itself is unchanged.
+      expect((yield* Ref.get(settings)).disabledSkills).toEqual(["grill-me"]);
+    }).pipe(
+      Effect.provide(
+        McpToolAccess.HandlersLayer.layer(ToolsHandlers.layer).pipe(
+          Layer.provideMerge(layerDependencies),
+        ),
+      ),
+    );
+  }),
+);

apps/server/src/mcp/toolkits/tools/handlers.ts

@@ -0,0 +1,164 @@
+import {
+  mcpServerTransportSummary,
+  OrchestratorMcpFailure,
+  type ProjectId,
+  type ServerSettings,
+  type ServerSettingsPatch,
+  type SkillInstallTarget,
+} from "@t3tools/contracts";
+import { mcpServerEnabledPatch, skillsDisabledPatch } from "@t3tools/shared/agentTools";
+import { resolveProjectSettings } from "@t3tools/shared/projectSettings";
+import { applyServerSettingsPatch } from "@t3tools/shared/serverSettings";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+
+import * as Environment from "../../../environment/ServerEnvironment.ts";
+import * as ThreadCommandExecutor from "../../../orchestration-v2/ThreadCommandExecutor.ts";
+import * as ProjectService from "../../../project/ProjectService.ts";
+import * as Settings from "../../../serverSettings.ts";
+import * as SkillLibrary from "../../../skills/SkillLibrary.ts";
+import * as McpInvocationContext from "../../McpInvocationContext.ts";
+import * as McpToolAccess from "../../McpToolAccess.ts";
+import { readCaller, unavailable } from "../../threadAccess.ts";
+import { ToolsToolkit } from "./tools.ts";
+
+/** What agents and the Tools page see for one scope; secrets never leave the server. */
+function toolsState(settings: ServerSettings, projectId: ProjectId | undefined) {
+  const resolved = resolveProjectSettings(settings, projectId ?? null).settings;
+  return {
+    disabledSkills: [...resolved.disabledSkills],
+    mcpServers: Object.entries(resolved.mcpServers).map(([name, server]) => ({
+      name,
+      enabled: server.enabled,
+      summary: mcpServerTransportSummary(server.transport),
+    })),
+  };
+}
+
+const access = Effect.gen(function* () {
+  const context = yield* readCaller();
+  const environment = yield* Environment.ServerEnvironment;
+  const descriptor = yield* environment.getDescriptor;
+  if (descriptor.environmentId !== context.scope.environmentId)
+    return yield* new OrchestratorMcpFailure({
+      code: "capability_denied",
+      message: "This credential belongs to another environment.",
+    });
+  return { settings: yield* Settings.ServerSettingsService };
+});
+
+/** The project's checkout, as the target of an install. */
+const projectTarget = (projectId: ProjectId | undefined) =>
+  Effect.gen(function* () {
+    if (projectId === undefined) return { kind: "environment" } satisfies SkillInstallTarget;
+    const projects = yield* ProjectService.ProjectService;
+    const project = yield* projects.getById(projectId).pipe(Effect.mapError(unavailable));
+    if (Option.isNone(project))
+      return yield* new OrchestratorMcpFailure({
+        code: "invalid_request",
+        message: "The project was not found.",
+      });
+    return { kind: "project", cwd: project.value.workspaceRoot } satisfies SkillInstallTarget;
+  });
+
+const libraryFailure = (error: { readonly message: string }) =>
+  new OrchestratorMcpFailure({ code: "invalid_request", message: error.message });
+
+/** Run a change while the calling thread holds its lock, re-checking it first. */
+const asCaller = <A, E, R, CR>(
+  check: Effect.Effect<unknown, OrchestratorMcpFailure, CR>,
+  change: Effect.Effect<A, E, R>,
+) =>
+  Effect.gen(function* () {
+    const scope = yield* McpInvocationContext.McpInvocationContext;
+    const executor = yield* ThreadCommandExecutor.ThreadCommandExecutor;
+    const guarded = check.pipe(Effect.andThen(change));
+    return yield* scope.thread === undefined
+      ? guarded
+      : executor.withLock(scope.thread.threadId, guarded);
+  });
+
+export const layer = McpToolAccess.toLayer(ToolsToolkit, {
+  t3_tools_read: McpToolAccess.reads((input) =>
+    Effect.gen(function* () {
+      const { settings } = yield* access;
+      const current = yield* settings.getSettings.pipe(Effect.mapError(unavailable));
+      return toolsState(current, input.projectId);
+    }),
+  ),
+  t3_tools_update: McpToolAccess.writesEnvironment((input, check) =>
+    asCaller(
+      check,
+      Effect.gen(function* () {
+        const { settings } = yield* access;
+        const projectId = input.projectId ?? null;
+        // Each change builds on the last; the patch is then read off the result,
+        // so everything lands in one write.
+        let next = yield* settings.getSettings.pipe(Effect.mapError(unavailable));
+        for (const enabled of [true, false]) {
+          const names = (input.skills ?? [])
+            .filter((skill) => skill.enabled === enabled)
+            .map((skill) => skill.name);
+          if (names.length > 0) {
+            next = applyServerSettingsPatch(
+              next,
+              skillsDisabledPatch(next, projectId, names, !enabled),
+            );
+          }
+        }
+        for (const server of input.mcpServers ?? []) {
+          const step = mcpServerEnabledPatch(next, projectId, server.name, server.enabled);
+          if (step === null)
+            return yield* new OrchestratorMcpFailure({
+              code: "invalid_request",
+              message: `There is no Settings → Tools server named ${server.name}.`,
+            });
+          next = applyServerSettingsPatch(next, step);
+        }
+        const servers = (input.mcpServers ?? []).map((server) => server.name);
+        const patch: ServerSettingsPatch =
+          projectId === null
+            ? {
+                ...(input.skills === undefined ? {} : { disabledSkills: next.disabledSkills }),
+                ...(servers.length === 0
+                  ? {}
+                  : {
+                      mcpServers: Object.fromEntries(
+                        servers.map((name) => [name, next.mcpServers[name] ?? null]),
+                      ),
+                    }),
+              }
+            : ({
+                projectSettingsOverrides: {
+                  [projectId]: next.projectSettingsOverrides[projectId] ?? null,
+                },
+              } as ServerSettingsPatch);
+        const saved = yield* settings.updateSettings(patch).pipe(Effect.mapError(unavailable));
+        return toolsState(saved, input.projectId);
+      }),
+    ),
+  ),
+  t3_skills_install: McpToolAccess.writesEnvironment((input, check) =>
+    asCaller(
+      check,
+      Effect.gen(function* () {
+        const library = yield* SkillLibrary.SkillLibrary;
+        const target = yield* projectTarget(input.projectId);
+        return yield* library
+          .install({ source: input.source, skills: input.skills, target })
+          .pipe(Effect.mapError(libraryFailure));
+      }),
+    ),
+  ),
+  t3_skills_remove: McpToolAccess.writesEnvironment((input, check) =>
+    asCaller(
+      check,
+      Effect.gen(function* () {
+        const library = yield* SkillLibrary.SkillLibrary;
+        const target = yield* projectTarget(input.projectId);
+        yield* library.remove({ name: input.name, target }).pipe(Effect.mapError(libraryFailure));
+        return {};
+      }),
+    ),
+  ),
+});