argsbarg 7.0.5 → 7.0.7

package/examples/full-example-json/justfile

@@ -58,7 +58,6 @@ dev *ARGS:
 docgen: schemagen
     @just run docs cli-schema --save
     @just run docs cli --save
-    @just run docs skill --save
     @just run docs mcp --save
     @just run docs http --save
     @just run docs openapi --save

package/examples/full-example-json/{docs/skill.md → skills/full-example-json/SKILL.md}

@@ -1,11 +1,9 @@
 ---
 id: full-example-json
 name: full-example-json
-description: Operates the full-example-json CLI (echo, render-json, status, workspaces get, workspaces post, and 4 more). Use when the user mentions full-example-json, echo, render-json, status, or related tasks.
+description: Operates the full-example-json CLI (echo, render-json, status, workspaces :id delete, workspaces :id get, and 4 more). Use when the user mentions full-example-json, echo, render-json, status, or related tasks.
 enabled: true
 ---
-<!-- Generated by full-example-json docs skill --save; do not edit. -->
-
 
 # full-example-json
 
@@ -19,25 +17,29 @@ Invoke via shell:
 full-example-json <subcommand> [options] [args]
 ```
 
+## Options & Help Discovery
+
+- Run `full-example-json <subcommand> --help` to inspect flags, choices, and positional arguments before running unfamiliar subcommands.
+- Run `full-example-json --help` at the root for top-level options and command routing.
+
 ## Commands
 
 - **`full-example-json echo`** — Echo a message (MCP-friendly leaf).
 - **`full-example-json render-json`** — Echo a JSON message (schema-first JSON leaf demo).
-- **`full-example-json status`** — Show app version. (flags: --json)
-- **`full-example-json workspaces get`** — List workspaces.
-- **`full-example-json workspaces post`** — Create a workspace.
+- **`full-example-json status`** — Show app version.
+- **`full-example-json workspaces :id delete`** — Delete a workspace.
 - **`full-example-json workspaces :id get`** — Get one workspace.
-- **`full-example-json workspaces :id put`** — Replace a workspace.
 - **`full-example-json workspaces :id patch`** — Patch a workspace name.
-- **`full-example-json workspaces :id delete`** — Delete a workspace.
+- **`full-example-json workspaces :id put`** — Replace a workspace.
+- **`full-example-json workspaces get`** — List workspaces.
+- **`full-example-json workspaces post`** — Create a workspace.
 
-## Pitfalls
+## Workflow & Pitfalls
 
+- Always run `full-example-json <subcommand> --help` instead of guessing options or reading large doc files.
 - Pass `--` before arguments that look like flags.
-
-## Reference
-
-For full detail, open `reference.md` in this skill directory (same as `full-example-json docs cli`).
+- Pass `--yes` for non-interactive execution when confirmation is required.
+- Pass `--json` when machine-readable structured output is supported.
 
 ## Install location
 

package/examples/full-example-json/src/program.ts

@@ -28,6 +28,5 @@ export const program = {
   key: createIdentity.key,
   mcpServer: { enabled: true },
   readiness: AppDb.checkReadiness,
-  skill: { enabled: true },
   version: "1.0.0",
 } satisfies CliProgram;

package/index.d.ts

@@ -533,9 +533,11 @@ export interface CliCompletionConfig {
 	/** When `false`, hide/disable `completion` (default: enabled). */
 	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;
 }
 /** Context for {@link CliConfigureConfig} lifecycle hooks. */
@@ -807,7 +809,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argsbarg",
-  "version": "7.0.5",
+  "version": "7.0.7",
   "main": "./src/index.ts",
   "module": "./src/index.ts",
   "dependencies": {

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/cli-tool/create.test.ts

@@ -83,6 +83,7 @@ describe("argsbarg create", () => {
     const tree = renderCreateTree(baseOpts({ key: "testapp" }));
     expect(tree.has("justfile")).toBe(true);
     expect(tree.has("scripts/create-identity.ts")).toBe(true);
+    expect(tree.has("skills/testapp/SKILL.md")).toBe(true);
     const identity = tree.get("scripts/create-identity.ts");
     expect(identity).toContain('key: "testapp"');
     expect(identity).toContain('template: "cli"');

package/src/cli-tool/create.ts

@@ -330,6 +330,7 @@ function listTemplateFiles(templateId: CreateTemplateId): string[] {
 }
 
 export function renderCreateTree(opts: CreateOptions): Map<string, string> {
+  const tmpl = templateIdentity(opts.templateId);
   const files = new Map<string, string>();
   for (const rel of listTemplateFiles(opts.templateId)) {
     if (rel === CREATE_IDENTITY_REL) {
@@ -338,7 +339,10 @@ export function renderCreateTree(opts: CreateOptions): Map<string, string> {
     }
     const src = join(templateDirFor(opts.templateId), rel);
     const raw = readFileSync(src, "utf8");
-    files.set(rel, substituteTemplateContent(raw, opts));
+    const targetRel = rel.startsWith(`skills/${tmpl.key}/`)
+      ? rel.replace(`skills/${tmpl.key}/`, `skills/${opts.key}/`)
+      : rel;
+    files.set(targetRel, substituteTemplateContent(raw, opts));
   }
   return files;
 }

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, 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 compact command index. */
-test("generateSkillBundle includes frontmatter and compact command index", () => {
-  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");
-  expect(bundle.skillMd).not.toContain("Prefer MCP");
-  expect(bundle.skillMd).not.toContain("tools/call");
-  expect(bundle.skillMd).not.toContain("Generated by");
-  expect(bundle.referenceMd).toContain("CLI API reference");
-  expect(bundle.referenceMd).toContain("#### Options");
-  expect(bundle.referenceMd).not.toContain("Generated by");
-  expect(bundle.referenceMd).not.toContain("```json");
-});
-
 /** Tests that generatePluginSkillBundle is MCP routing stub without shell catalog. */
 test("generatePluginSkillBundle is MCP routing stub without shell catalog", () => {
   const bundle = generatePluginSkillBundle(nestedMcpFixture);
@@ -1391,66 +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, "reference.md"))).toBe(true);
-    expect(readFileSync(join(skillDir, "SKILL.md"), "utf8")).toContain("## Commands");
-    expect(readFileSync(join(skillDir, "reference.md"), "utf8")).toContain("CLI API reference");
-    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));
-    const refText = readFileSync(join(skillDir, "reference.md"), "utf8");
-    expect(refText.startsWith(hint)).toBe(true);
-  } 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[] = [];