argsbarg 6.1.10 → 6.2.0

package/src/core/parse.test.ts

@@ -1149,13 +1149,17 @@ test("configure.prefix is rejected", () => {
 
 /** Tests that generateSkillBundle includes frontmatter and compact command index. */
 test("generateSkillBundle includes frontmatter and compact command index", () => {
-  const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
-  expect(bundle.dirName).toBe("nested_ts");
-  expect(bundle.skillMd).toMatch(/^---\nname: nested_ts\n/);
+  const bundle = generateSkillBundle(nestedMcpFixture);
+  expect(bundle.dirName).toBe("nested.ts");
+  expect(bundle.skillMd).toMatch(/^---\nid: nested\.ts\nname: nested\.ts\n/);
+  expect(bundle.skillMd).toContain("enabled: true");
+  expect(bundle.skillMd).toContain("dotagentsprotocol.com");
+  expect(bundle.skillMd).toContain("~/.claude/skills/nested.ts");
   expect(bundle.skillMd).toContain("## Commands");
   expect(bundle.skillMd).toContain("`nested.ts stat owner lookup <path>`");
   expect(bundle.skillMd).toContain("Invoke via shell:");
   expect(bundle.skillMd).toContain("For full detail, open `reference.md`");
+  expect(bundle.skillMd).toContain("~/.agents/skills/nested.ts/");
   expect(bundle.skillMd).not.toContain("#### Options");
   expect(bundle.skillMd).not.toContain("CLI API reference");
   expect(bundle.skillMd).not.toContain("mcp.json");
@@ -1183,15 +1187,15 @@ test("generatePluginSkillBundle is MCP routing stub without shell catalog", () =
   expect(bundle.skillMd).not.toContain("## Commands");
 });
 
-/** CliSkillInstall writes project Cursor skill files. */
-test("cliSkillInstall writes project Cursor skill files", () => {
+/** CliSkillInstall writes project agent skill files. */
+test("cliSkillInstall writes project agent skill files", () => {
   const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-"));
   const prev = process.cwd();
   process.chdir(cwd);
   try {
-    const files = cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
-    expect(files.some((f) => f.includes(".cursor/skills/nested_ts/"))).toBe(true);
-    const skillDir = join(cwd, ".cursor", "skills", "nested_ts");
+    const files = cliSkillInstall(nestedMcpFixture, { global: false, rimraf: true });
+    expect(files.some((f) => f.includes(".agents/skills/nested.ts/"))).toBe(true);
+    const skillDir = join(cwd, ".agents", "skills", "nested.ts");
     expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
     expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
     expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
@@ -1208,15 +1212,15 @@ test("cliSkillInstall writes project Cursor skill files", () => {
   }
 });
 
-/** CliSkillInstall global uses HOME skills directory. */
-test("cliSkillInstall global uses HOME skills directory", () => {
+/** CliSkillInstall global uses HOME agents skills directory. */
+test("cliSkillInstall global uses HOME agents skills directory", () => {
   const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
   const prevHome = process.env.HOME;
   process.env.HOME = home;
   try {
-    const files = cliSkillInstall(nestedMcpFixture, "cursor", { global: true, rimraf: true });
-    expect(files.some((f) => f.includes(join(home, ".cursor", "skills", "nested_ts")))).toBe(true);
-    expect(existsSync(join(home, ".cursor", "skills", "nested_ts", "SKILL.md"))).toBe(true);
+    const files = cliSkillInstall(nestedMcpFixture, { global: true, rimraf: true });
+    expect(files.some((f) => f.includes(join(home, ".agents", "skills", "nested.ts")))).toBe(true);
+    expect(existsSync(join(home, ".agents", "skills", "nested.ts", "SKILL.md"))).toBe(true);
   } finally {
     if (prevHome === undefined) {
       delete process.env.HOME;
@@ -1233,11 +1237,11 @@ test("cliSkillInstall rimraf overwrites existing directory", () => {
   const prev = process.cwd();
   process.chdir(cwd);
   try {
-    cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
-    writeFileSync(join(cwd, ".cursor", "skills", "nested_ts", "SKILL.md"), "stale", "utf8");
-    const files = cliSkillInstall(nestedMcpFixture, "cursor", { rimraf: true });
+    cliSkillInstall(nestedMcpFixture, { global: false, rimraf: true });
+    writeFileSync(join(cwd, ".agents", "skills", "nested.ts", "SKILL.md"), "stale", "utf8");
+    const files = cliSkillInstall(nestedMcpFixture, { global: false, rimraf: true });
     expect(files.length).toBeGreaterThan(0);
-    expect(readFileSync(join(cwd, ".cursor", "skills", "nested_ts", "SKILL.md"), "utf8")).toContain(
+    expect(readFileSync(join(cwd, ".agents", "skills", "nested.ts", "SKILL.md"), "utf8")).toContain(
       "stat owner lookup",
     );
   } finally {
@@ -1245,18 +1249,3 @@ test("cliSkillInstall rimraf overwrites existing directory", () => {
     rmSync(cwd, { recursive: true, force: true });
   }
 });
-
-/** CliSkillInstall claude target uses .claude/skills. */
-test("cliSkillInstall claude target uses .claude/skills", () => {
-  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-claude-"));
-  const prev = process.cwd();
-  process.chdir(cwd);
-  try {
-    const files = cliSkillInstall(nestedMcpFixture, "claude", { rimraf: true });
-    expect(files.some((f) => f.includes(".claude/skills/nested_ts/"))).toBe(true);
-    expect(readFileSync(join(cwd, ".claude", "skills", "nested_ts", "SKILL.md"), "utf8")).toContain("Claude Code");
-  } finally {
-    process.chdir(prev);
-    rmSync(cwd, { recursive: true, force: true });
-  }
-});

package/src/core/types.ts

@@ -404,24 +404,20 @@ export interface CliCompletionConfig {
   enabled?: boolean;
 }
 
+/** Opt-in agent skill install to `~/.agents/skills/<key>/` (default: disabled). */
+export interface CliSkillConfig {
+  /** When `true`, install and sync the agent skill via `configure --sync`. Default false when omitted. */
+  enabled?: boolean;
+}
+
 /** @experimental */
 export interface CliConfigureConfig {
   /** When `false`, hide/disable `configure` (default: enabled). */
   enabled?: boolean;
-  /**
-   * Default agent integration for sync (`configure --sync`).
-   * - `'mcp'` when `mcpServer.enabled` (default): MCP targets in sync; paired skills excluded.
-   * - `'skill'` when MCP is off (default): skill targets in sync; paired MCP excluded.
-   * - `'both'`: sync MCP and skill for the same host when both are available.
-   */
-  agentIntegration?: InstallAgentIntegration;
   /** Per-artifact gates for configure sync and interactive wizard. See {@link resolveEffectiveInstallTargets}. */
   targets?: CliConfigureTargets;
 }
 
-/** Agent integration mode for install — MCP vs shell skill per host. */
-export type InstallAgentIntegration = "mcp" | "skill" | "both";
-
 /** Boolean or structured gate for one install artifact. */
 export type InstallTargetSpec =
   | boolean
@@ -441,32 +437,8 @@ export interface ResolvedInstallTarget {
 export interface CliConfigureTargets {
   /** App binary status only (Homebrew PATH); no self-install. */
   app?: InstallTargetSpec;
-  /** ChatGPT desktop MCP. Default false. */
-  chatgptMcp?: InstallTargetSpec;
-  /** Claude Code MCP (`~/.claude.json`). Default false. */
-  claudeCodeMcp?: InstallTargetSpec;
-  /** Claude Desktop MCP. Default false. */
-  claudeDesktopMcp?: InstallTargetSpec;
-  /** Claude Code skill. Default false. */
-  claudeSkill?: InstallTargetSpec;
-  /** Codex MCP (`codex mcp add`). Default false. */
-  codexMcp?: InstallTargetSpec;
-  /** Codex skill. Default false. */
-  codexSkill?: InstallTargetSpec;
   /** App config: interactive wizard step in `configure`. Default not in sync. */
   configure?: InstallTargetSpec;
-  /** Cursor MCP. Default false. */
-  cursorMcp?: InstallTargetSpec;
-  /** Cursor skill. Default false. */
-  cursorSkill?: InstallTargetSpec;
-  /** OpenClaw MCP. Default false. */
-  openclawMcp?: InstallTargetSpec;
-  /** OpenClaw skill. Default false. */
-  openclawSkill?: InstallTargetSpec;
-  /** OpenCode MCP. Default false. */
-  opencodeMcp?: InstallTargetSpec;
-  /** OpenCode skill. Default false. */
-  opencodeSkill?: InstallTargetSpec;
 }
 
 /**
@@ -672,26 +644,28 @@ export interface CliLogConfig {
  * May be a leaf or router, plus optional program-level MCP and install config.
  */
 export type CliProgram = CliNode & {
-  /** Program version (printed by the `version` built-in and MCP serverInfo). */
-  version: string;
   /** Schema-driven app config file, bootstrap, and MCP metadata. */
   appConfig?: CliAppConfig;
-  /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
-  mcpServer?: CliMcpServerConfig;
-  /** When set with `enabled: true`, enables the `http` built-in HTTP server. */
-  httpServer?: CliHttpServerConfig;
-  /** Opt-out and defaults for `configure`. */
-  configure?: CliConfigureConfig;
   /** Opt-out for shell completion generation (`completion bash|zsh|fish`). */
   completion?: CliCompletionConfig;
+  /** Opt-out and defaults for `configure`. */
+  configure?: CliConfigureConfig;
   /** Opt-out and optional topics for the `docs` built-in (default: enabled). */
   docs?: CliDocsConfig;
   /** Invoke and error hooks for user commands on CLI, HTTP, and MCP. */
   hooks?: CliProgramHooks;
-  /** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
-  readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+  /** When set with `enabled: true`, enables the `http` built-in HTTP server. */
+  httpServer?: CliHttpServerConfig;
   /** Framework logging (stderr + optional file). */
   log?: CliLogConfig;
+  /** When set with `enabled: true`, enables the `mcp` built-in subcommand. */
+  mcpServer?: CliMcpServerConfig;
+  /** Optional readiness probe for HTTP/MCP `GET /health/readiness` only. */
+  readiness?: (ctx: ReadinessContext) => boolean | Promise<boolean>;
+  /** Opt-in agent skill (`~/.agents/skills/<key>/`). Default disabled when omitted. */
+  skill?: CliSkillConfig;
+  /** Program version (printed by the `version` built-in and MCP serverInfo). */
+  version: string;
 };
 
 /** True when the node is a leaf (has a handler). */

package/src/core/validate.ts

@@ -2,7 +2,6 @@
 This module validates CLI schemas before execution.
 */
 
-import { AGENT_PAIRS, MCP_KEYS, mcpServerRequiredForArtifact } from "../configure/artifacts/target-registry.ts";
 import { reservedDocsTopicResourceUris } from "../docs/mcp-resources.ts";
 import { DOCS_BUILTIN_TOPIC_KEYS, docsEnabled } from "../docs/resolve.ts";
 import { HTTP_RESERVED_TOP_LEVEL_SEGMENTS } from "../http/paths.ts";
@@ -16,8 +15,6 @@ import {
   type CliProgram,
   CliSchemaValidationError,
   CliValueFormat,
-  type InstallAgentIntegration,
-  type InstallTargetSpec,
   isCliLeaf,
   isCliRouter,
   isJsonLeaf,
@@ -98,21 +95,7 @@ function validateConfigBlock(appConfigBlock: import("./types.ts").CliAppConfig):
   }
 }
 
-const PAIR_HOST_LABELS: Record<string, string> = {
-  cursorMcp: "cursor",
-  claudeCodeMcp: "claudeCode",
-  codexMcp: "codex",
-  opencodeMcp: "opencode",
-  openclawMcp: "openclaw",
-};
-
-function installTargetExplicitTruthy(spec: InstallTargetSpec | undefined): boolean {
-  if (spec === undefined || spec === false) return false;
-  if (spec === true) return true;
-  return spec.enabled !== false;
-}
-
-/** Validates `program.configure` targets and agentIntegration. */
+/** Validates `program.configure` targets. */
 function validateConfigureConfig(program: CliProgram): void {
   const configure = program.configure;
   if (!configure) return;
@@ -121,48 +104,48 @@ function validateConfigureConfig(program: CliProgram): void {
     throw new CliSchemaValidationError("configure.prefix removed; app binary installs via Homebrew");
   }
 
+  if ("agentIntegration" in configure) {
+    throw new CliSchemaValidationError("configure.agentIntegration removed; use program.skill.enabled for skills");
+  }
+
   if (!configure.targets) return;
 
   const targets = configure.targets;
   if ("allSkills" in targets || "allMcps" in targets) {
-    throw new CliSchemaValidationError(
-      "configure.targets.allSkills/allMcps removed; use agentIntegration and per-key targets",
-    );
+    throw new CliSchemaValidationError("configure.targets.allSkills/allMcps removed; use per-key targets");
   }
 
-  const integration: InstallAgentIntegration =
-    configure.agentIntegration ?? (program.mcpServer?.enabled === true ? "mcp" : "skill");
-
-  const mcpEnabled = program.mcpServer?.enabled === true;
-
-  for (const [mcpKey, skillKey] of AGENT_PAIRS) {
-    const mcpSpec = targets[mcpKey];
-    const skillSpec = targets[skillKey];
-    const mcpOn = installTargetExplicitTruthy(mcpSpec);
-    const skillOn = installTargetExplicitTruthy(skillSpec);
-    const host = PAIR_HOST_LABELS[mcpKey] ?? mcpKey;
-
-    if (mcpOn && skillOn && integration !== "both") {
+  const legacySkillKeys = ["cursorSkill", "claudeSkill", "codexSkill", "opencodeSkill", "openclawSkill"] as const;
+  for (const key of legacySkillKeys) {
+    if (key in targets) {
       throw new CliSchemaValidationError(
-        `configure.targets: ${host} has both MCP and skill configured; set agentIntegration: 'both' or disable one side`,
+        `configure.targets.${key} removed; use program.skill.enabled for agent skill install`,
       );
     }
+  }
 
-    if (integration === "skill" && mcpOn) {
-      throw new CliSchemaValidationError(
-        `configure.targets.${mcpKey} requires agentIntegration: 'both' when agentIntegration is 'skill'`,
-      );
-    }
-    if (integration === "mcp" && skillOn) {
+  const legacyMcpKeys = [
+    "cursorMcp",
+    "claudeCodeMcp",
+    "claudeDesktopMcp",
+    "codexMcp",
+    "chatgptMcp",
+    "openclawMcp",
+    "opencodeMcp",
+    "agentsMcp",
+  ] as const;
+  for (const key of legacyMcpKeys) {
+    if (key in targets) {
       throw new CliSchemaValidationError(
-        `configure.targets.${skillKey} requires agentIntegration: 'both' when agentIntegration is 'mcp'`,
+        `configure.targets.${key} removed; MCP installs to ~/.agents/mcp.json when mcpServer.enabled`,
       );
     }
   }
 
-  for (const mcpKey of MCP_KEYS) {
-    if (!mcpServerRequiredForArtifact(mcpKey, mcpEnabled) && installTargetExplicitTruthy(targets[mcpKey])) {
-      throw new CliSchemaValidationError(`configure.targets.${mcpKey} requires mcpServer.enabled`);
+  const allowedKeys = new Set(["app", "configure"]);
+  for (const key of Object.keys(targets)) {
+    if (!allowedKeys.has(key)) {
+      throw new CliSchemaValidationError(`configure.targets.${key} is not a valid target key`);
     }
   }
 }

package/src/docs/docs.test.ts

@@ -296,17 +296,17 @@ test("completions offer docs subcommands", () => {
   expect(bash).toContain("skill) echo");
 });
 
-test("generateMcpGuide includes schema URI and configure sync", () => {
+test("generateMcpGuide includes schema URI and .agents install", () => {
   const guide = generateMcpGuide(docsFixture(true));
   expect(guide).toContain("myapp://schema");
+  expect(guide).toContain("~/.agents/mcp.json");
   expect(guide).toContain("~/.cursor/mcp.json");
   expect(guide).toContain("claude_desktop_config.json");
   expect(guide).toContain("## Installation");
   expect(guide).toContain("## Running directly");
   expect(guide).toContain("configure --sync");
-  expect(guide).toContain("brew install myapp");
-  expect(guide).toContain("OpenAI Codex");
-  expect(guide).toContain("ChatGPT");
+  expect(guide).toContain("dotagentsprotocol.com");
+  expect(guide).not.toContain("OpenAI Codex");
 });
 
 test("docs --save writes topic file", async () => {

package/src/docs/mcp-guide.ts

@@ -1,6 +1,7 @@
 import { defaultConfigEntryTitle } from "../config/entry.ts";
 import { displayAppConfigPath } from "../config/file.ts";
-import { expectedOpenCodeMcpEntry, OPENCODE_CONFIG_SCHEMA } from "../configure/artifacts/mcp-opencode.ts";
+import { expectedMcpEntry } from "../configure/artifacts/mcp-config.ts";
+import { resolveClaudeDesktopMcpPath, userHome } from "../configure/artifacts/paths.ts";
 import { collectOptionDefs } from "../core/parse.ts";
 import { CliOptionKind, type CliProgram } from "../core/types.ts";
 import { collectMcpTools, type McpToolDef, mcpServerId, resolveMcpSchemaUri } from "../mcp/tools.ts";
@@ -8,64 +9,41 @@ import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { resolveDocsTopicResourceUri } from "./mcp-resources.ts";
 import { docsEnabled, docsUserTopicKeys, resolveDocsConfig } from "./resolve.ts";
 
-/** Extra host notes for generated `docs mcp` (manual fallbacks and ChatGPT Connectors). */
-function appendManualHostSetup(lines: string[], root: CliProgram, serverId: string): void {
-  const openCodeEntry = expectedOpenCodeMcpEntry(root);
+/** Extra manual client setup notes for generated `docs mcp`. */
+function appendManualClientSetup(
+  lines: string[],
+  _root: CliProgram,
+  serverId: string,
+  entry: { command: string; args: string[] },
+): void {
+  const home = userHome();
+  const claudeDesktopPath = resolveClaudeDesktopMcpPath(home);
+  const mcpServersJson = JSON.stringify({ mcpServers: { [serverId]: entry } }, null, 2);
 
   lines.push(
-    "| OpenCode | `~/.config/opencode/*` (when `~/.config/opencode` exists) |",
-    "| OpenAI Codex | `~/.codex/config.toml` via `codex mcp add` (when `codex` is on PATH) |",
-    "| ChatGPT desktop | `chatgpt_mcp_config.json` (when ChatGPT app data exists) |",
+    "### Manual client setup",
     "",
-    "Claude Desktop paths by platform:",
-    "",
-    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
-    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
-    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
-    "",
-    "ChatGPT desktop JSON (when auto-installed):",
-    "",
-    "- **macOS:** `~/Library/Application Support/ChatGPT/chatgpt_mcp_config.json`",
-    "- **Windows:** `%APPDATA%\\OpenAI\\ChatGPT\\chatgpt_mcp_config.json`",
-    "",
-    "Restart Claude Desktop and ChatGPT desktop after changing their config files.",
-    "",
-    "### Manual fallbacks",
-    "",
-    "**OpenCode** (no `~/.config/opencode` yet):",
+    "Many clients do not read `~/.agents/mcp.json` yet. Copy the `mcpServers` entry from that file, or paste:",
     "",
     "```json",
-    JSON.stringify(
-      {
-        $schema: OPENCODE_CONFIG_SCHEMA,
-        mcp: { [serverId]: openCodeEntry },
-      },
-      null,
-      2,
-    ),
-    "```",
-    "",
-    "**Codex** (`codex` not on PATH):",
-    "",
-    "```toml",
-    `[mcp_servers.${serverId}]`,
-    `command = "${root.key}"`,
-    'args = ["mcp"]',
+    mcpServersJson,
     "```",
     "",
-    `Or after installing Codex CLI: \`codex mcp add ${serverId} -- ${root.key} mcp\`.`,
-    "",
-    "### ChatGPT web (Connectors)",
+    "| Client | Config file |",
+    "| --- | --- |",
+    "| **Cursor** | `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project) |",
+    "| **Claude Code** | `~/.claude.json` under `mcpServers`, or project `.mcp.json` |",
+    "| **Claude Desktop** | See platform paths below |",
     "",
-    `OpenAI's documented path for **ChatGPT web/desktop** is **Settings → Connectors → Developer mode** with a **remote HTTPS MCP URL** — not local stdio. ChatGPT does not spawn \`${root.key} mcp\` directly.`,
+    "Restart Cursor or reload MCP after editing. Restart Claude Desktop after config changes.",
     "",
-    "For local stdio, bridge and tunnel, then register the HTTPS URL in Connectors:",
+    "Claude Desktop config paths:",
     "",
-    `1. Expose \`${root.key} mcp\` over HTTP (e.g. \`mcp-remote\`).`,
-    "2. Tunnel if needed (ngrok, Cloudflare Tunnel).",
-    "3. Add the public URL as a custom connector.",
+    "- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`",
+    "- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`",
+    "- **Linux:** `~/.config/Claude/claude_desktop_config.json`",
     "",
-    "Desktop `chatgpt_mcp_config.json` is merged when the ChatGPT app is installed; support varies by build. Use Connectors when local JSON is absent or tools do not appear.",
+    `On this machine (macOS/Linux): \`${claudeDesktopPath}\``,
     "",
   );
 }
@@ -92,6 +70,7 @@ export function generateMcpGuide(root: CliProgram): string {
     throw new Error("MCP server not enabled");
   }
   const caps = resolveCapabilities(root);
+  const entry = expectedMcpEntry(root);
 
   const lines: string[] = [
     `# MCP server (${root.key})`,
@@ -100,17 +79,16 @@ export function generateMcpGuide(root: CliProgram): string {
     "",
     "## Installation",
     "",
-    "### `configure`",
+    "### `.agents` auto-install",
+    "",
+    "When `mcpServer.enabled` is set, `configure --sync` merges this server into `~/.agents/mcp.json` per the [.agents protocol](https://dotagentsprotocol.com/).",
     "",
   ];
 
   if (caps.configure) {
-    lines.push(
-      `Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`brew install ${root.key}\`). Host configs reference the app by name.`,
-      "",
-    );
+    lines.push(`Install the CLI first so \`${root.key}\` is on your PATH (e.g. \`brew install ${root.key}\`).`, "");
   } else {
-    lines.push(`The CLI binary \`${root.key}\` must already be on your PATH. Host configs reference it by name.`, "");
+    lines.push(`The CLI binary \`${root.key}\` must already be on your PATH.`, "");
   }
 
   lines.push(
@@ -118,30 +96,22 @@ export function generateMcpGuide(root: CliProgram): string {
     `${root.key} configure --sync --yes`,
     "```",
     "",
-    "Merges the server entry below into host config when each host is present:",
+    "Writes or updates `~/.agents/mcp.json` with a `mcpServers` entry for this app.",
     "",
-    "| Host | Config file |",
-    "| --- | --- |",
-    "| Cursor | `~/.cursor/mcp.json` (when `~/.cursor` exists) |",
-    "| Claude Code | `~/.claude.json` |",
-    "| Claude Desktop | `claude_desktop_config.json` (when Claude Desktop app data exists) |",
   );
 
-  appendManualHostSetup(lines, root, serverId);
+  appendManualClientSetup(lines, root, serverId, entry);
 
   lines.push(
     "### Manual `mcpServers` entry",
     "",
-    "For Cursor, Claude, and ChatGPT desktop JSON configs, add under `mcpServers`:",
+    "Same shape as in `~/.agents/mcp.json`:",
     "",
     "```json",
     JSON.stringify(
       {
         mcpServers: {
-          [serverId]: {
-            command: root.key,
-            args: ["mcp"],
-          },
+          [serverId]: entry,
         },
       },
       null,
@@ -174,11 +144,11 @@ export function generateMcpGuide(root: CliProgram): string {
       `Default config file: \`${displayAppConfigPath(root)}\` (flat JSON keys).`,
       "",
     );
-    for (const [key, entry] of Object.entries(root.appConfig.entries)) {
-      const label = entry.title ?? defaultConfigEntryTitle(key);
-      const req = entry.required === false ? "optional" : "required";
-      const envNote = entry.env ? ` → env \`${entry.env}\`` : "";
-      lines.push(`- **${label}** (\`${key}\`, ${req}${envNote}) — ${entry.description}`);
+    for (const [key, entryConfig] of Object.entries(root.appConfig.entries)) {
+      const label = entryConfig.title ?? defaultConfigEntryTitle(key);
+      const req = entryConfig.required === false ? "optional" : "required";
+      const envNote = entryConfig.env ? ` → env \`${entryConfig.env}\`` : "";
+      lines.push(`- **${label}** (\`${key}\`, ${req}${envNote}) — ${entryConfig.description}`);
     }
     lines.push(
       "",

package/src/docs/resolve.ts

@@ -99,7 +99,7 @@ export function docsTopicContent(program: CliProgram, topic: string): string {
     return generateCliGuide(program);
   }
   if (topic === "skill") {
-    return `${generateSkillBundle(program, "cursor").skillMd}\n`;
+    return `${generateSkillBundle(program).skillMd}\n`;
   }
   const text = docsTopicText(program, topic);
   return text.endsWith("\n") ? text : `${text}\n`;

package/src/exports/cli.ts

@@ -32,7 +32,7 @@ export type {
   CliProgram,
   CliRespondBody,
   CliRespondOptions,
-  InstallAgentIntegration,
+  CliSkillConfig,
   InstallTargetSpec,
   ResolvedInstallTarget,
 } from "../core/types.ts";

package/src/index.ts

@@ -52,8 +52,8 @@ export type {
   CliProgramHooks,
   CliRespondBody,
   CliRespondOptions,
+  CliSkillConfig,
   ErrorHookContext,
-  InstallAgentIntegration,
   InstallTargetSpec,
   InvokeFailureKind,
   InvokeHookContext,

package/src/skill/generate.ts

@@ -13,10 +13,7 @@ import {
   resolveMcpSchemaUri,
   sanitizeToolSegment,
 } from "../mcp/tools.ts";
-import type { SkillTarget } from "./naming.ts";
-import { skillDirNameForTarget, skillFrontmatterName } from "./naming.ts";
-
-export type { SkillTarget } from "./naming.ts";
+import { skillDirName } from "./naming.ts";
 
 export interface SkillBundle {
   dirName: string;
@@ -103,16 +100,18 @@ function buildConfigurationSection(root: CliProgram): string[] {
   return lines;
 }
 
-/** Builds SKILL.md body for the given target. */
-function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
-  const name = skillFrontmatterName(root.key, target);
+/** Builds SKILL.md body for the agent skill bundle. */
+function buildSkillMd(root: CliProgram, dirName: string): string {
+  const name = dirName;
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
   const lines: string[] = [
     "---",
+    `id: ${dirName}`,
     `name: ${name}`,
     `description: ${description}`,
+    "enabled: true",
     "---",
     "",
     `# ${root.key}`,
@@ -151,42 +150,24 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
     "",
     `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs cli\`).`,
     "",
+    "## Install location",
+    "",
+    "Install follows the [.agents protocol](https://dotagentsprotocol.com/):",
+    "",
+    `- Auto-install: \`${root.key} configure --sync --yes\` when \`skill.enabled\` → \`~/.agents/skills/${dirName}/\``,
+    `- Cursor and most coding agents read \`~/.agents/skills/\` natively`,
+    "",
+    "**Claude Code (manual):** symlink or copy into Claude's skill directory:",
+    "",
+    "```bash",
+    "mkdir -p ~/.claude/skills",
+    `ln -sf ~/.agents/skills/${dirName} ~/.claude/skills/${dirName}`,
+    "```",
+    "",
+    `Project override (optional): \`.agents/skills/${dirName}/\``,
+    "",
   );
 
-  if (target === "cursor") {
-    lines.push(
-      "## Cursor install location",
-      "",
-      `- Project: \`.cursor/skills/${dirName}/\``,
-      `- Global: \`~/.cursor/skills/${dirName}/\``,
-      "",
-      "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
-      "",
-    );
-  } else if (target === "claude") {
-    lines.push(
-      "## Claude Code",
-      "",
-      `- Invoke with \`/${dirName}\` or let Claude auto-match from the description.`,
-      `- Project skills: \`.claude/skills/${dirName}/\``,
-      `- Global skills: \`~/.claude/skills/${dirName}/\``,
-      `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
-      "",
-    );
-  } else if (target === "codex") {
-    lines.push(
-      "## Codex",
-      "",
-      `- Global: \`~/.codex/skills/${dirName}/\``,
-      "- Enable skills in `~/.codex/config.toml` if required.",
-      "",
-    );
-  } else if (target === "opencode") {
-    lines.push("## OpenCode", "", `- Global: \`~/.config/opencode/skills/${dirName}/\``, "");
-  } else {
-    lines.push("## OpenClaw", "", `- Global: \`~/.openclaw/skills/${dirName}/\``, "");
-  }
-
   return lines.join("\n");
 }
 
@@ -243,12 +224,12 @@ export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
   };
 }
 
-/** Generates SKILL.md and reference.md for Cursor or Claude Code. */
-export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
-  const dirName = skillDirNameForTarget(root.key, target);
+/** Generates SKILL.md and reference.md for agent skill install. */
+export function generateSkillBundle(root: CliProgram): SkillBundle {
+  const dirName = skillDirName(root.key);
   return {
     dirName,
-    skillMd: buildSkillMd(root, target, dirName),
+    skillMd: buildSkillMd(root, dirName),
     referenceMd: buildReferenceMd(root),
   };
 }