@duyquangnvx/create-agent-cli 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@duyquangnvx/create-agent-cli",
-  "version": "0.23.0",
+  "version": "0.24.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.23.0",
+    "@duyquangnvx/agent-cli": "0.24.0",
     "tsdown": "0.23.0",
     "zod": "4.6.7"
   },

package/partials/dependency/installSteps.md

@@ -9,4 +9,4 @@ This installs the project's copy of {{binName}}. Always run it as `{{runAs}}`: a
      and with npm `! npm install -D {{packageName}}`.
 
    With yarn or bun, hand the user that package manager's own line.
-2. Finish with [Check](#check): its `skill` row brings this skill to the installed version. {{binName}} is ready when `doctor` exits 0 with nothing in `next`.
+2. Finish with [Check](#check). {{binName}} is ready when `doctor` exits 0 with nothing in `next`.

package/partials/dependency/skillCheck.md

@@ -1 +1 @@
-The `skill` row compares this skill's copy at the project root, `.claude/skills/{{binName}}`, with the one the project's {{binName}} ships. When the copy is missing or differs, as after an update, run its `{{runAs}} skill install` fix, then load this skill again. A copy under `~/.claude/skills/{{binName}}` shadows the project's: ask the user to remove it.
+The `skill` row looks for the skill's copy at the project root, `.claude/skills/{{binName}}`. When the copy is missing or states `metadata.version`, as an older skill does, run its `{{runAs}} skill install` fix, then load the skill again. A copy under `~/.claude/skills/{{binName}}` shadows the project's: ask the user to remove it.

package/partials/dependency/updateSteps.md

@@ -1,4 +1,4 @@
 1. Run `{{runAs}} doctor --json` and read its `registry` row. When it reports no newer release, {{binName}} is current: stop here. When a newer release exists, the row's fix is the line that moves {{packageName}} to it; with yarn or bun the row names the version without a line, so use that package manager's own line for it. If the row fails to reach the registry, the sandbox refused the host, as [Sandbox](#sandbox) says.
 2. Hand the user that line to type with `!`.
-3. Read the `CHANGELOG.md` that `{{runAs}} --version` names, from the top down to the version the project left, and do each upgrade step it lists, oldest first.
-4. Finish with [Check](#check): its `skill` row brings this skill to the new version.
+3. Read the `CHANGELOG.md` that `{{runAs}} --version` names, from the top down to the version the project left, and do each upgrade step it lists, oldest first. A release that changes the skill lists `{{runAs}} skill install` there.
+4. Finish with [Check](#check).

package/partials/dependency/whenMissing.md

@@ -0,0 +1 @@
+If the line above says {{binName}} is not installed, or names no `docs` folder, ask the user to type a line in the project's folder: `! pnpm install` when a `package.json` from here up lists {{packageName}}, else `! pnpm add -D {{packageName}}`. With npm these are `! npm install` and `! npm install -D {{packageName}}`, and with yarn or bun that package manager's own. Always run the CLI as `{{runAs}}`: a bare `npx {{binName}}` runs whatever npm package holds the name.

package/partials/global/installLines.md

@@ -1,5 +1,5 @@
-Install the skill first, so that the coding agent loading it can install and check the CLI. In Claude Code, type each line in the prompt:
+Paste this to your coding agent, with your task in it:
 
-{{skillLine}}
+> Run `{{setupLine}}`, then use {{binName}} to <your task>.
 
-`! npm install --global {{packageName}}@latest`
+That line installs the CLI and its skill. In a terminal it works the same.

package/partials/global/installSteps.md

@@ -1,10 +1,6 @@
-This installs the CLI. The user has installed this skill already.
+This installs the CLI and this skill on this machine, and is safe to run again.
 
-1. Run `node --version` and compare it with the range `npm view {{packageName}} engines.node` prints, which `doctor`'s `node` row also checks once the CLI is installed. Under nvm every Node version has its own global packages, so {{binName}} lands under the Node this shell runs. If that Node is too old, or is not the one the user's terminal runs, tell the user and let them choose before going on. That is also why a {{binName}} the user installed can be missing from this shell: ask which Node their terminal runs before installing again.
-2. Hand the user the install line to type, as [Sandbox](#sandbox) says:
-
-   `! npm install --global {{packageName}}@latest`
-
-   Never run `npx {{binName}}`: that runs whatever npm package holds the name.
-3. If `{{binName}} --version` then shows an older version than this skill describes, npm answered from a stale cache. Hand the user the same line with `--cache "$(mktemp -d)"` appended.
-4. Finish with [Check](#check). {{binName}} is ready when `doctor` exits 0 with nothing in `next`: a row that only advises, such as `install`, leaves the exit code at 0.
+1. Run `{{setupLine}}`. Never run a bare `npx {{binName}}`: that runs whatever npm package holds the name.
+2. If it fails with a Next step, the sandbox may have refused it, as [Sandbox](#sandbox) says: hand the user that line to type with `!`.
+3. If it fails with `NOT_ON_PATH`, the CLI went under the Node this shell runs, which the shell cannot run bins from: ask which Node the user's terminal runs, and let them choose before going on. Under nvm each Node has its own global packages.
+4. Read the folder its `docs` line names, then go on with the task.

package/partials/global/sandbox.md

@@ -1,3 +1,3 @@
-Claude Code's sandbox never lets a command write npm's global folder, `~/.claude/skills` or `~/.agents/skills`, so the install line, `{{binName}} update` and `npx skills` fail inside it. Hand the user the line to type with `!` in this session, which runs it outside the sandbox under the Node this shell runs.
+Claude Code's sandbox never lets a command write npm's global folder, `~/.claude/skills` or `~/.agents/skills`, so `{{setupLine}}` and `{{binName}} update` fail inside it. Hand the user the line to type with `!` in this session, which runs it outside the sandbox under the Node this shell runs.
 
 `doctor`'s `registry` row, `update` and `npm view` ask the registry {{binName}} is published to for its latest release. If the sandbox refuses that host, `doctor` still passes with only that row failing, and `update --dry-run` fails. If the user wants these to work inside the sandbox, give them this block for their Claude Code settings, naming the registry's host, and let them decide:

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 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.
+The `skill` row looks for the skill's copies, `~/.claude/skills/{{binName}}` and `~/.agents/skills/{{binName}}`. A missing copy, or one stating `metadata.version`, as an older skill does, gets `{{binName}} setup`: run it, then load the skill again.

package/partials/global/updateSteps.md

@@ -1,4 +1,3 @@
 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, 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`.
+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. It also brings the skill to that release, so load the skill again.
+3. Confirm the new version with `{{binName}} --version`.

package/partials/global/whenMissing.md

@@ -0,0 +1 @@
+If the line above says {{binName}} is not installed, or names no `docs` folder, run `{{setupLine}}`, which installs the CLI and this skill and names that folder; a bare `npx {{binName}}` runs whatever npm package holds the name. When a sandbox refuses it, ask the user to type that line with `!`. Under nvm each Node has its own global packages, so when the user says it is installed, ask which Node their terminal runs.

package/template/AGENTS.md

@@ -24,6 +24,8 @@ Follow the rules in `~/.claude/rules/harness/`. Biome enforces the mechanical on
 
 ## Agent skills
 
-`skills/{{binName}}/SKILL.md` is the agent skill: when to use `{{binName}}`, its workflows and how to recover from its errors. Update it with any change to those, and leave flag details to `--help`. Its `references/setup.md` installs, checks and updates `{{binName}}`; `test/cli.test.ts` fails when its install line, or the README's, differs from what `doctor` gives.
+`skills/{{binName}}/SKILL.md` is the CLI skill: when to use `{{binName}}`, its install line and a pointer to `docs/cli/`, so it stays true across releases. `{{runAs}} update` brings a Global install's copy along; a Dependency install's release that changes it lists `{{runAs}} skill install` under `### Upgrade from` in `CHANGELOG.md`. `test/cli.test.ts` fails when its install line, the README's or `docs/cli/setup.md`'s differs from what `doctor` gives.
+
+`docs/cli/` is the CLI docs, which ship in the package and `--version` names: `README.md` holds the workflows and how to recover from errors, `setup.md` checks and updates `{{binName}}`. Update them with any change to those, and leave flag details to `--help`.
 
 {{agentsSection}}

package/template/docs/cli/README.md

@@ -0,0 +1,34 @@
+<!-- A skeleton to rewrite around {{binName}}'s real Commands. A line earns its place only when no `--help`, output, hint or `doctor` row tells the agent the same thing: write down what costs it turns to work out, such as a convention, a reason, a trap, or a step that needs the user's consent. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. -->
+
+# {{binName}}
+
+`{{runAs}} --help` lists the Commands, and `{{runAs}} <command> --help` shows a Command's examples, args, options and the flags the Runtime adds. This folder ships with the CLI, so it describes the build that runs. It covers the work around the Commands.
+
+To check, update or fix the install, read [setup](setup.md).
+
+## Workflows
+
+<!-- Each main task as steps naming the Commands it runs, in order. Move a long workflow to its own page in this folder and link it. -->
+
+### Greet someone
+
+1. Run `{{runAs}} greet <name> --json`.
+2. Read `greeting` from the JSON on stdout.
+
+### Write a card
+
+1. Run `{{runAs}} card <name> --language <code> --dry-run` to see the file it writes and what it costs.
+2. If it states a cost, ask the user before going on.
+3. Run it again without `--dry-run`, adding `--yes` once the user approved the cost.
+
+To put a message under the greeting, pass `-` after the name and pipe the message in with a heredoc, so its quotes and newlines reach the card intact.
+
+## Recovering from errors
+
+Do what the error's hint says, except for a code below:
+
+| Code | What to do |
+|---|---|
+| `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/{skills/{{binName}}/references → docs/cli}/setup.md

@@ -1,6 +1,6 @@
 # Setup
 
-Checking, installing and updating {{binName}}, and letting it work inside Claude Code's sandbox. Using it is in [SKILL.md](../SKILL.md).
+Checking, installing and updating {{binName}}, and letting it work inside Claude Code's sandbox. Using it is in [README.md](README.md).
 
 Work through a section in order and stop at a step that fails. Ask the user to do what only they can do, such as typing an install line, and wait until they say it is done.
 

package/template/package.json

@@ -12,6 +12,8 @@
   },
   "files": [
     "dist",
+    "docs/cli",
+    "skills",
     "CHANGELOG.md"
   ],
   "publishConfig": {
@@ -29,7 +31,7 @@
     "@biomejs/biome": "2.5.15",
     "@duyquangnvx/agent-cli": "{{runtimeVersion}}",
     "@duyquangnvx/harness": "0.3.1",
-    "@duyquangnvx/release": "0.5.0",
+    "@duyquangnvx/release": "0.9.0",
     "@types/node": "^22.19.0",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",

package/template/scripts/release.ts

@@ -1,6 +1,5 @@
 import { release } from "@duyquangnvx/release";
 
 process.exitCode = await release({
-  skill: "skills/{{binName}}/SKILL.md",
   smoke: { cli: true },
 });

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

@@ -2,46 +2,15 @@
 name: {{binName}}
 description: >-
   {{description}} Use when a task needs what `{{binName}}` does, or when a `{{binName}}` command fails.
-allowed-tools: Bash({{runAs}} --version)
-metadata:
-  version: "0.0.0"
+allowed-tools: Bash({{runAs}} --version) Read(//**/node_modules/{{packageName}}/docs/cli/**)
 ---
 
-<!-- A skeleton to rewrite around {{binName}}'s real Commands. A line earns its place only when no `--help`, output, hint or `doctor` row tells the agent the same thing: write down what costs it turns to work out, such as a convention, a reason, a trap, or a step that needs the user's consent. Leave flags out: `--help` is generated from the code and stays in sync with it, this file does not. What {{binName}} is for, and the nearby tasks it is not for, go in the description, which the agent always sees. -->
+<!-- This file holds only what stays true across releases, so a release need not change it: say here when to use {{binName}}, in the description, and put how to use it in docs/cli/. -->
 
 # {{binName}}
 
-`{{runAs}} --help` lists the Commands, and `{{runAs}} <command> --help` shows a Command's examples, args, options and the flags the Runtime adds. This file covers the work around them.
-
-## Installed CLI
-
 !`{{runAs}} --version 2>&1 || echo "{{binName}}: not installed"`
 
-The line above should show 0.0.0, the version this skill describes. If it says {{binName}} is not installed or shows another version, read [setup](references/setup.md) before anything else.
-
-## Workflows
-
-<!-- Each main task as steps naming the Commands it runs, in order. Move a long workflow to a file under references/ and link it. -->
-
-### Greet someone
-
-1. Run `{{runAs}} greet <name> --json`.
-2. Read `greeting` from the JSON on stdout.
-
-### Write a card
-
-1. Run `{{runAs}} card <name> --language <code> --dry-run` to see the file it writes and what it costs.
-2. If it states a cost, ask the user before going on.
-3. Run it again without `--dry-run`, adding `--yes` once the user approved the cost.
-
-To put a message under the greeting, pass `-` after the name and pipe the message in with a heredoc, so its quotes and newlines reach the card intact.
-
-## Recovering from errors
-
-Do what the error's hint says, except for a code below:
-
-| Code | What to do |
-|---|---|
-| `LANGUAGE_UNSUPPORTED` | The user asked for that language. Ask whether an English card will do before running the Next step. |
+Before any other `{{binName}}` command, read the folder the `docs` line above names, starting with its `README.md` when it has one: it holds the steps to follow and what to do on each error.
 
-<!-- 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. -->
+{{whenMissing}}

package/template/src/bin.ts

@@ -1,5 +1,23 @@
 #!/usr/bin/env node
-import { runProcess } from "@duyquangnvx/agent-cli";
-import { cli } from "./cli.js";
+import { readFileSync } from "node:fs";
 
+// Every other import waits for this check, so a Node too old to load them fails with what it needs.
+const manifest: { name?: string; engines?: { node?: string } } = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8"),
+);
+const range = manifest.engines?.node ?? ">=0";
+const needed = range.replace(">=", "").split(".").map(Number);
+const running = process.versions.node.split(".").map(Number);
+const differs = needed.findIndex((part, index) => part !== running[index]);
+if (differs !== -1 && (running[differs] ?? 0) < (needed[differs] ?? 0)) {
+  process.stderr.write(
+    `${manifest.name} needs Node ${range}, and this is ${process.versions.node}: install it, then run this again\n`,
+  );
+  process.exit(2);
+}
+
+const [{ runProcess }, { cli }] = await Promise.all([
+  import("@duyquangnvx/agent-cli"),
+  import("./cli.js"),
+]);
 await runProcess(cli);

package/template/src/cli.ts

@@ -101,5 +101,7 @@ const card = defineCommand({
 export const cli = defineCli({
   manifest,
   install: "global",
+  docs: "docs/cli",
+  skill: { folder: "skills/{{binName}}" },
   commands: { greet, card },
 });

package/template/test/cli.test.ts

@@ -199,15 +199,17 @@ describe("install lines", () => {
     return readFile(join(root, path), "utf8");
   }
 
-  test("the setup reference and the README install the CLI with doctor's install line", async () => {
+  test("the skill, the setup page and the README install the CLI with doctor's install line", async () => {
     const install = (await doctorRows()).install?.fix;
 
     expect(install).toBeDefined();
-    expect(await text("skills/{{binName}}/references/setup.md")).toContain(`\`! ${install}\``);
-    expect(await text("README.md")).toContain(`\`! ${install}\``);
+    expect(await text("skills/{{binName}}/SKILL.md")).toContain(install);
+    expect(await text("docs/cli/setup.md")).toContain(install);
+    expect(await text("README.md")).toContain(install);
   });
 
-  test.skipIf(cli.skill === undefined)(
+  // A Global install's line that also installs the skill is doctor's install line, checked above.
+  test.skipIf(DOCTOR_BIN === "")(
     "the README installs the skill with doctor's skill line",
     async () => {
       const fix = (await doctorRows()).skill?.fix;
@@ -217,11 +219,16 @@ describe("install lines", () => {
     },
   );
 
-  test("the setup reference names the registry's host for the sandbox to allow", async () => {
+  test("the skill's read grant and the package's files name the CLI docs folder", async () => {
+    const skill = await text("skills/{{binName}}/SKILL.md");
+
+    expect(skill).toContain(`Read(//**/node_modules/${manifest.name}/${cli.docs}/**)`);
+    expect(manifest.files).toContain(cli.docs);
+  });
+
+  test("the setup page names the registry's host for the sandbox to allow", async () => {
     const { host } = new URL(manifest.publishConfig.registry);
 
-    expect(await text("skills/{{binName}}/references/setup.md")).toContain(
-      `"allowedDomains": ["${host}"]`,
-    );
+    expect(await text("docs/cli/setup.md")).toContain(`"allowedDomains": ["${host}"]`);
   });
 });