@duyquangnvx/create-agent-cli 0.18.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.20.0 (2026-10-28)
+
+### Changed
+
+- **Breaking:** the hints of `OUTPUT_EXISTS` and `ALREADY_EXISTS` read `once the user agrees to replace it, run the Next step` (`them` for several, and `remove` for `skill install` removing an edited file), `NOT_CONFIRMED`'s reads `once the user approves the cost, run the Next step`, and those of `CONFIRMATION_REQUIRED` and `CONFIRMATION_MISMATCH` read `once the user confirms the target, run the Next step`, so an agent asks before adding `--force`, `--yes` or `--confirm` without a skill telling it to. The docs' example `bundle` gives `BUNDLE_EXISTS` the same kind of hint.
+- **Breaking:** the scaffolded skill's Recovering from errors section tells the agent to do what the hint says, and keeps a row only for `LANGUAGE_UNSUPPORTED`, which now asks the user whether an English card will do before running the Next step. The rows for `OUTPUT_EXISTS`, `NOT_CONFIRMED` and every exit code are gone, since the hints and `--help` say the same.
+
+### Fixed
+
+- `--force` in help reads `replace a file the run writes that already exists; --dry-run lists every file it writes`, since `--dry-run` lists the files a run writes, not which of them exist.
+
+## v0.19.0 (2026-10-28)
+
+### Added
+
+- `defineCli({ skill })` takes `{ add: "<command line>" }`, the whole line that installs the skill from a Skill Hub whose line the Runtime cannot build. `doctor`'s `skill` fix and `update`'s `next` give it verbatim for a missing copy or one that states no version, as `npx -y skills update <name> && <line>` when another copy is older than the CLI, and `npx -y skills update <name>` for an older copy alone. `defineCli` throws on an empty line or one holding a line break.
+- The Scaffolder's `--skill-hub-api` takes `--skill-add "<command line>"`, which it writes as `skill: { add }` and, after `! `, as the README's skill line. Either flag without the other is a usage error, `SKILL_ADD_MISSING` or `SKILL_HUB_API_MISSING`, and an empty or multi-line `--skill-add` is `SKILL_ADD_INVALID`.
+
+### Removed
+
+- **Breaking:** `defineCli({ skill })` no longer takes `{ page }`, and `doctor` and `update` no longer name a page; declare the hub's install line as `{ add }`.
+- **Breaking:** the Scaffolder's `--skill-page` and its usage error `SKILL_PAGE_MISSING` are gone; pass `--skill-add`.
+
 ## v0.18.0 (2026-10-28)
 
 ### Added

package/README.md

@@ -6,6 +6,6 @@ Creates a new Agent CLI repository already wired to [`@duyquangnvx/agent-cli`](h
 pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --skill-hub-git https://github.com/<owner>/skills.git
 ```
 
-The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md` whose Agents section points Coding agents at the Runtime's docs in `node_modules`, and a skeleton skill for the new CLI whose setup reference installs, checks and updates it, so a user installs the skill first and lets their agent do the rest. `--skill-hub-git` names the git Skill Hub each release commits that skill to and agents install it from, and `--skill-hub-api` with `--skill-page` an API Skill Hub that gives each user their own install line from that page; `--dependency` instead starts a CLI each project pins as a devDependency, run as `npx -q --no-install <name>`, whose skill ships inside the package for its `skill install` to copy into the project. Pass `--dry-run` to see what it would write.
+The new repository has an Error table, a port, two example Commands (one writing a file at a cost) and their test, a bundled build that stamps the commit and build time into `--version`, CI, a release script, a CHANGELOG, an `AGENTS.md` whose Agents section points Coding agents at the Runtime's docs in `node_modules`, and a skeleton skill for the new CLI whose setup reference installs, checks and updates it, so a user installs the skill first and lets their agent do the rest. `--skill-hub-git` names the git Skill Hub each release commits that skill to and agents install it from, and `--skill-hub-api` with `--skill-add` an API Skill Hub and the whole line that installs the skill from it; `--dependency` instead starts a CLI each project pins as a devDependency, run as `npx -q --no-install <name>`, whose skill ships inside the package for its `skill install` to copy into the project. Pass `--dry-run` to see what it would write.
 
 See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [Runtime's docs](https://github.com/duyquangnvx/cli-for-agent/blob/main/packages/agent-cli/docs/README.md) for how to build on it.

package/dist/bin.js

@@ -6471,7 +6471,7 @@ const YES_FLAG = standardFlag("--yes", {
 	schema: boolean()
 });
 const FORCE_FLAG = standardFlag("--force", {
-	description: "replace the files the run writes when they exist; --dry-run lists them",
+	description: "replace a file the run writes that already exists; --dry-run lists every file it writes",
 	takes: "nothing",
 	schema: boolean()
 });
@@ -6764,9 +6764,9 @@ function toolRows(tools, commands) {
 /** The bundler's stamp, absent when the CLI runs unbundled. Read per call, so a test can define it. */
 function buildStamp() {
 	return {
-		"sha": "e9645e3",
+		"sha": "330940a",
 		"dirty": false,
-		"builtAt": "2026-10-28T08:17:12.000Z"
+		"builtAt": "2026-10-28T15:25:01.000Z"
 	};
 }
 /** The first line of `--version`: the version, and the commit and time of a stamped build. */
@@ -7616,18 +7616,16 @@ async function skillCopies(cliName, version, { cwd, env }) {
 	return copies;
 }
 const has = (copies, wanted) => copies.some(({ state }) => state === wanted);
+function addLineOf(cliName, from) {
+	return "add" in from ? from.add : `npx -y skills add ${from.source} --skill ${cliName} -g`;
+}
 function fixFor(cliName, copies, from) {
 	const update = `npx -y skills update ${cliName}`;
-	const add = from !== void 0 && "source" in from ? `npx -y skills add ${from.source} --skill ${cliName} -g` : void 0;
+	const add = from === void 0 ? void 0 : addLineOf(cliName, from);
 	if (copies.length === 0) return add;
 	if (has(copies, "unversioned") && add !== void 0) return has(copies, "behind") ? `${update} && ${add}` : add;
-	if (from !== void 0 && "page" in from) return has(copies, "behind") ? update : void 0;
 	return has(copies, "behind") || has(copies, "unversioned") ? update : void 0;
 }
-function pageNote(copies, from) {
-	if (from === void 0 || !("page" in from)) return;
-	return copies.length === 0 || has(copies, "unversioned") ? `copy your install line from ${from.page}` : void 0;
-}
 const SKILL_STATE_NOTES = {
 	current: "the same as this build",
 	behind: "older than this build",
@@ -7638,13 +7636,11 @@ const SKILL_STATE_NOTES = {
 function describeCopy({ path, version, state }) {
 	return `${path}${version === void 0 ? "" : ` ${version}`} (${SKILL_STATE_NOTES[state]})`;
 }
-/** A skill on a Skill Hub, which `from` says how to install; with neither, no line adds it. */
+/** A skill on a Skill Hub, which `from` says how to install; without it, no line adds it. */
 function hubSkill(cli, from) {
 	const findingOf = (copies) => {
 		const fix = fixFor(cli.name, copies, from);
-		const note = pageNote(copies, from);
-		const found = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
-		const message = note === void 0 ? found : `${found}; ${note}`;
+		const message = copies.length === 0 ? `no copy of the ${cli.name} skill is installed` : copies.map(describeCopy).join("; ");
 		return fix === void 0 ? {
 			state: "ok",
 			message
@@ -7665,8 +7661,6 @@ function hubSkill(cli, from) {
 		notice: async () => {},
 		nextAt: async (version, ctx) => {
 			const copies = await skillCopies(cli.name, version, ctx);
-			const note = pageNote(copies, from);
-			if (note !== void 0) ctx.notice(note);
 			const fix = fixFor(cli.name, copies, from);
 			return fix === void 0 ? [] : [fix];
 		}
@@ -8028,7 +8022,7 @@ async function checkOutputs({ rerun, commandLine, force, files }, outputs) {
 	throw new CliError({
 		code: OUTPUT_EXISTS,
 		message: `\`${commandLine}\` would overwrite ${existing.join(", ")}`,
-		hint: `to replace ${them}, run the Next step`,
+		hint: `once the user agrees to replace ${them}, run the Next step`,
 		next: [rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
@@ -8050,7 +8044,7 @@ function outputsGuard(files, cwd) {
 			throw new CliError({
 				code: ALREADY_EXISTS,
 				message: error.message,
-				hint: "to replace it, run the Next step",
+				hint: "once the user agrees to replace it, run the Next step",
 				next: [forceStep]
 			}, { cause: error });
 		}
@@ -8176,7 +8170,7 @@ function editedRemovals(plan, ctx) {
 	return new CliError({
 		code: OUTPUT_EXISTS,
 		message: `skill install would remove ${plan.remove.map((file) => join(plan.copy, file)).join(", ")}`,
-		hint: `to remove ${them}, run the Next step`,
+		hint: `once the user agrees to remove ${them}, run the Next step`,
 		next: [ctx.rerun({ add: [FORCE_FLAG.flag] })]
 	});
 }
@@ -9199,13 +9193,15 @@ function checkTree(commands, path, table) {
 		else checkTree(node, at, table);
 	}
 }
-function checkSkillPage({ name, skill }) {
-	if (skill === void 0 || !("page" in skill)) return;
-	if (!URL.canParse(skill.page) || new URL(skill.page).protocol !== "https:") throw new Error(`${name} declares skill.page ${skill.page}, which is not an https URL`);
+function checkSkillAdd({ name, skill }) {
+	if (skill === void 0 || !("add" in skill)) return;
+	const declares = `${name} declares skill.add ${JSON.stringify(skill.add)}`;
+	if (skill.add.trim() === "") throw new Error(`${declares}, which is empty`);
+	if (/[\r\n]/.test(skill.add)) throw new Error(`${declares}, which holds a line break`);
 }
 function checkCli(cli) {
 	const table = errorTableOf(cli);
-	checkSkillPage(cli);
+	checkSkillAdd(cli);
 	if (cli.commands === void 0) {
 		checkCommand(cli.command, commandLabel([], cli.name).join(" "), table);
 		if (skillOf$1(cli, installOf(cli)).kind === "packaged") throw new Error(`${cli.name} declares a Packaged skill, which only a CLI with several Commands can install`);
@@ -10710,7 +10706,7 @@ const CONFIRMATION_MISMATCH = "CONFIRMATION_MISMATCH";
 function checkConfirmation({ rerun, commandLine, given }, expected) {
 	if (given === expected) return;
 	const advice = {
-		hint: "to confirm, run the Next step",
+		hint: "once the user confirms the target, run the Next step",
 		next: [rerun({
 			remove: [CONFIRM_FLAG.flag],
 			add: [CONFIRM_FLAG.flag, expected]
@@ -10736,7 +10732,7 @@ function checkCost({ rerun, commandLine, yes }, cost) {
 	throw new CliError({
 		code: NOT_CONFIRMED,
 		message: `\`${commandLine}\` needs ${YES_FLAG.flag}: ${cost}`,
-		hint: "to approve the cost, run the Next step",
+		hint: "once the user approves the cost, run the Next step",
 		next: [rerun({ add: [YES_FLAG.flag] })]
 	});
 }
@@ -11294,7 +11290,7 @@ async function runProcess(cli) {
 //#region package.json
 var package_default = {
 	name: "@duyquangnvx/create-agent-cli",
-	version: "0.18.0",
+	version: "0.20.0",
 	description: "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
 	type: "module",
 	engines: { "node": ">=22.12.0" },
@@ -11345,31 +11341,36 @@ const PARTIALS_DIR = fileURLToPath(new URL("../partials/", import.meta.url));
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const COMMANDS_ANCHOR = "  commands: {";
 const GLOBAL_INSTALL = `  install: "global",\n`;
-const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub: { git }` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, or set `skill.page` to the Skill Hub's page where each user copies their own install line and `skillHub: { api }` to the API Skill Hub each release publishes the skill to. Then put here what `node dist/bin.js doctor` gives in its `skill` row: the `! npx -y skills add` line of its fix, or the sentence naming the page. -->";
-function skillHubOf({ git, api, page }) {
+const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub: { git }` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, or set `skill.add` to the whole line that installs the skill and `skillHub: { api }` to the API Skill Hub each release publishes the skill to. Then put here what `node dist/bin.js doctor` gives in its `skill` row: the line of its fix, after `! `. -->";
+function skillHubOf({ git, api, add }) {
 	if (git !== void 0 && api !== void 0) throw new UsageError({
 		code: "SKILL_HOMES_CONFLICT",
 		message: "--skill-hub-git and --skill-hub-api each name the Skill Hub the skill goes to",
 		hint: "pass one of them"
 	});
-	if (api !== void 0 && page === void 0) throw new UsageError({
-		code: "SKILL_PAGE_MISSING",
-		message: "--skill-hub-api needs --skill-page, the hub's page where each user copies their own install line",
-		hint: "add --skill-page with the skill's page on the hub"
+	if (api !== void 0 && add === void 0) throw new UsageError({
+		code: "SKILL_ADD_MISSING",
+		message: "--skill-hub-api needs --skill-add, the whole line that installs the skill from the hub",
+		hint: "add --skill-add with the hub's install line for the skill"
 	});
-	if (page !== void 0 && api === void 0) throw new UsageError({
+	if (add !== void 0 && api === void 0) throw new UsageError({
 		code: "SKILL_HUB_API_MISSING",
-		message: "--skill-page names a page of an API Skill Hub, which --skill-hub-api names",
+		message: "--skill-add is the install line of an API Skill Hub, which --skill-hub-api names",
 		hint: "add --skill-hub-api with the hub's URL"
 	});
+	if (add !== void 0 && (add.trim() === "" || /[\r\n]/.test(add))) throw new UsageError({
+		code: "SKILL_ADD_INVALID",
+		message: `--skill-add ${JSON.stringify(add)} is not one command line`,
+		hint: "pass the hub's install line for the skill, on one line"
+	});
 	if (git !== void 0) return {
 		kind: "git",
 		url: git
 	};
-	return api === void 0 || page === void 0 ? void 0 : {
+	return api === void 0 || add === void 0 ? void 0 : {
 		kind: "api",
 		url: api,
-		page
+		add
 	};
 }
 function installModeOf(flags, dependency, binName) {
@@ -11391,7 +11392,7 @@ function installModeOf(flags, dependency, binName) {
 }
 function skillLineOf(skillHub, binName) {
 	if (skillHub === void 0) return NO_SKILL_HUB;
-	return skillHub.kind === "git" ? `\`! npx -y skills add ${skillHub.url} --skill ${binName} -g\`` : `The skill's line is your own: copy your install line from ${skillHub.page}, then type it.`;
+	return skillHub.kind === "git" ? `\`! npx -y skills add ${skillHub.url} --skill ${binName} -g\`` : `\`! ${skillHub.add}\``;
 }
 async function partialsOf(mode, values) {
 	const partial = async (name) => fill(await readFile(join(PARTIALS_DIR, mode, `${name}.md`), "utf8"), values, false).trimEnd();
@@ -11437,7 +11438,7 @@ async function globalSetup(skillHub, packageName, binName) {
 	};
 }
 function skillOf(skillHub) {
-	return skillHub.kind === "git" ? `{ source: ${JSON.stringify(skillHub.url)} }` : `{ page: ${JSON.stringify(skillHub.page)} }`;
+	return skillHub.kind === "git" ? `{ source: ${JSON.stringify(skillHub.url)} }` : `{ add: ${JSON.stringify(skillHub.add)} }`;
 }
 async function dependencySetup(packageName, binName) {
 	const runAs = runAsOf({
@@ -11653,15 +11654,15 @@ await runProcess(defineCli({
 			repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
 			skillHubGit: url({ protocol: /^https$/ }).refine((url) => new URL(url).search === "" && new URL(url).hash === "", "must name the hub's repository with no query or fragment").refine((url) => new URL(url).pathname.endsWith(".git"), "must end in .git").optional().describe("the https git URL of a git Skill Hub each release commits the CLI's skill to"),
 			skillHubApi: url({ protocol: /^https$/ }).optional().describe("the https URL of an API Skill Hub each release publishes the CLI's skill to"),
-			skillPage: url({ protocol: /^https$/ }).optional().describe("the https page of the skill on the API Skill Hub, where each user copies their own install line"),
+			skillAdd: string().optional().describe("the whole line that installs the CLI's skill from the API Skill Hub"),
 			dependency: boolean().default(false).describe("install the CLI per project, as a devDependency, with its skill shipped inside the package")
 		}),
-		plan: async ({ name, description, install, git, repository, skillHubGit, skillHubApi, skillPage, dependency }, ctx) => {
+		plan: async ({ name, description, install, git, repository, skillHubGit, skillHubApi, skillAdd, dependency }, ctx) => {
 			const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
 			const mode = installModeOf({
 				git: skillHubGit,
 				api: skillHubApi,
-				page: skillPage
+				add: skillAdd
 			}, dependency, binName);
 			const path = resolve(ctx.cwd, binName);
 			await ensureFree(path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.",
   "type": "module",
   "engines": {
@@ -21,7 +21,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@duyquangnvx/agent-cli": "0.18.0",
+    "@duyquangnvx/agent-cli": "0.20.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/partials/global/skillCheck.md

@@ -1 +1 @@
-The `skill` row names every installed copy of this skill against the installed CLI. A missing copy, or one that states no version, is installed afresh as the row says, with its `npx -y skills add` fix or from the page its message names, since `npx skills update` skips a copy it did not install. After a fix that runs the `skills` installer, load this skill again.
+The `skill` row names every installed copy of this skill against the installed CLI. A missing copy, or one that states no version, is installed afresh with the row's fix, since `npx skills update` skips a copy it did not install. After a fix that runs the `skills` installer, load this skill again.

package/template/skills/{{binName}}/SKILL.md

@@ -47,18 +47,10 @@ Pass `--json` whenever you parse the output: stdout then holds only the data. A
 
 ## Recovering from errors
 
-Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Match the first row that fits:
+Errors go to stderr and end with a `hint:` line, then a `run:` line for each command to run next, in order. Under `--json`, every stderr line is one JSON object: `{"progress":"..."}` or `{"notice":"..."}` while it runs, then `{ errors: [{ code, message, hint, next }] }` as the last line, `next` holding those commands when there are any. Do what the hint says, except for a code below:
 
-| Code or exit | What to do |
+| Code | What to do |
 |---|---|
-| `OUTPUT_EXISTS` | The run would overwrite a file. Ask the user before adding `--force`. |
-| `NOT_CONFIRMED` | The run costs money. Tell the user the cost from the message; add `--yes` only once they approve it. |
-| `LANGUAGE_UNSUPPORTED` | The greetings service lacks that language. Run the Next step's English card, or ask the user for another language. |
-| exit 1 | You called it wrong. Fix what the message and hint point at, then run it again. |
-| exit 2 | Something on this machine needs a person. Tell the user what the hint says and ask them to fix it. |
-| exit 3 | The source it talks to is broken. Tell the user; running it again won't help. |
-| exit 75 | Nobody needs to act. Wait, then run it again, as the hint says. |
-| exit 70, `INTERNAL` | A bug in {{binName}}. Run it once more with `{{debugVariable}}=1` for the stack trace, then give the user stderr verbatim. |
-| exit 130 or 143 | It was interrupted. Run it again only if the user still wants it. |
-
-<!-- Add a row above the exit rows for each CliError code {{binName}} throws, saying what to do about it. -->
+| `LANGUAGE_UNSUPPORTED` | The user asked for that language. Ask whether an English card will do before running the Next step. |
+
+<!-- Add a row for each code {{binName}} throws whose right move goes beyond its hint. A guardrail on a flag goes in the workflow step that passes it instead. -->

package/template/test/cli.test.ts

@@ -207,15 +207,13 @@ describe("install lines", () => {
     expect(await text("README.md")).toContain(`\`! ${install}\``);
   });
 
-  // A hub that gives each user their own install line has no fix: the row's message names its page.
   test.skipIf(cli.skill === undefined)(
-    "the README installs the skill as doctor's skill row says",
+    "the README installs the skill with doctor's skill line",
     async () => {
-      const { fix, message } = (await doctorRows()).skill ?? { message: "" };
-      const line = fix === undefined ? message.split("; ").at(-1) : `\`! ${fix}\``;
+      const fix = (await doctorRows()).skill?.fix;
 
-      expect(line).toMatch(/^`! |^copy your install line from /);
-      expect(await text("README.md")).toContain(line);
+      expect(fix).toBeDefined();
+      expect(await text("README.md")).toContain(`\`! ${fix}\``);
     },
   );