argsbarg 7.0.5 → 7.0.7

package/src/docs/docs.test.ts

@@ -76,9 +76,6 @@ test("docs rejects reserved topic keys", () => {
   docs.topics["cli-schema"] = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics["cli-schema"];
-  docs.topics.skill = { text: "nope" };
-  expect(() => cliValidateProgram(root)).toThrow(/reserved/);
-  delete docs.topics.skill;
   docs.topics.cli = { text: "nope" };
   expect(() => cliValidateProgram(root)).toThrow(/reserved/);
   delete docs.topics.cli;
@@ -128,9 +125,6 @@ test("built-in docs work without topics", async () => {
   const cliRef = await new Cli(root).invoke(["docs", "cli"]);
   expect(cliRef.exitCode).toBe(0);
   expect(cliRef.stdout).toContain("CLI API reference");
-  const skill = await new Cli(root).invoke(["docs", "skill"]);
-  expect(skill.exitCode).toBe(0);
-  expect(skill.stdout).toContain("name: myapp");
 });
 
 test("bare docs shows router help", () => {
@@ -253,40 +247,14 @@ test("skipsRequiredAppConfigExit includes docs and config builtins", () => {
   expect(skipsRequiredAppConfigExit(["run"], caps)).toBe(false);
 });
 
-test("docs skill prints Cursor SKILL.md", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "skill"]);
-  expect(result.exitCode).toBe(0);
-  expect(result.stdout).toContain("---");
-  expect(result.stdout).toContain("name: myapp");
-  expect(result.stdout).toContain("## Commands");
-  expect(result.stdout).toContain("For full detail, open `reference.md`");
-  expect(result.stdout).not.toContain("#### Options");
-  expect(result.stdout).not.toContain("mcp.json");
-});
-
-/** Docs skill help recommends configure. */
-test("docs skill help recommends configure", async () => {
-  const presentation = cliPresentationRoot(docsFixture());
-  const docsNode = presentation.commands.find((c) => c.key === "docs");
-  expect(docsNode && "commands" in docsNode).toBe(true);
-  if (docsNode && "commands" in docsNode) {
-    const skill = docsNode.commands.find((c) => c.key === "skill");
-    expect(skill?.description).toContain("reference agent SKILL");
-    expect(skill?.description).toContain("configure");
-    expect(skill?.notes).toBeUndefined();
-    expect(docsNode.notes).toContain("--save");
-    expect(docsNode.notes).not.toContain("install --skill");
-  }
-});
-
-test("presentation includes docs cli-schema and skill", () => {
+test("presentation includes docs cli-schema and cli without skill", () => {
   const presentation = cliPresentationRoot(docsFixture());
   const docsNode = presentation.commands.find((c) => c.key === "docs");
   expect(docsNode && "commands" in docsNode).toBe(true);
   if (docsNode && "commands" in docsNode) {
     expect(docsNode.commands.some((c) => c.key === "cli-schema")).toBe(true);
     expect(docsNode.commands.some((c) => c.key === "cli")).toBe(true);
-    expect(docsNode.commands.some((c) => c.key === "skill")).toBe(true);
+    expect(docsNode.commands.some((c) => c.key === "skill")).toBe(false);
   }
 });
 
@@ -296,7 +264,7 @@ test("completions offer docs subcommands", () => {
   expect(bash).toContain("readme) echo");
   expect(bash).toContain("cli-schema) echo");
   expect(bash).toContain("cli) echo");
-  expect(bash).toContain("skill) echo");
+  expect(bash).not.toContain("skill) echo");
 });
 
 test("generateMcpGuide includes schema URI and .agents install", () => {
@@ -329,16 +297,6 @@ test("docs cli --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
-test("docs skill --save keeps frontmatter first", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
-  expect(result.exitCode).toBe(0);
-  const text = readFileSync(join(workDir, "docs/skill.md"), "utf8");
-  expect(text.startsWith("---\n")).toBe(true);
-  expect(text).toContain("name: myapp");
-  const hint = "<!-- Generated by myapp docs skill --save; do not edit. -->";
-  expect(text.indexOf(hint)).toBeGreaterThan(text.indexOf("---\n", 4));
-});
-
 test("docs cli-schema --save writes JSON file", async () => {
   const result = await new Cli(docsFixture()).invoke(["docs", "cli-schema", "--save"]);
   expect(result.exitCode).toBe(0);

package/src/docs/resolve.ts

@@ -1,13 +1,16 @@
+/*
+This module resolves and prints bundled documentation topics for the `docs` built-in.
+*/
+
 import { cliSchemaJson } from "../core/schema.ts";
 import type { CliDocsConfig, CliProgram } from "../core/types.ts";
 import { openApiJson } from "../http/openapi.ts";
-import { generateSkillBundle } from "../skill/generate.ts";
 import { generateCliGuide } from "./cli-guide.ts";
 import { generateHttpGuide } from "./http-guide.ts";
 import { generateMcpGuide } from "./mcp-guide.ts";
 
 /** Built-in docs subcommand keys not allowed in `docs.topics`. */
-export const DOCS_BUILTIN_TOPIC_KEYS = ["http", "mcp", "all", "cli-schema", "cli", "skill", "openapi"] as const;
+export const DOCS_BUILTIN_TOPIC_KEYS = ["http", "mcp", "all", "cli-schema", "cli", "openapi"] as const;
 
 export type DocsBuiltinTopicKey = (typeof DOCS_BUILTIN_TOPIC_KEYS)[number];
 
@@ -98,9 +101,6 @@ export function docsTopicContent(program: CliProgram, topic: string): string {
   if (topic === "cli") {
     return generateCliGuide(program);
   }
-  if (topic === "skill") {
-    return `${generateSkillBundle(program).skillMd}\n`;
-  }
   const text = docsTopicText(program, topic);
   return text.endsWith("\n") ? text : `${text}\n`;
 }

package/src/docs/save.ts

@@ -1,5 +1,10 @@
+/*
+This module persists bundled documentation topics to disk when `--save` is passed.
+It writes documentation under `./docs/`.
+*/
+
 import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
 import { generatedFileHtmlComment, insertGeneratedHint } from "../skill/hint.ts";
 import { docsTopicContent } from "./resolve.ts";
@@ -8,34 +13,57 @@ import { docsTopicContent } from "./resolve.ts";
 export const DOCS_SAVE_DIR = "docs";
 
 /** Builtin docs topics generated by argsbarg (not consumer `docs.topics`). */
-export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "skill", "http"] as const;
+export const DOCS_GENERATED_SAVE_TOPICS = ["mcp", "cli", "http"] as const;
 
 /** Whether `--save` should prepend a generated-file hint (argsbarg writers only). */
-export function docsTopicIsGeneratedByArgsbarg(topic: string): boolean {
+export function docsTopicIsGeneratedByArgsbarg(
+  /** Topic name. */
+  topic: string,
+): boolean {
   return (DOCS_GENERATED_SAVE_TOPICS as readonly string[]).includes(topic);
 }
 
 /** HTML comment for generated markdown saved with `--save`. */
-export function docsSaveGeneratedHint(program: CliProgram, topic: string): string {
+export function docsSaveGeneratedHint(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+): string {
   return generatedFileHtmlComment(`${program.key} docs ${topic} --save`);
 }
 
-/** Inserts save hint without breaking YAML frontmatter (`docs skill`). */
-export function applySaveGeneratedHint(program: CliProgram, topic: string, content: string): string {
+/** Inserts save hint into markdown content. */
+export function applySaveGeneratedHint(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+  /** Markdown text. */
+  content: string,
+): string {
   if (!docsTopicIsGeneratedByArgsbarg(topic)) {
     return content;
   }
   const hint = docsSaveGeneratedHint(program, topic);
-  return insertGeneratedHint(content, hint, topic === "skill" ? { afterFrontmatter: true } : undefined);
+  return insertGeneratedHint(content, hint);
 }
 
 /** File body for `--save` (hint on argsbarg-generated markdown only). */
-export function docsTopicContentForSave(program: CliProgram, topic: string): string {
+export function docsTopicContentForSave(
+  /** Program definition. */
+  program: CliProgram,
+  /** Topic name. */
+  topic: string,
+): string {
   return applySaveGeneratedHint(program, topic, docsTopicContent(program, topic));
 }
 
 /** Filename for a saved docs topic. */
-export function docsSaveFilename(topic: string): string {
+export function docsSaveFilename(
+  /** Topic name. */
+  topic: string,
+): string {
   if (topic === "cli-schema") {
     return "cli-schema.json";
   }
@@ -46,17 +74,26 @@ export function docsSaveFilename(topic: string): string {
 }
 
 /** Relative path under cwd for a saved docs topic. */
-export function docsSaveRelativePath(topic: string): string {
+export function docsSaveRelativePath(
+  /** Topic identifier. */
+  topic: string,
+  /** Program root for resolving app-specific paths. */
+  _program?: CliProgram,
+): string {
   return join(DOCS_SAVE_DIR, docsSaveFilename(topic));
 }
 
 /** Writes one docs topic under `./docs/`; returns relative path written. */
-export function saveDocsTopic(program: CliProgram, topic: string): string {
-  const dir = join(process.cwd(), DOCS_SAVE_DIR);
-  mkdirSync(dir, { recursive: true });
-
-  const rel = docsSaveRelativePath(topic);
+export function saveDocsTopic(
+  /** Program definition root. */
+  program: CliProgram,
+  /** Topic identifier to save. */
+  topic: string,
+): string {
+  const rel = docsSaveRelativePath(topic, program);
   const abs = join(process.cwd(), rel);
+  mkdirSync(dirname(abs), { recursive: true });
+
   writeFileSync(abs, docsTopicContentForSave(program, topic), "utf8");
   return rel;
 }

package/src/help.test.ts

@@ -64,7 +64,7 @@ describe("cliResolveNotes", () => {
 });
 
 describe("cliHelpRender", () => {
-  test("docs help lists schema, cli, and skill subcommands", () => {
+  test("docs help lists schema and cli subcommands", () => {
     const root = testProgram({
       key: "app",
       version: "1.0.0",
@@ -85,8 +85,7 @@ describe("cliHelpRender", () => {
     expect(help).toContain("Print the full CLI command tree as JSON.");
     expect(help).toContain("cli");
     expect(help).toContain("markdown");
-    expect(help).toContain("skill");
-    expect(help).toContain("reference agent SKILL");
+    expect(help).not.toContain("skill");
   });
 
   test("root help omits legacy --schema flag", () => {
@@ -106,7 +105,7 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("--schema");
   });
 
-  test("root help shows agent docs hint when docs enabled", () => {
+  test("root help omits agent docs hint when docs enabled", () => {
     const root = testProgram({
       key: "myapp",
       version: "1.0.0",
@@ -117,7 +116,7 @@ describe("cliHelpRender", () => {
       commands: [{ key: "run", description: "Run.", handler: () => {} }],
     });
     const help = cliHelpRender(cliPresentationRoot(root), [], false);
-    expect(help).toContain("For AI agents: `myapp docs skill`.");
+    expect(help).not.toContain("docs skill");
     expect(help).not.toContain("install --skill");
   });
 
@@ -134,7 +133,7 @@ describe("cliHelpRender", () => {
     expect(help).not.toContain("docs skill");
   });
 
-  test("root help includes program notes and agent hint", () => {
+  test("root help includes program notes", () => {
     const root = testProgram({
       key: "myapp",
       version: "1.0.0",
@@ -147,6 +146,6 @@ describe("cliHelpRender", () => {
     });
     const help = cliHelpRender(cliPresentationRoot(root), [], false);
     expect(help).toContain("See `myapp docs readme` for the user guide.");
-    expect(help).toContain("myapp docs skill");
+    expect(help).not.toContain("docs skill");
   });
 });

package/src/skill/generate.ts

@@ -1,29 +1,22 @@
 /*
-This module generates Agent Skills content (SKILL.md + reference.md) from a CLI schema.
+This module generates the MCP routing skill (SKILL.md) for Claude Code plugin zips.
 */
 
 import { defaultConfigEntryTitle } from "../config/entry.ts";
-import { CliOptionKind, type CliProgram } from "../core/types.ts";
-import { generateCliGuide } from "../docs/cli-guide.ts";
+import type { CliProgram } from "../core/types.ts";
 import {
   collectMcpTools,
   leafWireOptions,
-  type McpToolDef,
   mcpServerId,
   resolveMcpSchemaUri,
   sanitizeToolSegment,
 } from "../mcp/tools.ts";
-import { skillDirName } from "./naming.ts";
-
-export interface SkillBundle {
-  dirName: string;
-  skillMd: string;
-  referenceMd: string;
-}
 
 /** MCP routing skill for Claude Code plugin zips (SKILL.md only). */
 export interface PluginSkillBundle {
+  /** Target directory name under `skills/`. */
   dirName: string;
+  /** Generated plugin SKILL.md content. */
   skillMd: string;
 }
 
@@ -43,168 +36,63 @@ function pluginSkillDescription(root: CliProgram): string {
   return truncate(desc, 1024);
 }
 
-/** Builds third-person skill description for YAML frontmatter. */
-function skillDescription(root: CliProgram): string {
-  const tools = collectMcpTools(root);
-  const paths = tools.map((t) => (t.path.length > 0 ? t.path.join(" ") : root.key));
-  const sample = paths.slice(0, 5).join(", ");
-  const more = paths.length > 5 ? `, and ${paths.length - 5} more` : "";
-  const desc = `Operates the ${root.key} CLI (${sample}${more}). Use when the user mentions ${root.key}${paths.length > 0 ? `, ${paths.slice(0, 3).join(", ")}` : ""}, or related tasks.`;
-  return truncate(desc, 1024);
-}
-
-/** CLI path with required single-slot positionals for the compact catalog. */
-function commandCatalogPath(root: CliProgram, tool: McpToolDef): string {
-  const base = tool.path.length > 0 ? `${root.key} ${tool.path.join(" ")}` : root.key;
-  const slots = (tool.leaf.positionals ?? [])
-    .filter((p) => (p.argMin ?? 1) > 0 && (p.argMax ?? 1) === 1)
-    .map((p) => `<${p.name}>`);
-  if (slots.length === 0) {
-    return base;
-  }
-  return `${base} ${slots.join(" ")}`;
-}
-
-/** Formats one command line for the SKILL.md index (details live in reference.md). */
-function formatCommandEntry(root: CliProgram, tool: McpToolDef): string {
-  const cliPath = commandCatalogPath(root, tool);
-  let line = `- **\`${cliPath}\`** — ${tool.leaf.description}`;
-  const opts = leafWireOptions(tool.leaf);
-  const flags = opts.filter((o) => o.kind === CliOptionKind.Presence).map((o) => `--${o.name}`);
-  if (flags.length > 0) {
-    line += ` (flags: ${flags.join(", ")})`;
-  }
-  const enums = opts.filter((o) => o.kind === CliOptionKind.Enum && o.choices?.length);
-  for (const e of enums) {
-    line += ` (\`--${e.name}\`: ${e.choices?.join(" | ")})`;
-  }
-  const varargs = (tool.leaf.positionals ?? []).filter((p) => (p.argMax ?? 1) === 0);
-  if (varargs.length > 0) {
-    line += ` (varargs: ${varargs.map((p) => p.name).join(", ")})`;
-  }
-  return line;
-}
-
+/** Builds configuration section lines for YAML and markdown. */
 function buildConfigurationSection(root: CliProgram): string[] {
-  const schema = root.appConfig?.entries;
-  if (!schema || Object.keys(schema).length === 0) {
+  if (!root.appConfig || Object.keys(root.appConfig.entries).length === 0) {
     return [];
   }
-  const lines = ["## Configuration", ""];
-  for (const [key, entry] of Object.entries(schema)) {
-    const label = entry.title ?? defaultConfigEntryTitle(key);
-    const envNote = entry.env ? ` (env: \`${entry.env}\`)` : "";
-    lines.push(`- **${label}** (\`${key}\`${envNote}) — ${entry.description}`);
+  const entries = root.appConfig.entries;
+  const lines: string[] = ["## Configuration", ""];
+  for (const name of Object.keys(entries).sort()) {
+    const entry = entries[name];
+    if (!entry) continue;
+    const title = defaultConfigEntryTitle(name);
+    const envStr = entry.env ? ` (env: \`${entry.env}\`)` : "";
+    const desc = entry.description ? ` — ${entry.description}` : "";
+    lines.push(`- **${name}** (\`${title}\`${envStr})${desc}`);
   }
   lines.push("");
   return lines;
 }
 
-/** 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);
-
+/** Builds SKILL.md for Claude Code plugin zips (MCP routing only). */
+function buildPluginSkillMd(root: CliProgram, dirName: string): string {
   const lines: string[] = [
     "---",
-    `id: ${dirName}`,
-    `name: ${name}`,
-    `description: ${description}`,
-    "enabled: true",
+    `name: ${dirName}`,
+    `description: ${pluginSkillDescription(root)}`,
     "---",
     "",
     `# ${root.key}`,
     "",
     root.description,
     "",
-    "## Execution",
+    "## MCP Tools",
     "",
-    "Invoke via shell:",
+    `Server id: \`${mcpServerId(root)}\``,
     "",
-    "```bash",
-    `${root.key} <subcommand> [options] [args]`,
-    "```",
+    "Prefer using MCP tools over terminal commands when available.",
     "",
-    "## Commands",
+    `- Run \`tools/list\` against \`${mcpServerId(root)}\` to discover tools.`,
+    `- Read schema resource \`${resolveMcpSchemaUri(root)}\` for types.`,
     "",
   ];
 
-  if (tools.length === 0) {
-    lines.push("(No leaf commands in schema.)", "");
-  } else {
+  const tools = collectMcpTools(root);
+  if (tools.length > 0) {
+    lines.push("### Available tools", "");
     for (const tool of tools) {
-      lines.push(formatCommandEntry(root, tool));
+      const toolName = sanitizeToolSegment(tool.path.join("_"));
+      const desc = tool.leaf.description;
+      const wire = leafWireOptions(tool.leaf);
+      const flags = wire.length > 0 ? ` (flags: ${wire.map((o) => `--${o.name}`).join(", ")})` : "";
+      lines.push(`- \`${toolName}\` — ${desc}${flags}`);
     }
     lines.push("");
   }
 
   lines.push(...buildConfigurationSection(root));
 
-  lines.push(
-    "## Pitfalls",
-    "",
-    "- Pass `--` before arguments that look like flags.",
-    "",
-    "## Reference",
-    "",
-    `For full detail, open \`reference.md\` in this skill directory (same as \`${root.key} docs cli\`).`,
-    "",
-    "## Install location",
-    "",
-    "Install follows the https://dotagentsprotocol.com:",
-    "",
-    `- Auto-install: \`${root.key} configure install\` 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}/\``,
-    "",
-  );
-
-  return lines.join("\n");
-}
-
-/** Builds reference.md with the compact `docs cli` markdown guide. */
-function buildReferenceMd(root: CliProgram): string {
-  return generateCliGuide(root, { compact: true });
-}
-
-/** Builds MCP routing SKILL.md for Claude Code plugin zips. */
-function buildPluginSkillMd(root: CliProgram, dirName: string): string {
-  const name = sanitizeToolSegment(root.key);
-  const description = pluginSkillDescription(root);
-  const serverId = mcpServerId(root);
-  const schemaUri = resolveMcpSchemaUri(root);
-
-  const lines: string[] = [
-    "---",
-    `name: ${name}`,
-    `description: ${description}`,
-    "---",
-    "",
-    `# ${root.key}`,
-    "",
-    root.description,
-    "",
-    "## Execution",
-    "",
-    "This plugin bundles an MCP server. Use MCP tools to fulfill requests.",
-    "",
-    `- Server id: \`${serverId}\` (configured in plugin \`.mcp.json\`)`,
-    "- Tool names and argument shapes come from MCP `tools/list`",
-    `- Full schema: \`${schemaUri}\` (same as \`${root.key} docs cli-schema\`)`,
-    "",
-  ];
-
-  lines.push(...buildConfigurationSection(root));
-
   lines.push(
     "## Claude Code plugin",
     "",
@@ -223,13 +111,3 @@ export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
     skillMd: buildPluginSkillMd(root, dirName),
   };
 }
-
-/** 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, dirName),
-    referenceMd: buildReferenceMd(root),
-  };
-}

package/src/skill/hint.ts

@@ -1,6 +1,11 @@
+/*
+This module provides HTML comment hints embedded in generated documentation
+and plugin artifacts to mark them as machine-generated.
+*/
+
 import type { CliProgram } from "../core/types.ts";
 
-/** YAML frontmatter block at the start of SKILL.md. */
+/** YAML frontmatter block at the start of markdown files. */
 export const MARKDOWN_FRONTMATTER_RE = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
 
 /** HTML comment marking argsbarg-generated markdown. */
@@ -19,42 +24,11 @@ export function insertGeneratedHint(content: string, hint: string, options?: { a
   return `${hint}${content}`;
 }
 
-/** Hint for `configure` skill output files. */
-export function skillInstallHint(program: CliProgram): string {
-  return generatedFileHtmlComment(`${program.key} configure`);
-}
-
-/** Applies install hints to SKILL.md (after frontmatter) and reference.md. */
-export function applySkillInstallHints(
-  program: CliProgram,
-  skillMd: string,
-  referenceMd: string,
-): { skillMd: string; referenceMd: string } {
-  const hint = skillInstallHint(program);
-  return {
-    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
-    referenceMd: insertGeneratedHint(referenceMd, hint),
-  };
-}
-
 /** Hint for `mcp bundle` plugin skill output. */
 export function skillBundleHint(program: CliProgram): string {
   return generatedFileHtmlComment(`${program.key} mcp bundle`);
 }
 
-/** Applies bundle hints to SKILL.md (after frontmatter) and reference.md. */
-export function applySkillBundleHints(
-  program: CliProgram,
-  skillMd: string,
-  referenceMd: string,
-): { skillMd: string; referenceMd: string } {
-  const hint = skillBundleHint(program);
-  return {
-    skillMd: insertGeneratedHint(skillMd, hint, { afterFrontmatter: true }),
-    referenceMd: insertGeneratedHint(referenceMd, hint),
-  };
-}
-
 /** Applies bundle hint to plugin SKILL.md (after frontmatter). */
 export function applyPluginSkillHint(program: CliProgram, skillMd: string): string {
   return insertGeneratedHint(skillMd, skillBundleHint(program), { afterFrontmatter: true });

package/src/skill/install.ts

@@ -1,16 +1,22 @@
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+/*
+This module provides paths and helpers for agent skill directories (~/.agents/skills/<key>/).
+Skill generation is removed; skills are authored directly in repositories under skills/<app>/SKILL.md.
+*/
+
 import { join } from "node:path";
 import type { CliProgram } from "../core/types.ts";
-import { displayHomePath, userHome } from "../paths/host.ts";
-import { generateSkillBundle } from "./generate.ts";
-import { applySkillInstallHints } from "./hint.ts";
+import { userHome } from "../paths/host.ts";
 import { skillDirName } from "./naming.ts";
 
 export { skillDirName } from "./naming.ts";
 
+/** Options for agent skill installation. */
 export interface SkillInstallOpts {
+  /** When true, installs to user home ~/.agents/skills/<key>/; otherwise project .agents/skills/<key>/. */
   global?: boolean;
+  /** When true, removes existing directory before installing. */
   rimraf?: boolean;
+  /** When true, computes file paths without writing to disk. */
   dry?: boolean;
 }
 
@@ -20,33 +26,6 @@ export function resolveAgentsSkillDir(root: CliProgram, global = true): string {
   return join(base, ".agents", "skills", skillDirName(root.key));
 }
 
-/** Writes skill.md, SKILL.md (compatibility copy), and reference.md; returns changed file paths. */
-export function cliSkillInstall(root: CliProgram, opts: SkillInstallOpts): string[] {
-  const bundle = generateSkillBundle(root);
-  const { skillMd, referenceMd } = applySkillInstallHints(root, bundle.skillMd, bundle.referenceMd);
-  const dir = resolveAgentsSkillDir(root, opts.global ?? true);
-  const changed: string[] = [];
-
-  if (opts.rimraf && existsSync(dir) && !opts.dry) {
-    rmSync(dir, { recursive: true, force: true });
-  }
-
-  const skillPath = join(dir, "skill.md");
-  const skillCompatPath = join(dir, "SKILL.md");
-  const refPath = join(dir, "reference.md");
-
-  if (!opts.dry) {
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(skillPath, skillMd, "utf8");
-    writeFileSync(skillCompatPath, skillMd, "utf8");
-    writeFileSync(refPath, referenceMd, "utf8");
-    process.stdout.write(`Installed skill to ${displayHomePath(dir)}/\n`);
-  }
-
-  changed.push(skillPath, skillCompatPath, refPath);
-  return changed;
-}
-
 /** True when the plan action kind installs the agent skill bundle. */
 export function isAgentSkillActionKind(kind: string): boolean {
   return kind === "agent-skill";