@duyquangnvx/create-agent-cli 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ What changed in each release of `@duyquangnvx/agent-cli` (the Runtime) and `@duy
 
 ## Unreleased
 
+## v0.9.0 (2026-10-20)
+
+### Added
+
+- The Scaffolder's `--skill-hub <git URL>` names the Skill Hub each release commits the new CLI's skill to: it becomes `skill.source` in `defineCli`, `skillHub` in `scripts/release.ts` and the README's skill line. See ADR 0009. It refuses a URL that does not end in `.git` or holds a query or fragment, and with it a name the release cannot put in a hub (`SKILL_NAME_INVALID`).
+
+### Changed
+
+- **Breaking:** `doctor`'s `skill` row and `update`'s `next` install the skill only from a declared `skill.source`, no longer from package.json `repository` at `#release`, a branch `@duyquangnvx/release` 0.4 stops moving. A CLI without `skill.source` still gets `skills update` for an older copy.
+- **Breaking:** the Scaffolder's `--repository` only sets package.json `repository`; the skill line comes from `--skill-hub`. The scaffolded template releases with `@duyquangnvx/release` 0.4.0.
+- **Breaking:** the agent-cli skill installs from the Skill Hub: `npx skills add https://github.com/duyquangnvx/skills.git --skill agent-cli -g`.
+
+## v0.8.0 (2026-10-20)
+
+### Changed
+
+- **Breaking:** `update` shows only the Upgrade steps of a skipped release whose CHANGELOG section lists them under `### Upgrade from v<version>`, under `upgrade steps for <version>:`. A release whose only step is `Nothing to do.` is left out, and one without the heading still shows its whole section under `changes in <version>:`.
+- **Breaking:** each entry of `upgrades` in `update --json` is `{ version, steps }` or `{ version, notes }`.
+- The scaffolded template's CHANGELOG asks each release from the second on to hold `### Upgrade from v<the release below>`, and its setup reference tells the agent to do the steps `update` prints. The agent-cli skill's shipping reference explains the convention.
+
 ## v0.7.0 (2026-10-20)
 
 ### Added

package/README.md

@@ -3,9 +3,9 @@
 Creates a new Agent CLI repository already wired to [`@duyquangnvx/agent-cli`](https://www.npmjs.com/package/@duyquangnvx/agent-cli):
 
 ```sh
-pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --repository https://github.com/<owner>/<name>
+pnpm create @duyquangnvx/agent-cli <name> --description "One line saying what it does" --skill-hub 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`, 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. `--repository` names where that skill is installed from. 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`, 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` names the Skill Hub each release commits that skill to and agents install it from. Pass `--dry-run` to see what it would write.
 
-See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/release/skills/agent-cli/SKILL.md) for how to build on it.
+See the [repository](https://github.com/duyquangnvx/cli-for-agent) for an overview and the [agent-cli skill](https://github.com/duyquangnvx/cli-for-agent/blob/main/skills/agent-cli/SKILL.md) for how to build on it.

package/dist/bin.js

@@ -7049,36 +7049,8 @@ async function globalInstallOf(bin, ctx) {
 	};
 }
 //#endregion
-//#region ../agent-cli/dist/manifest.js
-const link$1 = union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0);
-const manifestSchema = object({
-	repository: link$1,
-	bugs: link$1
-});
-const NO_MANIFEST = {};
-function manifestAt(packageRoot) {
-	let manifest;
-	try {
-		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-	} catch {
-		return NO_MANIFEST;
-	}
-	const parsed = manifestSchema.safeParse(manifest);
-	return parsed.success ? parsed.data : NO_MANIFEST;
-}
-//#endregion
 //#region ../agent-cli/dist/built-ins/skills.js
 const SKILL_DIRS = [[".claude", "skills"], [".agents", "skills"]];
-/** The branch a release moves to the released commit, which holds the skill of that version. */
-const RELEASE_BRANCH$1 = "release";
-const SHORTHAND = /^(?:(?:github:)?[\w.-]+\/[\w.-]+|gitlab:[\w.-]+(?:\/[\w.-]+)+)$/;
-const GIT_URL_PROTOCOLS = /* @__PURE__ */ new Set([
-	"https:",
-	"http:",
-	"ssh:",
-	"git:"
-]);
-const SCP_STYLE = /^[\w.-]+@[\w.-]+:[\w./-]+$/;
 const FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---/;
 const METADATA_VERSION = /^metadata:[ \t]*\r?\n(?:[ \t]+.*\r?\n)*?[ \t]+version:[ \t]*["']?([^"'\s]+)["']?[ \t]*$/m;
 /** The version a SKILL.md's frontmatter `metadata.version` states. */
@@ -7127,18 +7099,6 @@ async function skillCopies(cliName, version, { cwd, env }) {
 	}
 	return copies;
 }
-function sourceFromRepository(repository) {
-	if (SHORTHAND.test(repository)) return `${repository}#${RELEASE_BRANCH$1}`;
-	const url = repository.replace(/^git\+/, "");
-	if (!(URL.canParse(url) && GIT_URL_PROTOCOLS.has(new URL(url).protocol)) && !SCP_STYLE.test(url)) return void 0;
-	return `${url.endsWith(".git") ? url : `${url}.git`}#${RELEASE_BRANCH$1}`;
-}
-/** What the installer installs the CLI's skill from: the declared source, else the package's repository. */
-function skillSource({ skill }, packageRoot) {
-	if (skill !== void 0) return skill.source;
-	const { repository } = manifestAt(packageRoot);
-	return repository === void 0 ? void 0 : sourceFromRepository(repository);
-}
 function fixFor(cliName, copies, source) {
 	const has = (wanted) => copies.some(({ state }) => state === wanted);
 	const update = `npx -y skills update ${cliName}`;
@@ -7151,7 +7111,7 @@ async function skillReport(cli, version, ctx) {
 	const copies = await skillCopies(cli.name, version, ctx);
 	return {
 		copies,
-		fix: fixFor(cli.name, copies, skillSource(cli, ctx.packageRoot))
+		fix: fixFor(cli.name, copies, cli.skill?.source)
 	};
 }
 //#endregion
@@ -7554,8 +7514,20 @@ var RunControl = class {
 	}
 };
 //#endregion
-//#region ../agent-cli/dist/built-ins/upgrade-notes.js
+//#region ../agent-cli/dist/built-ins/upgrades.js
+/** A skipped release's Upgrade steps, or its whole section when it lists none. */
+const upgradeSchema = union([object({
+	version: string(),
+	steps: array(string())
+}), object({
+	version: string(),
+	notes: string()
+})]);
 const RELEASE_HEADING = /^## v?(\S+)/;
+const UPGRADE_HEADING = /^### Upgrade from v\S+$/;
+const HEADING = /^#{1,6} /;
+const ITEM = /^[-*] /;
+const NOTHING_TO_DO = /^nothing to do\.?$/i;
 function releasesIn(changelog) {
 	const releases = [];
 	let current;
@@ -7570,16 +7542,33 @@ function releasesIn(changelog) {
 			if (current !== void 0) releases.push(current);
 		} else current?.lines.push(line);
 	}
-	return releases.map(({ version, lines }) => ({
+	return releases;
+}
+function listedSteps(lines) {
+	const start = lines.findIndex((line) => UPGRADE_HEADING.test(line.trimEnd()));
+	if (start === -1) return [];
+	const end = lines.findIndex((line, i) => i > start && HEADING.test(line));
+	const body = lines.slice(start + 1, end === -1 ? void 0 : end).filter((line) => line.trim() !== "");
+	const starts = body.flatMap((line, i) => ITEM.test(line) ? [i] : []);
+	return starts.map((first, i) => body.slice(first, starts[i + 1]).map((line) => line.trim()).join(" ").replace(ITEM, ""));
+}
+function upgradeOf({ version, lines }) {
+	const listed = listedSteps(lines);
+	if (listed.length === 0) return [{
 		version,
 		notes: lines.join("\n").trim()
-	}));
+	}];
+	const todo = listed.filter((step) => !NOTHING_TO_DO.test(step));
+	return todo.length === 0 ? [] : [{
+		version,
+		steps: todo
+	}];
 }
 /**
-* What changed in each release after `from` up to `to`, oldest first, from the CHANGELOG.md in
-* `packageDir`; none when the package ships no CHANGELOG.
+* What each release after `from` up to `to` asks of the operator, oldest first, from the
+* CHANGELOG.md in `packageDir`; none when the package ships no CHANGELOG.
 */
-async function upgradeNotes(packageDir, from, to) {
+async function upgradesOf(packageDir, from, to) {
 	let changelog;
 	try {
 		changelog = await readFile(join(packageDir, "CHANGELOG.md"), "utf8");
@@ -7587,7 +7576,7 @@ async function upgradeNotes(packageDir, from, to) {
 		if (isMissingFile(error)) return [];
 		throw error;
 	}
-	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version));
+	return releasesIn(changelog).filter(({ version }) => compareVersions(version, from) > 0 && compareVersions(version, to) <= 0).sort((a, b) => compareVersions(a.version, b.version)).flatMap(upgradeOf);
 }
 //#endregion
 //#region ../agent-cli/dist/built-ins/update.js
@@ -7598,18 +7587,18 @@ const updateSchema = object({
 		version: string(),
 		prefix: string()
 	}).nullable(),
-	upgrades: array(object({
-		version: string(),
-		notes: string()
-	})),
+	upgrades: array(upgradeSchema),
 	next: array(string())
 });
 function nothingToInstall({ from, latest }) {
 	return standingOf(from, latest) === "current" ? `already on ${from}, the latest release: nothing to install` : `${from} is newer than the latest release ${latest}: nothing to install`;
 }
+function renderUpgrade(upgrade) {
+	return "steps" in upgrade ? [`\nupgrade steps for ${upgrade.version}:`, ...upgrade.steps.map((step) => `- ${step}`)].join("\n") : `\nchanges in ${upgrade.version}:\n${upgrade.notes}`;
+}
 function renderUpdate(cli, install, update) {
 	const { installed } = update;
-	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(({ version, notes }) => `\nchanges in ${version}:\n${notes}`)];
+	const head = installed === null ? [nothingToInstall(update)] : [`installed ${install.package}@${installed.version} with the npm under ${installed.prefix}, replacing ${update.from}`, ...update.upgrades.map(renderUpgrade)];
 	const next = update.next.map((command) => `next: ${command}, so the ${cli.name} skill describes ${update.latest}`);
 	return (next.length === 0 ? head : [
 		...head,
@@ -7672,7 +7661,7 @@ function updateCommand(cli, install, { bin, node }) {
 					version: latest,
 					prefix
 				},
-				upgrades: await upgradeNotes(plan.packageDir, from, latest),
+				upgrades: await upgradesOf(plan.packageDir, from, latest),
 				next: await skillNext(cli, latest, ctx)
 			};
 			if (ctx.signal.aborted) {
@@ -8756,6 +8745,18 @@ async function execute(command, input, ctx, { dryRun, confirm, yes, page, invoca
 	}
 	return outcomeOf(await command.apply(plan, ctx), (data, style) => command.render(data, style));
 }
+const manifestSchema = object({ bugs: union([string(), object({ url: string() })]).transform((value) => typeof value === "string" ? value : value.url).optional().catch(void 0) });
+const NO_MANIFEST = {};
+function manifestAt(packageRoot) {
+	let manifest;
+	try {
+		manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	} catch {
+		return NO_MANIFEST;
+	}
+	const parsed = manifestSchema.safeParse(manifest);
+	return parsed.success ? parsed.data : NO_MANIFEST;
+}
 //#endregion
 //#region ../agent-cli/dist/parse-input.js
 const NO_INPUT = object({});
@@ -9408,14 +9409,14 @@ async function runProcess(cli) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.7.0";
+var version$1 = "0.9.0";
 var description = "Creates a new Agent CLI repository wired to @duyquangnvx/agent-cli.";
 //#endregion
 //#region src/build.ts
 const build = {
-	"sha": "10574f5",
+	"sha": "ff9a1b4",
 	"dirty": false,
-	"builtAt": "2026-10-20T03:42:41.670Z"
+	"builtAt": "2026-10-20T09:52:22.284Z"
 };
 //#endregion
 //#region src/steps.ts
@@ -9549,8 +9550,17 @@ const version = version$1;
 //#region src/create.ts
 const { defineCommand } = agentCli();
 const PACKAGE_NAME = /^(?:@[a-z0-9][a-z0-9._-]*\/)?([a-z0-9][a-z0-9._-]*)$/;
-const RELEASE_BRANCH = "release";
-const NO_REPOSITORY = "<!-- Set `repository` in package.json, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
+const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const NO_SKILL_HUB = "<!-- Set `skill.source` in `defineCli` and `skillHub` in `scripts/release.ts` to the git URL of the Skill Hub each release commits the skill to, then put here the `! npx -y skills add` line that `node dist/bin.js doctor` gives as the `skill` row's fix. -->";
+const SKILL_HUB_ANCHORS = [{
+	file: "src/cli.ts",
+	before: "  commands: {",
+	line: (hub) => `  skill: { source: ${JSON.stringify(hub)} },\n`
+}, {
+	file: "scripts/release.ts",
+	before: "  smoke: {",
+	line: (hub) => `  skillHub: ${JSON.stringify(hub)},\n`
+}];
 function errorCode(error) {
 	return error instanceof Error && "code" in error ? error.code : void 0;
 }
@@ -9563,9 +9573,16 @@ async function isFree(path) {
 		throw error;
 	}
 }
-function skillInstallLine(repository, binName) {
-	if (repository === void 0) return NO_REPOSITORY;
-	return `\`! npx -y skills add ${`${repository.endsWith(".git") ? repository : `${repository}.git`}#${RELEASE_BRANCH}`} --skill ${binName} -g\``;
+function skillInstallLine(skillHub, binName) {
+	return skillHub === void 0 ? NO_SKILL_HUB : `\`! npx -y skills add ${skillHub} --skill ${binName} -g\``;
+}
+async function setSkillHub(root, skillHub) {
+	for (const { file, before, line } of SKILL_HUB_ANCHORS) {
+		const path = join(root, file);
+		const text = await readFile(path, "utf8");
+		if (!text.includes(before)) throw new Error(`the template's ${file} has no \`${before}\` line to put the Skill Hub before`);
+		await writeFile(path, text.replace(before, `${line(skillHub)}${before}`));
+	}
 }
 const MANIFEST = record(string(), unknown());
 async function setRepository(root, repository) {
@@ -9574,6 +9591,13 @@ async function setRepository(root, repository) {
 	const entries = Object.entries(manifest).flatMap((entry) => entry[0] === "description" ? [entry, ["repository", repository]] : [entry]);
 	await writeFile(path, `${JSON.stringify(Object.fromEntries(entries), null, 2)}\n`);
 }
+function ensureSkillName(binName) {
+	if (!SKILL_NAME.test(binName)) throw new UsageError({
+		code: "SKILL_NAME_INVALID",
+		message: `${binName} cannot name a skill in a Skill Hub, whose names are lowercase letters, digits and single hyphens`,
+		hint: "choose a name such as my-cli, or leave out --skill-hub"
+	});
+}
 async function ensureFree(path) {
 	if (!await isFree(path)) throw new UsageError({
 		code: "TARGET_NOT_EMPTY",
@@ -9594,10 +9618,12 @@ const create = defineCommand({
 		description: string().default("An Agent CLI.").describe("one line saying what the CLI does"),
 		install: boolean().default(true).describe("run pnpm install"),
 		git: boolean().default(true).describe("create a git repository with an initial commit"),
-		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository, where its skill is installed from")
+		repository: url({ protocol: /^https$/ }).optional().describe("the https URL of the CLI's git repository"),
+		skillHub: 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 the Skill Hub each release commits the CLI's skill to")
 	}),
-	plan: async ({ name, description, install, git, repository }, ctx) => {
+	plan: async ({ name, description, install, git, repository, skillHub }, ctx) => {
 		const binName = PACKAGE_NAME.exec(name)?.[1] ?? name;
+		if (skillHub !== void 0) ensureSkillName(binName);
 		const path = resolve(ctx.cwd, binName);
 		await ensureFree(path);
 		const values = {
@@ -9606,7 +9632,7 @@ const create = defineCommand({
 			description,
 			debugVariable: debugVariable(binName),
 			runtimeVersion: version,
-			skillInstall: skillInstallLine(repository, binName)
+			skillInstall: skillInstallLine(skillHub, binName)
 		};
 		return {
 			path,
@@ -9617,13 +9643,15 @@ const create = defineCommand({
 				git
 			}),
 			install,
-			repository
+			repository,
+			skillHub
 		};
 	},
 	apply: async (plan, ctx) => {
 		await mkdir(plan.path, { recursive: true });
 		await writeTemplate(plan.path, plan.files, plan.values);
 		if (plan.repository !== void 0) await setRepository(plan.path, plan.repository);
+		if (plan.skillHub !== void 0) await setSkillHub(plan.path, plan.skillHub);
 		await runSteps(plan.steps, plan.path, ctx);
 		return {
 			path: plan.path,

package/package.json

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

package/template/CHANGELOG.md

@@ -1,5 +1,5 @@
 # Changelog
 
-What changed in each release of `{{packageName}}`, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: a Command, a flag, a `--json` field, an exit code or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`.
+What changed in each release of `{{packageName}}`, newest first, in the format of [Keep a Changelog 2.0](https://keepachangelog.com/en/2.0.0/). Each change lands under `## Unreleased` as it merges, grouped under `### Added`, `### Changed`, `### Fixed` or `### Removed`. A breaking change starts with `**Breaking:**` and names what breaks: a Command, a flag, a `--json` field, an exit code or the skill. A release turns `## Unreleased` into `## vX.Y.Z (YYYY-MM-DD)`. From the second release on, a release holds `### Upgrade from v<the release below>` listing what someone upgrading must do, or `- Nothing to do.`.
 
 ## Unreleased

package/template/package.json

@@ -29,7 +29,7 @@
     "@biomejs/biome": "2.5.15",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
     "@duyquangnvx/harness": "0.3.1",
-    "@duyquangnvx/release": "0.2.0",
+    "@duyquangnvx/release": "0.4.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",

package/template/pnpm-workspace.yaml

@@ -1,4 +1,5 @@
-# A fresh project pins the Runtime release it was created with, which can be younger than
-# pnpm's minimum release age.
+# A fresh project pins the Runtime and release versions it was created with, which can be younger
+# than pnpm's minimum release age.
 minimumReleaseAgeExclude:
   - "@duyquangnvx/agent-cli"
+  - "@duyquangnvx/release"

package/template/skills/{{binName}}/references/setup.md

@@ -32,7 +32,7 @@ This installs the CLI. The user has installed this skill already.
 ## Update
 
 1. Run `{{binName}} update --dry-run` to see the version it would install. If it fails to reach the registry, the sandbox refused the host, as [Sandbox](#sandbox) says: go on to the next step.
-2. Ask the user to type `! {{binName}} update`; never run it yourself. It installs the latest release and prints what changed since the version it replaced: under `--json`, `upgrades` lists each release's notes, oldest first. Do each upgrade step those notes give, oldest first.
+2. Ask the user to type `! {{binName}} update`; never run it yourself. It installs the latest release and prints, for each release since the version it replaced, oldest first, the upgrade steps it asks of the user, or its whole notes when it lists none: under `--json`, each entry of `upgrades` holds `steps` or `notes`. Do each step, oldest first, and any the notes give.
 3. Hand the user each line in `next` to type with `!`: they bring this skill to the version `update` installed, or to the latest release when it installed nothing, as `doctor`'s `skill` row would. Load this skill again after, as [Check](#check) says.
 4. Confirm the new version with `{{binName}} --version`.
 

package/template/test/cli.test.ts

@@ -186,7 +186,7 @@ describe("install lines", () => {
     expect(await text("README.md")).toContain(`\`! ${install}\``);
   });
 
-  test.skipIf(!("repository" in manifest))(
+  test.skipIf(cli.skill === undefined)(
     "the README installs the skill with doctor's skill line",
     async () => {
       const { skill } = await doctorFixes();