argsbarg 7.0.6 → 7.0.8

package/src/builtins/builtins.test.ts

@@ -5,7 +5,6 @@ Tests for builtins/builtins module behavior.
 import { describe, expect, test } from "bun:test";
 import { ParseKind, parse, postParseValidate } from "../core/parse.ts";
 import type { CliProgram } from "../core/types.ts";
-import { cliBuiltinDocsGroup } from "../docs/builtin.ts";
 import { resolveCapabilities } from "../runtime/capabilities.ts";
 import { completionBashScript, completionFishScript, completionZshScript } from ".";
 import { cliBuiltinConfigureCommand } from "./configure.ts";
@@ -41,7 +40,6 @@ const noMcp: CliProgram = {
 describe("builtins help copy", () => {
   test("configure command includes capability-aware description", () => {
     const configure = cliBuiltinConfigureCommand(fixture);
-    expect(configure.description).toContain("agent skills");
     expect(configure.description).toContain("MCP config");
     expect(configure.notes).toContain("brew upgrade");
     const commandKeys = configure.commands.map((c) => c.key);
@@ -55,7 +53,7 @@ describe("builtins help copy", () => {
 
   test("configure copy omits MCP when mcpServer unset", () => {
     const caps = resolveCapabilities(noMcp);
-    expect(configureCommandDescription(noMcp, caps)).toBe("Set up agent skills for this app (binary via Homebrew).");
+    expect(configureCommandDescription(noMcp, caps)).toBe("Set up agent artifacts for this app (binary via Homebrew).");
     expect(configureCommandDescription(noMcp, caps)).not.toContain("MCP");
     const configure = cliBuiltinConfigureCommand(noMcp);
     expect(configure.description).not.toContain("MCP");
@@ -172,22 +170,3 @@ describe("schema export builtins", () => {
     expect(builtins.map((b) => b.key)).not.toContain("completion");
   });
 });
-
-/** Tests for docs skill topic copy. */
-describe("docs skill topic copy", () => {
-  test("mentions configure when configure is enabled", () => {
-    const withDocs: CliProgram = {
-      ...noMcp,
-      docs: { topics: { readme: { text: "# r\n" } } },
-    };
-    const skill = cliBuiltinDocsGroup(withDocs).commands.find((c) => c.key === "skill");
-    expect(skill?.description).toContain("configure");
-
-    const configureOff: CliProgram = {
-      ...withDocs,
-      configure: { enabled: false },
-    };
-    const skillOff = cliBuiltinDocsGroup(configureOff).commands.find((c) => c.key === "skill");
-    expect(skillOff?.description).not.toContain("configure");
-  });
-});

package/src/builtins/configure-copy.ts

@@ -1,19 +1,19 @@
-/** Capability-aware labels for configure builtin and docs copy. */
+/*
+This module provides capability-aware labels for the configure built-in and docs copy.
+*/
 
 import type { CliProgram } from "../core/types.ts";
 import type { CliCapabilities } from "../runtime/capabilities.ts";
 
-type Kind = "skills" | "mcp" | "config";
+type Kind = "mcp" | "config";
 
 const LABEL: Record<Kind, { prose: string; short: string }> = {
-  skills: { prose: "agent skills", short: "skills" },
   mcp: { prose: "MCP config", short: "MCP" },
   config: { prose: "app config", short: "config" },
 };
 
 function enabledKinds(program: CliProgram, caps: CliCapabilities): Kind[] {
   const kinds: Kind[] = [];
-  if (program.skill?.enabled) kinds.push("skills");
   if (caps.mcp && program.mcpServer?.enabled) kinds.push("mcp");
   if (program.appConfig && Object.keys(program.appConfig.entries).length > 0) kinds.push("config");
   return kinds;
@@ -39,13 +39,6 @@ export function configureCommandDescription(program: CliProgram, caps: CliCapabi
   return `Set up ${prose(program, caps)} for this app (binary via Homebrew).`;
 }
 
-export function docsSkillTopicDescription(_program: CliProgram, caps: CliCapabilities): string {
-  if (caps.configure) {
-    return "Print a reference agent SKILL; run `configure install` to install an optimized copy.";
-  }
-  return "Print a reference agent SKILL for AI agents.";
-}
-
 export function configureCommandNotes(program: CliProgram, _caps: CliCapabilities): string {
   const app = program.key;
   const lines = [

package/src/builtins/presentation.ts

@@ -77,15 +77,12 @@ export function cliPresentationRoot(program: CliProgram): CliRouter {
   };
 }
 
-/** Root help notes: consumer `program.notes` plus agent discovery when `docs` is enabled. */
-export function presentationRootNotes(program: CliProgram, caps: CliCapabilities): string | undefined {
+/** Root help notes from consumer `program.notes`. */
+export function presentationRootNotes(program: CliProgram, _caps: CliCapabilities): string | undefined {
   const parts: string[] = [];
   if ((program.notes ?? "").trim().length > 0) {
     parts.push((program.notes ?? "").trim());
   }
-  if (caps.docs) {
-    parts.push(`For AI agents: \`${program.key} docs skill\`.`);
-  }
   if (parts.length === 0) {
     return undefined;
   }

package/src/configure/artifacts/status.test.ts

@@ -43,7 +43,7 @@ describe("resolveInstallTargetPreview", () => {
     expect(preview.skill).toEqual([]);
   });
 
-  test("skill app includes skill in all scope when enabled", () => {
+  test("skill app does not include skill in all scope (skill gen removed)", () => {
     const program: CliProgram = {
       key: "cliapp",
       version: "1",
@@ -53,8 +53,8 @@ describe("resolveInstallTargetPreview", () => {
     };
     const paths = resolveInstallPaths(program);
     const preview = resolveInstallTargetPreview(program, paths);
-    expect(preview.all).toEqual(["skill"]);
-    expect(preview.skill).toEqual(["skill"]);
+    expect(preview.all).toEqual([]);
+    expect(preview.skill).toEqual([]);
     expect(preview.mcp).toEqual([]);
   });
 });
@@ -81,8 +81,8 @@ describe("printInstallStatus json", () => {
       const parsed = JSON.parse(chunks.join("")) as {
         effective: { all: string[]; mcp: string[]; skill: string[] };
       };
-      expect(parsed.effective.all).toEqual(["skill", "agentsMcp"]);
-      expect(parsed.effective.skill).toEqual(["skill"]);
+      expect(parsed.effective.all).toEqual(["agentsMcp"]);
+      expect(parsed.effective.skill).toEqual([]);
       expect(parsed.effective.mcp).toEqual(["agentsMcp"]);
     } finally {
       process.stdout.write = orig;

package/src/configure/artifacts/target-effective.ts

@@ -32,8 +32,7 @@ function artifactDefaults(
   program?: Pick<CliProgram, "mcpServer" | "skill">,
 ): { enabled: boolean; includedInAll: boolean } {
   if (key === "skill") {
-    const on = program?.skill?.enabled === true;
-    return { enabled: on, includedInAll: on };
+    return { enabled: false, includedInAll: false };
   }
   if (key === "agentsMcp") {
     const on = program?.mcpServer?.enabled === true;

package/src/configure/artifacts/target-skill.ts

@@ -1,6 +1,11 @@
+/*
+Agent shell skill directory install (~/.agents/skills/<key>/).
+Skill generation is removed; skills are authored directly in repositories under skills/<app>/SKILL.md.
+Uninstall cleans up legacy/stale skill directories if present.
+*/
+
 import { existsSync } from "node:fs";
 import type { CliProgram } from "../../core/types.ts";
-import { cliSkillInstall } from "../../skill/install.ts";
 import { displayInstallPath, type InstallPaths } from "./paths.ts";
 import { InstallTarget } from "./target-base.ts";
 import type {
@@ -15,6 +20,7 @@ import type {
 } from "./target-types.ts";
 import { uninstallSkillDir } from "./uninstall.ts";
 
+/** Specification for an agent skill install target. */
 export interface SkillHostSpec {
   key: CliInstallArtifactKey;
   actionKind: InstallActionKind;
@@ -71,20 +77,8 @@ export class SkillInstallTarget extends InstallTarget {
     return this.spec.skillDir(paths);
   }
 
-  protected buildInstallActions(ctx: TargetPlanContext): InstallAction[] {
-    const dir = this.spec.skillDir(ctx.paths);
-    const displayDir = `${displayInstallPath(dir)}/`;
-    return [
-      {
-        kind: this.actionKind,
-        summary: `${this.spec.label.toLowerCase()}: ${displayDir}`,
-        message: `Installing ${this.spec.label.toLowerCase()} to ${displayDir}`,
-        run: () => {
-          cliSkillInstall(ctx.root, { global: true, rimraf: true, dry: ctx.dry });
-          return [];
-        },
-      },
-    ];
+  protected buildInstallActions(_ctx: TargetPlanContext): InstallAction[] {
+    return [];
   }
 
   protected buildUninstallActions(ctx: TargetPlanContext): UninstallAction[] {

package/src/configure/artifacts/targets/skill.ts

@@ -1,5 +1,12 @@
+/*
+Install target definition for agent skill cleanup and status.
+Skill generation is removed; skills are authored directly in repositories under skills/<app>/SKILL.md.
+*/
+
+import { existsSync } from "node:fs";
 import { SkillInstallTarget } from "../target-skill.ts";
 
+/** Registered install target for agent skill directory cleanup and detection. */
 export const skillTarget = new SkillInstallTarget({
   key: "skill",
   actionKind: "agent-skill",
@@ -8,5 +15,5 @@ export const skillTarget = new SkillInstallTarget({
   skillDir: (p) => p.agentsSkillDir,
   detectedKey: "skill",
   statusField: "skill",
-  isAvailable: (root) => root.skill?.enabled === true,
+  isAvailable: (_root, p) => existsSync(p.agentsSkillDir),
 });

package/src/configure/artifacts/targets.test.ts

@@ -42,10 +42,10 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(t.agentsMcp.includedInAll).toBe(false);
   });
 
-  test("skill enabled via program.skill", () => {
+  test("skill disabled even when program.skill is set (skill gen removed)", () => {
     const t = resolveEffectiveInstallTargets(undefined, { skill: { enabled: true } });
-    expect(t.skill.enabled).toBe(true);
-    expect(t.skill.includedInAll).toBe(true);
+    expect(t.skill.enabled).toBe(false);
+    expect(t.skill.includedInAll).toBe(false);
   });
 
   test("agentsMcp in --all when mcpServer enabled", () => {
@@ -69,7 +69,7 @@ describe("resolveEffectiveInstallTargets", () => {
     expect(isArtifactInScope("agentsMcp", scope, effective, "install-scoped", program)).toBe(true);
   });
 
-  test("scoped --skill includes skill when program.skill.enabled", () => {
+  test("scoped --skill omits skill because skill generation is removed", () => {
     const program: CliProgram = {
       key: "app",
       version: "1",
@@ -79,6 +79,6 @@ describe("resolveEffectiveInstallTargets", () => {
     };
     const effective = resolveEffectiveInstallTargets(program.configure, program);
     const scope = { skill: true };
-    expect(isArtifactInScope("skill", scope, effective, "install-scoped", program)).toBe(true);
+    expect(isArtifactInScope("skill", scope, effective, "install-scoped", program)).toBe(false);
   });
 });

package/src/configure/configure.test.ts

@@ -88,19 +88,19 @@ describe("detect installed", () => {
 
 /** Tests for install plan. */
 describe("install plan", () => {
-  test("buildUpdatePlan greenfield includes skill when enabled", () => {
+  test("buildUpdatePlan greenfield omits skill because skill generation is removed", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildUpdatePlan(fixture, paths, parseInstallOpts({ reinstall: "1", yes: "1" }));
     expect(plan.length).toBeGreaterThan(0);
-    expect(plan.some((a) => a.kind === "agent-skill")).toBe(true);
+    expect(plan.some((a) => a.kind === "agent-skill")).toBe(false);
     expect(plan.some((a) => a.kind === "app")).toBe(false);
   });
 
-  test("buildInstallPlan --all omits app self-install", () => {
+  test("buildInstallPlan --all omits app self-install and skill", () => {
     const paths = resolveInstallPaths(fixture);
     const plan = buildInstallPlan(fixture, paths, parseInstallOpts({ all: "1" }));
     expect(plan.some((a) => a.kind === "app")).toBe(false);
-    expect(plan.some((a) => a.kind === "agent-skill")).toBe(true);
+    expect(plan.some((a) => a.kind === "agent-skill")).toBe(false);
     expect(plan.some((a) => a.kind === "agents-mcp")).toBe(true);
   });
 

package/src/core/parse.test.ts

@@ -3,9 +3,6 @@ Domain-specific regression tests (split from index.test.ts).
 */
 
 import { expect, test } from "bun:test";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
 import { $ } from "bun";
 import { completionBashScript, completionZshScript } from "../builtins/index.ts";
 import { cliPresentationRoot } from "../builtins/presentation.ts";
@@ -13,8 +10,7 @@ import { cliHelpRender } from "../help.ts";
 import { Cli, CliFallbackMode, CliOptionKind, type CliProgram } from "../index.ts";
 import { applyShellEnv } from "../mcp/env.ts";
 import { allMcpResources, collectMcpTools, mcpToolCallToArgv, resolveMcpSchemaUri } from "../mcp/tools.ts";
-import { generatePluginSkillBundle, generateSkillBundle } from "../skill/generate.ts";
-import { cliSkillInstall } from "../skill/install.ts";
+import { generatePluginSkillBundle } from "../skill/generate.ts";
 import {
   enumMcpFixture,
   nestedDocsFallbackFixture,
@@ -1352,31 +1348,6 @@ test("configure.prefix is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/configure\.prefix removed/);
 });
 
-/** Tests that generateSkillBundle includes frontmatter and intent-based router. */
-test("generateSkillBundle includes frontmatter and intent-based router", () => {
-  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("Options & Help Discovery");
-  expect(bundle.skillMd).toContain("Run `nested.ts <subcommand> --help`");
-  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("Workflow & Pitfalls");
-  expect(bundle.skillMd).toContain("~/.agents/skills/nested.ts/");
-  expect(bundle.skillMd).not.toContain("reference.md");
-  expect(bundle.skillMd).not.toContain("#### Options");
-  expect(bundle.skillMd).not.toContain("CLI API reference");
-  expect(bundle.skillMd).not.toContain("mcp.json");
-  expect(bundle.skillMd).not.toContain("Prefer MCP");
-  expect(bundle.skillMd).not.toContain("tools/call");
-  expect(bundle.skillMd).not.toContain("Generated by");
-  expect((bundle as unknown as Record<string, unknown>).referenceMd).toBeUndefined();
-});
-
 /** Tests that generatePluginSkillBundle is MCP routing stub without shell catalog. */
 test("generatePluginSkillBundle is MCP routing stub without shell catalog", () => {
   const bundle = generatePluginSkillBundle(nestedMcpFixture);
@@ -1391,85 +1362,3 @@ test("generatePluginSkillBundle is MCP routing stub without shell catalog", () =
   expect(bundle.skillMd).not.toContain("`nested.ts stat owner lookup <path>`");
   expect(bundle.skillMd).not.toContain("## Commands");
 });
-
-/** 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, { 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, "skill.md"))).toBe(true);
-    expect(existsSync(join(skillDir, "reference.md"))).toBe(false);
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("Options & Help Discovery");
-    const skillText = readFileSync(join(skillDir, "SKILL.md"), "utf8");
-    expect(skillText.startsWith("---\n")).toBe(true);
-    const hint = "<!-- Generated by nested.ts configure; do not edit. -->";
-    expect(skillText.indexOf(hint)).toBeGreaterThan(skillText.indexOf("---\n", 4));
-  } finally {
-    process.chdir(prev);
-    rmSync(cwd, { recursive: true, force: true });
-  }
-});
-
-/** CliSkillInstall removes legacy reference.md if present. */
-test("cliSkillInstall removes legacy reference.md if present", () => {
-  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-legacy-"));
-  const prev = process.cwd();
-  process.chdir(cwd);
-  try {
-    const skillDir = join(cwd, ".agents", "skills", "nested.ts");
-    mkdirSync(skillDir, { recursive: true });
-    writeFileSync(join(skillDir, "reference.md"), "legacy reference content", "utf8");
-    expect(existsSync(join(skillDir, "reference.md"))).toBe(true);
-
-    cliSkillInstall(nestedMcpFixture, { global: false, rimraf: false });
-    expect(existsSync(join(skillDir, "SKILL.md"))).toBe(true);
-    expect(existsSync(join(skillDir, "reference.md"))).toBe(false);
-  } finally {
-    process.chdir(prev);
-    rmSync(cwd, { recursive: true, force: true });
-  }
-});
-
-/** CliSkillInstall global uses TEST_USER_HOME agents skills directory. */
-test("cliSkillInstall global uses TEST_USER_HOME agents skills directory", () => {
-  const home = mkdtempSync(join(tmpdir(), "argsbarg-home-"));
-  const prevTestHome = process.env.TEST_USER_HOME;
-  process.env.TEST_USER_HOME = home;
-  try {
-    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 (prevTestHome === undefined) {
-      delete process.env.TEST_USER_HOME;
-    } else {
-      process.env.TEST_USER_HOME = prevTestHome;
-    }
-    rmSync(home, { recursive: true, force: true });
-  }
-});
-
-/** CliSkillInstall rimraf overwrites existing directory. */
-test("cliSkillInstall rimraf overwrites existing directory", () => {
-  const cwd = mkdtempSync(join(tmpdir(), "argsbarg-skill-dup-"));
-  const prev = process.cwd();
-  process.chdir(cwd);
-  try {
-    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, ".agents", "skills", "nested.ts", "SKILL.md"), "utf8")).toContain(
-      "stat owner lookup",
-    );
-  } finally {
-    process.chdir(prev);
-    rmSync(cwd, { recursive: true, force: true });
-  }
-});

package/src/core/types.ts

@@ -404,9 +404,11 @@ export interface CliCompletionConfig {
   enabled?: boolean;
 }
 
-/** Opt-in agent skill install to `~/.agents/skills/<key>/` (default: disabled). */
+/**
+ * @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`.
+ */
 export interface CliSkillConfig {
-  /** When `true`, install the agent skill via `configure install`. Default false when omitted. */
+  /** @deprecated Skill generation was removed; this property has no effect. */
   enabled?: boolean;
 }
 
@@ -678,7 +680,7 @@ export type CliProgram = CliNode & {
   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. */
+  /** @deprecated Skill generation was removed; skills are authored directly in repositories under `skills/<app>/SKILL.md`. */
   skill?: CliSkillConfig;
   /** Program version (printed by the `version` built-in and MCP serverInfo). */
   version: string;

package/src/core/validate.ts

@@ -105,7 +105,9 @@ function validateConfigureConfig(program: CliProgram): void {
   }
 
   if ("agentIntegration" in configure) {
-    throw new CliSchemaValidationError("configure.agentIntegration removed; use program.skill.enabled for skills");
+    throw new CliSchemaValidationError(
+      "configure.agentIntegration removed; skills are authored under skills/<app>/SKILL.md",
+    );
   }
 
   if (!configure.targets) return;
@@ -119,7 +121,7 @@ function validateConfigureConfig(program: CliProgram): void {
   for (const key of legacySkillKeys) {
     if (key in targets) {
       throw new CliSchemaValidationError(
-        `configure.targets.${key} removed; use program.skill.enabled for agent skill install`,
+        `configure.targets.${key} removed; skills are authored under skills/<app>/SKILL.md`,
       );
     }
   }

package/src/docs/builtin.ts

@@ -1,6 +1,9 @@
-import { docsSkillTopicDescription } from "../builtins/configure-copy.ts";
+/*
+This module builds the built-in `docs` command group router.
+It registers bundled documentation topics (CLI guide, schema, MCP, HTTP) as subcommands.
+*/
+
 import { type CliLeaf, type CliOption, CliOptionKind, type CliProgram, type CliRouter } from "../core/types.ts";
-import { resolveCapabilities } from "../runtime/capabilities.ts";
 import {
   DOCS_ROUTER_DESCRIPTION,
   docsEnabled,
@@ -74,7 +77,6 @@ export function cliBuiltinDocsGroup(program: CliProgram): CliRouter {
   leaves.push(
     docsLeaf(program, "cli-schema", "Print the full CLI command tree as JSON."),
     docsLeaf(program, "cli", "Print the full command reference as markdown."),
-    docsLeaf(program, "skill", docsSkillTopicDescription(program, resolveCapabilities(program))),
   );
 
   return {

package/src/docs/cli-guide.ts

@@ -6,7 +6,7 @@ import { cliPositionalLabel, cliResolveNotes } from "../help.ts";
 
 /** Options for {@link generateCliGuideBody} and {@link generateCliGuide}. */
 export interface CliGuideBodyOptions {
-  /** Omit embedded outputSchema JSON; point to `docs cli-schema` instead (skill reference). */
+  /** Omit embedded outputSchema JSON; point to `docs cli-schema` instead. */
   compact?: boolean;
 }
 
@@ -72,7 +72,7 @@ function formatNotesBlockquote(notes: string, appKey: string): string {
     .join("\n");
 }
 
-/** Markdown section for leaf outputSchema (docs cli / skill reference). */
+/** Markdown section for leaf outputSchema (docs cli). */
 function formatOutputSchemaSection(schema: Record<string, unknown>): string[] {
   return [
     "#### Output",
@@ -173,7 +173,7 @@ function renderCommandNode(
   }
 }
 
-/** Command-tree markdown shared by `docs cli` and generated agent skills (no API doc header). */
+/** Command-tree markdown for `docs cli` (no API doc header). */
 export function generateCliGuideBody(program: CliProgram, opts: CliGuideBodyOptions = {}): string {
   const schema = cliSchemaExport(program);
   const lines: string[] = [];

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,41 +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("--help");
-  expect(result.stdout).not.toContain("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);
   }
 });
 
@@ -297,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", () => {
@@ -330,17 +297,6 @@ test("docs cli --save prepends generated hint", async () => {
   expect(text).toContain("CLI API reference");
 });
 
-test("docs skill --save writes skills/<app>/SKILL.md and keeps frontmatter first", async () => {
-  const result = await new Cli(docsFixture()).invoke(["docs", "skill", "--save"]);
-  expect(result.exitCode).toBe(0);
-  expect(result.stdout.trim()).toBe("skills/myapp/SKILL.md");
-  const text = readFileSync(join(workDir, "skills/myapp/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`;
 }