@zenera/cli 1.1.43 → 1.1.45

package/dist/commands/completion.d.ts

@@ -2,7 +2,7 @@ import type { Command } from '../command.ts';
 export { install, installed, loader, rcFile } from '../completion-install.ts';
 /**
  * Prints the shell's side of tab completion. The script is a few lines that
- * call back into `zen __complete`, so the project names and stored prompts it
+ * call back into `zen __complete`, so the project names and commands it
  * offers are always read from the machine it runs on, never baked in.
  */
 export declare const completion: Command;

package/dist/commands/completion.js

@@ -8,7 +8,7 @@ export { install, installed, loader, rcFile } from "../completion-install.js";
 const USAGE = 'zen completion [<zsh|bash|fish>] [--install [--yes]]';
 /**
  * Prints the shell's side of tab completion. The script is a few lines that
- * call back into `zen __complete`, so the project names and stored prompts it
+ * call back into `zen __complete`, so the project names and commands it
  * offers are always read from the machine it runs on, never baked in.
  */
 export const completion = {
@@ -29,12 +29,12 @@ export const completion = {
         '  zen completion zsh --install --yes       without asking',
         '',
         'Then, in a new shell:',
-        '  zen meta run my-project /<Tab>           the project’s stored prompts',
+        '  zen meta run my-project /<Tab>           the project’s commands',
         '  zen meta <Tab>                           run, prompts, resume, model …',
         '  zen run <Tab>                            your projects',
         '',
-        'The prompts are the files in .github/prompts/ — the same ones an editor',
-        'offers as slash commands. Where there is nothing to offer, file names are.',
+        'The commands are the skills in .github/skills/ an editor offers as slash',
+        'commands - not the zen-* ones, which are the model’s. Where there is nothing to offer, file names are.',
     ],
     run: async (ctx) => {
         const { values, positionals } = parse(ctx.args, { install: { type: 'boolean' }, yes: { type: 'boolean' } }, USAGE);

package/dist/commands/meta.js

@@ -10,7 +10,7 @@ import { parse } from "../args.js";
 import { matching, projectNames } from "../candidates.js";
 import { copilotEventLog } from "../eventlog.js";
 import { probeChat, probeModel } from "../liveness.js";
-import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, editorFiles, fallbackRef, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, metaCompatible, misspelledProvider, MODEL_ENV, openLog, ORDER, PROMPT_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, wireGateway, writeMeta, } from "../meta/index.js";
+import { answerBox, chooseModel, DATASET_DETAILS, DATASET_SUMMARY, DATASET_USAGE, datasetProjectFlag, DEFAULT_RESUMES, editorFiles, fallbackRef, FINETUNE_DETAILS, FINETUNE_SUMMARY, FINETUNE_USAGE, finetuneProjectFlag, lastSession, launch, listPrompts, loadPrompt, locate, masked, metaCompatible, misspelledProvider, MODEL_ENV, openLog, ORDER, SKILL_DIR, providersWarning, readMeta, recordSession, RESUME_PROMPT, resumeDelayMs, runDataset, runFinetune, sameModel, sessionModel, sessionTotals, SOURCE_LABELS, startVertexRelay, tailSpans, Tally, terminalSink, transient, wire, wireGateway, writeMeta, } from "../meta/index.js";
 import { splitRef } from "../modelref.js";
 import { duration } from "../narrate.js";
 import { project as resolveProject } from "../resolve.js";
@@ -84,16 +84,16 @@ const OPTIONS = {
 };
 const RUN_FORMS = [
     '  zen meta run [project] "<question>"      ask it something',
-    '  zen meta run [project] /<name> [words]   run a stored prompt',
-    '  zen meta run [project]                   pick one of its stored prompts',
+    '  zen meta run [project] /<name> [words]   run one of its commands',
+    '  zen meta run [project]                   pick one of its commands',
 ];
 const RUN_ARGUMENTS = [
     'Arguments:',
     '  [project]   Name of a project. Default: the one you are in.',
     '  [prompt]    Your question, in quotes. Or --prompt, or piped in when neither',
     '              it nor --prompt-file is given.',
-    '  /<name>     A prompt file in .github/prompts/<name>.prompt.md.',
-    '  [words]     Appended to that prompt as a final line.',
+    '  /<name>     A command: the skill in .github/skills/<name>/SKILL.md.',
+    '  [words]     Given to that command, after its text.',
 ];
 const RUN_OPTIONS = [
     'Options:',
@@ -126,7 +126,7 @@ export const meta = {
     details: [
         'Forms:',
         ...RUN_FORMS,
-        '  zen meta prompts [project]               list the stored prompts',
+        '  zen meta prompts [project]               list its commands',
         '  zen meta resume [project] [session]      carry on a run that stopped',
         '  zen meta model [ref]                     show or set the model it uses',
         '  zen meta dataset <verb>                  the cases it tunes against',
@@ -134,7 +134,7 @@ export const meta = {
         '',
         'The project may come before the verb instead: `zen meta acme run`.',
         '`zen meta dataset --help`, `zen meta finetune --help` and `zen meta run --help`',
-        'have their own pages; the last lists the stored prompts.',
+        'have their own pages; the last lists the commands.',
         '',
         ...RUN_ARGUMENTS,
         '',
@@ -281,7 +281,7 @@ async function runHelp(ctx, words) {
     lines.push('', ...RUN_ARGUMENTS, '', ...RUN_OPTIONS, '', 'Examples:', '  zen meta run "what does this project do?"', '  zen meta run acme /project-review', '  zen meta run acme /spec-sync-project agents/triage.md', '  zen meta run acme /analyze --json');
     page({
         usage: 'zen meta run [project] [/<name> [words] | "<question>"] [options]',
-        summary: 'Ask the meta agent a question, or run one of the stored prompts.',
+        summary: 'Ask the meta agent a question, or run one of the commands.',
         details: lines,
     });
 }
@@ -359,7 +359,7 @@ async function stored(ctx, values, args) {
     if (question) {
         return await go(ctx, values, project, question);
     }
-    // Nothing said and nothing piped: the stored prompts are what is left to offer.
+    // Nothing said and nothing piped: the commands are what is left to offer.
     return await runPrompt(ctx, values, project, await pickPrompt(ctx, project), []);
 }
 async function runPrompt(ctx, values, project, name, extra) {
@@ -508,7 +508,7 @@ async function prompts(ctx, values, args) {
         return json(found.map(({ name, description, path }) => ({ name, description, path })));
     }
     if (found.length === 0) {
-        note(dim(`no prompts in ${project.name}/${PROMPT_DIR}`));
+        note(dim(`no commands in ${project.name}/${SKILL_DIR}`));
         return;
     }
     writeAll(table(found.map((p) => [`/${p.name}`, p.description ? dim(p.description) : ''])));

package/dist/completion.js

@@ -14,7 +14,7 @@ import { completeMeta } from "./commands/meta.js";
 // One candidate per line, `value<TAB>description`. Nothing at all means "no
 // opinion", and the shell falls back to completing file names — which is the
 // right answer for `-C <dir>`, for `--events <file>`, and for the files that
-// follow a stored prompt.
+// follow a stored command.
 // ---------------------------------------------------------------------------
 /** Flags the frame owns, offered where a command name would be. */
 const GLOBAL_FLAGS = [

package/dist/meta/editor.js

@@ -1,3 +1,4 @@
+import { existsSync, readdirSync, rmdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { copyTree, TEMPLATES } from "./host.js";
 // ---------------------------------------------------------------------------
@@ -27,8 +28,8 @@ import { copyTree, TEMPLATES } from "./host.js";
 // assistant still needs a brief of its own, and what it needs to know is how
 // this kind of project is put together — the file formats, how a prompt is
 // written, when to add a skill rather than an agent. That is what the
-// `.github/` tree is: the standing brief, plus the prompt files and skills the
-// editor picks up from the same place.
+// `.github/` tree is: the standing brief, plus the skills the editor picks up
+// from the same place - `zen-*` for the model to load, the rest as `/commands`.
 // ---------------------------------------------------------------------------
 /**
  * Writes the editor's files under `dir`, replacing what is there. They are
@@ -38,6 +39,45 @@ import { copyTree, TEMPLATES } from "./host.js";
  * none. Returns the relative paths that actually changed.
  */
 export function editorFiles(dir) {
-    return copyTree(join(TEMPLATES, 'editor'), dir, '', {});
+    return [...copyTree(join(TEMPLATES, 'editor'), dir, '', {}), ...retirePrompts(dir)];
+}
+// Every `.github/prompts/*.prompt.md` `zen` has ever shipped. Copilot dropped
+// prompt files for skills, and these are now `.github/skills/<name>/` - so the
+// old copy would only offer a second, stale `/name`. A prompt file the project
+// wrote itself is not on this list, and stays.
+const RETIRED_PROMPTS = [
+    'analyze',
+    'dataset',
+    'finetune',
+    'finetune-apply',
+    'finetune-consolidate',
+    'inspect',
+    'new-agent',
+    'new-skill',
+    'project-review',
+    'review-project',
+    'spec-apply-feedback',
+    'spec-edit',
+    'spec-sync-project',
+    'sync-with-spec',
+    'update-spec-from-feedback',
+];
+function retirePrompts(dir) {
+    const folder = join(dir, '.github', 'prompts');
+    if (!existsSync(folder)) {
+        return [];
+    }
+    const removed = [];
+    for (const name of RETIRED_PROMPTS) {
+        const file = join(folder, `${name}.prompt.md`);
+        if (existsSync(file)) {
+            rmSync(file);
+            removed.push(join('.github', 'prompts', `${name}.prompt.md`));
+        }
+    }
+    if (readdirSync(folder).length === 0) {
+        rmdirSync(folder);
+    }
+    return removed;
 }
 //# sourceMappingURL=editor.js.map

package/dist/meta/finetune/command.js

@@ -89,7 +89,7 @@ export const FINETUNE_DETAILS = [
     'has its own private memory; passing memories are merged into finetune/memories/.',
     '',
     'A parked case gives its worker back; woken cases take a worker before new ones.',
-    '/finetune-apply fixes the parked cases together: when -M wait, or once nothing',
+    '/zen-finetune-apply fixes the parked cases together: when -M wait, or once nothing',
     'else can run. No run starts during an apply. What it may do:',
     '  - Every call reads the house rules, the prompt, preloaded skills and one line per',
     '    skill, so that is what --budget counts. A skill body is paid only once loaded:',
@@ -461,7 +461,7 @@ async function gate(ctx, project, rest, options) {
     const dir = resolve(ctx.cwd, at);
     const g = readJson(join(dir, 'gate.json'));
     if (!g || existsSync(join(dir, 'applied.json'))) {
-        throw invalidError(`${at} is not an apply in progress`, 'pass the apply directory named on the line after /finetune-apply');
+        throw invalidError(`${at} is not an apply in progress`, 'pass the apply directory named after /zen-finetune-apply');
     }
     const after = await measure(project.dir);
     const over = overLimits(g.before, after, g.limits);

package/dist/meta/finetune/improvements.js

@@ -401,7 +401,7 @@ export class Improvements {
                 join(dir, 'apply.events.jsonl'),
                 '--prompt-file',
                 brief,
-                '/finetune-apply',
+                '/zen-finetune-apply',
                 dir,
             ], applyLog);
             writeFileSync(join(dir, attempt === 1 ? 'apply.json' : `apply-${attempt}.json`), res.stdout);

package/dist/meta/prompts.d.ts

@@ -1,3 +1,4 @@
+export declare const SKILL_DIR = ".github/skills";
 export declare const PROMPT_DIR = ".github/prompts";
 /** `/project-review`, `project-review`, `project-review.prompt.md` or a path. */
 export declare function promptPath(dir: string, name: string): string;
@@ -5,14 +6,18 @@ export interface StoredPrompt {
     name: string;
     path: string;
     description?: string;
+    /** False for a skill marked `user-invocable: false` - the model's, not a command. */
+    invocable: boolean;
     body: string;
 }
 /**
- * Frontmatter is the editor's business — `mode`, `tools`, `description` — and
- * none of it means anything to copilot, so only the body is sent. `description`
- * is kept for the one line of narration that says which prompt is running.
+ * Frontmatter is the editor's business — `name`, `argument-hint`, the
+ * invocation switches — and none of it means anything once the body is the
+ * prompt, so only the body is sent. `description` is kept for the one line of
+ * narration that says which command is running.
  */
 export declare function readPrompt(path: string, name: string, text: string): StoredPrompt;
 export declare function loadPrompt(dir: string, name: string): Promise<StoredPrompt>;
+/** The commands a person may type: every skill not marked for the model only, and any legacy prompt file. */
 export declare function listPrompts(dir: string): Promise<string[]>;
 //# sourceMappingURL=prompts.d.ts.map

package/dist/meta/prompts.js

@@ -1,14 +1,21 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { usageError } from "./host.js";
 // ---------------------------------------------------------------------------
-// Stored prompts
+// Stored commands
 //
-// Copilot reads `AGENTS.md`, `.github/skills/` and `.github/agents/`, but it
-// has no notion of `.github/prompts/*.prompt.md` — the files an editor offers
-// as slash commands. Reading one and handing over its body is the whole of
-// `zen meta run`, and it is why that subcommand exists.
+// The editor offers `.github/skills/<name>/SKILL.md` as `/name`. The `zen-*`
+// skills are reference the model loads on its own (`user-invocable: false`);
+// the rest are commands somebody types (`disable-model-invocation: true`), and
+// those are what `zen meta run /<name>` runs. Copilot would expand `/name`
+// itself, but reading the file and handing over its body works the same with
+// every model and leaves room for `--prompt-file` after it.
+//
+// `.github/prompts/*.prompt.md` is the format these used to be in. Copilot has
+// dropped it, but a project may still have prompt files of its own, so one
+// whose name no skill takes is still run.
 // ---------------------------------------------------------------------------
+export const SKILL_DIR = '.github/skills';
 export const PROMPT_DIR = '.github/prompts';
 const PROMPT_SUFFIX = '.prompt.md';
 /** `/project-review`, `project-review`, `project-review.prompt.md` or a path. */
@@ -17,42 +24,58 @@ export function promptPath(dir, name) {
     if (bare.includes('/') || bare.endsWith('.md')) {
         return `${dir}/${bare}`;
     }
-    return `${dir}/${PROMPT_DIR}/${bare}${PROMPT_SUFFIX}`;
+    const skill = `${dir}/${SKILL_DIR}/${bare}/SKILL.md`;
+    const legacy = `${dir}/${PROMPT_DIR}/${bare}${PROMPT_SUFFIX}`;
+    return !existsSync(skill) && existsSync(legacy) ? legacy : skill;
 }
 /**
- * Frontmatter is the editor's business — `mode`, `tools`, `description` — and
- * none of it means anything to copilot, so only the body is sent. `description`
- * is kept for the one line of narration that says which prompt is running.
+ * Frontmatter is the editor's business — `name`, `argument-hint`, the
+ * invocation switches — and none of it means anything once the body is the
+ * prompt, so only the body is sent. `description` is kept for the one line of
+ * narration that says which command is running.
  */
 export function readPrompt(path, name, text) {
     let body = text;
     let description;
+    let invocable = true;
     const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(text);
     if (match) {
         body = text.slice(match[0].length);
         const found = /^description:\s*(.+)$/m.exec(match[1]);
         description = found?.[1].trim().replace(/^['"]|['"]$/g, '');
+        invocable = !/^user-invocable:\s*['"]?false['"]?\s*$/m.test(match[1]);
     }
-    return { name, path, description, body: body.trim() };
+    return { name, path, description, invocable, body: body.trim() };
 }
 export async function loadPrompt(dir, name) {
     const path = promptPath(dir, name);
     if (!existsSync(path)) {
         const known = await listPrompts(dir);
-        throw usageError(`no prompt named ${name.replace(/^\//, '')}`, known.length > 0
+        throw usageError(`no command named ${name.replace(/^\//, '')}`, known.length > 0
             ? `try: ${known.map((p) => `/${p}`).join(', ')}`
-            : `put one in ${PROMPT_DIR}/`);
+            : `put one in ${SKILL_DIR}/<name>/SKILL.md`);
     }
     return readPrompt(path, name.replace(/^\//, ''), await readFile(path, 'utf8'));
 }
+/** The commands a person may type: every skill not marked for the model only, and any legacy prompt file. */
 export async function listPrompts(dir) {
-    const { readdir } = await import('node:fs/promises');
+    const names = new Set();
+    for (const entry of entries(`${dir}/${SKILL_DIR}`)) {
+        const path = `${dir}/${SKILL_DIR}/${entry}/SKILL.md`;
+        if (existsSync(path) && readPrompt(path, entry, readFileSync(path, 'utf8')).invocable) {
+            names.add(entry);
+        }
+    }
+    for (const entry of entries(`${dir}/${PROMPT_DIR}`)) {
+        if (entry.endsWith(PROMPT_SUFFIX)) {
+            names.add(entry.slice(0, -PROMPT_SUFFIX.length));
+        }
+    }
+    return [...names].sort();
+}
+function entries(path) {
     try {
-        const names = await readdir(`${dir}/${PROMPT_DIR}`);
-        return names
-            .filter((n) => n.endsWith(PROMPT_SUFFIX))
-            .map((n) => n.slice(0, -PROMPT_SUFFIX.length))
-            .sort();
+        return readdirSync(path);
     }
     catch {
         return [];

package/dist/usage.d.ts

@@ -3,7 +3,7 @@ import type { ModelUsage, TokenUsage } from '@zenera/neo';
 export declare const LEDGER_ENV = "ZENERA_USAGE_LEDGER";
 /** The meta session whose agent started this process, if one did. */
 export declare const META_SESSION_ENV = "ZENERA_META_SESSION";
-/** The stored prompt that meta session was started with, if any. */
+/** The stored command that meta session was started with, if any. */
 export declare const META_PROMPT_ENV = "ZENERA_META_PROMPT";
 /**
  * Where this project's usage goes: the variable when set, else the fine-tuning's

package/dist/usage.js

@@ -13,7 +13,7 @@ import { warn } from "./term.js";
 export const LEDGER_ENV = 'ZENERA_USAGE_LEDGER';
 /** The meta session whose agent started this process, if one did. */
 export const META_SESSION_ENV = 'ZENERA_META_SESSION';
-/** The stored prompt that meta session was started with, if any. */
+/** The stored command that meta session was started with, if any. */
 export const META_PROMPT_ENV = 'ZENERA_META_PROMPT';
 /**
  * Where this project's usage goes: the variable when set, else the fine-tuning's

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/cli",
-    "version": "1.1.43",
+    "version": "1.1.45",
     "description": "Command-line front end for @zenera/neo: agentic projects you can run, share and commit.",
     "keywords": [
         "agents",
@@ -54,9 +54,9 @@
         "@google/genai": "^2.30.0",
         "@inkjs/ui": "^2.0.0",
         "@openrouter/sdk": "^1.4.25",
-        "@zenera/engine": "^1.1.43",
-        "@zenera/neo": "^1.1.43",
-        "@zenera/view": "^1.1.43",
+        "@zenera/engine": "^1.1.45",
+        "@zenera/neo": "^1.1.45",
+        "@zenera/view": "^1.1.45",
         "google-auth-library": "^10.0.0",
         "ink": "^7.1.1",
         "openai": "^6.0.0",

package/templates/editor/.github/copilot-instructions.md

@@ -1,7 +1,7 @@
 # Copilot instructions - agent projects
 
 > Written by `zen init` into `.github/copilot-instructions.md`, alongside the
-> prompt files and skills in the same tree (§2.4). VS Code loads it
+> skills and commands in the same tree (§2.4). VS Code loads it
 > automatically for every request in this folder, so it is the standing brief
 > for anyone - human or agent - editing this project.
 >
@@ -35,12 +35,15 @@ programmed: what an agent knows, which model answers, and which of the tools
 6. Every change must still load: `agents.yaml` is validated strictly at load,
    and `zen check` says so before a model is ever called.
 
-### 0.1 Copilot is the meta-agent: load the skill for every capability in use
+### 0.1 Copilot is the meta-agent: load skills for the capabilities in scope
 
 Copilot is always the meta-agent that creates and changes target projects. Load
 the editor's `zen-cli` skill before deciding how a target project should run,
 be validated, or use command-line capabilities. It is the command contract; do
 not reconstruct `zen` arguments from memory or call `--help` to discover them.
+When the task is to bring a project into compliance with `SPECIFICATION.md`,
+load `zen-spec-sync` first; its narrow tiers contain the exact validation
+commands and do not require loading `zen-cli` as well.
 
 **Every runtime capability a project turns on carries obligations that are not
 visible in `agents.yaml` and that `zen check` does not report.** Before
@@ -54,20 +57,23 @@ code, `zen-topology` for `handoffs:` or `fork:` on any agent,
 `zen-cli` always. A capability that is already
 configured and already passing `zen check` is exactly the case that looks
 finished and is not: the obligation lives in the skill, so a review that never
-opens the skill cannot find what is missing. This applies whatever prompted the
-change - a task scoped to `SPECIFICATION.md` does not narrow it. There is one
-exception: a `/spec-sync-project` pass that the `zen-spec-sync` skill classes as
-**spec-only**. It touches no agent, prompt, skill or wiring, so there is no
-obligation for it to meet.
+opens the skill cannot find what is missing. Outside a specification-sync pass,
+this applies whatever prompted the change. During an incremental sync, load only
+skills for capabilities its changed requirements, files, keys or unresolved
+work touch. A full pass still loads every enabled capability's skill. The
+**spec-only** and **model-reference-only** tiers load no capability skill unless
+the work expands beyond their eligibility rules.
 
 **Load `zen-instructions` before writing, editing, reviewing or deleting any
 `agents/*instructions.md`.** They are the house rules, prepended to every
-agent's prompt, and three of them are `zen`'s own copies rather than the
+agent's prompt, and four of them are `zen`'s own copies rather than the
 project's: an edit made inside one is lost at the next `zen check --fix`, `zen
 init` or `zen open`, with no diff to show for it. The skill is what says which
-three those are, where a project's own rules on the same subjects go instead,
+four those are, where a project's own rules on the same subjects go instead,
 how `requires:` conditions a document, and what filename order decides. None of
 that is visible in the file being edited.
+Replacing generated copies with `zen check --fix` is maintenance, not manual
+house-rule editing, and does not by itself require loading `zen-instructions`.
 
 **Load `zen-code-python` before writing, editing or reviewing any prompt, skill
 or house rule for an agent that writes or runs code** - any agent holding
@@ -251,8 +257,7 @@ Two consequences that drive nearly every design rule in this document:
 my-project/
 ├── .github/                      the editor's brief - §2.4
 │   ├── copilot-instructions.md   this file
-│   ├── prompts/*.prompt.md       tasks you invoke by name
-│   └── skills/*/SKILL.md         reference the editor loads on demand
+│   └── skills/*/SKILL.md         zen-* reference loaded on demand; the rest /commands
 ├── .env                          this project's environment - NEVER committed
 ├── .spec-sync/                   what the last /spec-sync-project applied - §0.1
 ├── agents.yaml                   who exists, what they may reach for
@@ -349,15 +354,18 @@ agents do, for the same reason - it is a prefix somebody pays for:
 
 - **`copilot-instructions.md`** is always on. Everything in it is loaded for
   every request in this folder, so it holds only what is true of every task.
-- **`.github/skills/<name>/SKILL.md`** is reference the editor loads when its
-  `description` matches what you asked. Put long, occasional material here -
-  a command surface, a vendor's quirks, a format spec - not in the file above.
-  The `description` is the routing key; §3.4 applies to these as much as to the
-  project's own skills.
-- **`.github/prompts/<name>.prompt.md`** is a task you invoke by name (`/name`),
-  with `mode: agent` and a `description` in its frontmatter. Write one when a
-  job is done repeatedly and has a right order - adding an agent, adding a
-  skill, reviewing before a commit.
+- **`.github/skills/zen-<name>/SKILL.md`** is reference the editor loads when
+  its `description` matches what you asked. Put long, occasional material here
+    - a command surface, a vendor's quirks, a format spec - not in the file above.
+      The `description` is the routing key; §3.4 applies to these as much as to the
+      project's own skills. `user-invocable: false` keeps them out of the `/` menu.
+- **`.github/skills/<name>/SKILL.md`** without the `zen-` prefix is a command
+  you invoke by name (`/name`, or `zen meta run /name`), with
+  `disable-model-invocation: true` so the model never starts one on a hunch,
+  and an `argument-hint` when it takes words. Write one when a job is done
+  repeatedly and has a right order - adding an agent, adding a skill, reviewing
+  before a commit. It holds the order of the work and loads the `zen-*` skills
+  that hold the rules.
 
 `zen init` and `zen open` rewrite this whole tree from the version of `zen` in
 hand, so **edits inside `.github/` do not survive**. Project-specific conventions
@@ -1885,6 +1893,11 @@ the spec-sync record, in that order:
 
 Run it first and read what it says. Everything else below is judgement, which is
 why it is still a list. The `zen-review` skill has the detail.
+Within a specification-sync pass, reuse its final check with
+`review.sh --skip-check` instead of probing again, and apply the sync skill's
+explicit tier scope to this checklist. Use `--skip-check no-sandbox` only for an
+eligible model-reference-only pass. Independent reviews still cover the whole
+checklist.
 
 Before finishing any change here:
 
@@ -2086,8 +2099,8 @@ install` is an `image:` that was never set - §3.7.
 
 This file is loaded on every request in this repository, so it is subject to its
 own rules: stable, factual, no hedging. Before adding a section, ask whether it
-is true of every task - if it is not, it is a skill under `.github/skills/`, or
-a prompt file under `.github/prompts/` if it is a procedure (§2.4).
+is true of every task - if it is not, it is a `zen-*` skill under
+`.github/skills/`, or a command skill there if it is a procedure (§2.4).
 
 Update it when:
 

package/templates/editor/.github/{prompts/analyze.prompt.md → skills/analyze/SKILL.md}

@@ -1,5 +1,8 @@
 ---
+name: analyze
 description: Analyze one recorded run of this project - its health, what it wasted, and what to change in the instructions. Name the run (directory or id) after the command, or get the most recent one.
+argument-hint: '[run directory or run id]'
+disable-model-invocation: true
 ---
 
 Load the **zen-analyze-run** skill and follow it to analyze one run of this
@@ -10,10 +13,10 @@ audit cannot be graded without it.
 
 ## Which run
 
-The line after this prompt may name the run - a run directory or a run id.
-If it does, use it. Words after it like `case=<id> ... feedback=<file>` mean
+The words given with the command may name the run - a run directory or a run
+id. If they do, use it. Words after it like `case=<id> ... feedback=<file>` mean
 the tuning loop sent you: follow section 7 of the skill and write that file.
-A `## The brief` section below that line is what the loop already ran for
+A `## The brief` section below them is what the loop already ran for
 you: section 1 of the skill says how to use it.
 
 If it does not, list this project's most recent runs, newest first:

package/templates/editor/.github/{prompts/dataset.prompt.md → skills/dataset/SKILL.md}

@@ -1,17 +1,20 @@
 ---
+name: dataset
 description: Build or refresh this project's dataset - every case read from its sources with a class, complexity, tags, a verbatim rubric and an anchor - re-reading only the sections that changed since the last revision. Name a source after the command to add it, `rebuild` to read everything again, or a case and what to fix.
+argument-hint: '[source file | rebuild | <case id> <what to fix>]'
+disable-model-invocation: true
 ---
 
 Keep `dataset/` in step with its sources. **Load the `zen-dataset` skill before
 anything else**, and `zen-cli` for the command reference. The skill holds the
-extraction rules and every verb; this prompt is the order of the work. If
+extraction rules and every verb; this command is the order of the work. If
 loading a skill fails, read `.github/skills/<name>/SKILL.md` with your file tool
 before going on.
 
 You never run cases, never edit `agents/`, and never edit a source. Only
 `zen meta dataset` writes `dataset/` - never a file tool, never a script.
 
-This prompt is **reentrant**: the state on disk says what to do, so running it
+This command is **reentrant**: the state on disk says what to do, so running it
 twice in a row does nothing the second time.
 
 ## 1. Where things stand
@@ -27,7 +30,7 @@ sections are `changed`, `gone` or `uncovered`.
 
 ## 2. What to do
 
-The last line of this prompt may hold words. Then read the table top down and
+Words may be given with the command. Then read the table top down and
 take the first row that fits:
 
 | State                                    | Do                                                                    |

package/templates/editor/.github/{prompts/finetune.prompt.md → skills/finetune/SKILL.md}

@@ -1,5 +1,8 @@
 ---
+name: finetune
 description: Fine-tune this project against a training set, a batch at a time - every batch first with no memory, fixing the instructions, then with the memory it just built, making the same work cheaper - starting from a 3-case smoke test and doubling each smooth batch, until every case is used and no difficult case is open.
+argument-hint: '[training set] [limit]'
+disable-model-invocation: true
 ---
 
 Tune this project against real queries. Nothing here touches model weights: what
@@ -9,7 +12,7 @@ queries produce.
 
 **Load the `zen-finetune` skill before anything else**, and load `zen-inspect`,
 `zen-analyze-run`, `zen-topology` and `zen-inspect-ask` before you grade, and
-`zen-instructions` before you write a policy file. This prompt is the order of the work; the skill
+`zen-instructions` before you write a policy file. This command is the order of the work; the skill
 is how each step is done, and it holds the rules that are easy to get wrong. If
 loading a skill fails, read `.github/skills/<name>/SKILL.md` with your file tool
 before going on - never carry on without it.
@@ -28,7 +31,7 @@ command:
 | one memory node in full                      | `zen memory show <node-id> --dir "$RUN/batch/<id>/memory"`        |
 | a whole memory, or what one added to another | `zen memory ls --dir <dir>`, `zen memory diff <base> --dir <dir>` |
 
-This prompt is **reentrant**. Tuning is long and gets interrupted - a run dies, a
+This command is **reentrant**. Tuning is long and gets interrupted - a run dies, a
 session ends, I stop you mid-batch. Every step leaves its result on disk under
 `finetune/`, so a second invocation does not start over: it reads that state,
 works out where the work stopped, says so, and carries on from there unless I
@@ -199,7 +202,7 @@ in your reports instead of re-typing it.
 
 ## Where you are - work this out before anything else
 
-Do this every time this prompt runs, including the first:
+Do this every time this command runs, including the first:
 
 ```sh
 .github/skills/zen-finetune/scripts/next.mjs
@@ -208,7 +211,7 @@ Do this every time this prompt runs, including the first:
 ```
 
 `next.mjs` reads the whole `finetune/` tree and prints the next step. Do not
-re-derive the state from an `ls`. Map what it says onto this prompt:
+re-derive the state from an `ls`. Map what it says onto this command:
 
 | What `next.mjs` says                                             | Go to                                                                             |
 | ---------------------------------------------------------------- | --------------------------------------------------------------------------------- |

package/templates/editor/.github/{prompts/new-agent.prompt.md → skills/new-agent/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-mode: agent
+name: new-agent
 description: Add an agent to agents.yaml, with its prompt, tools and handoffs.
+argument-hint: "[the agent's job in one sentence]"
+disable-model-invocation: true
 ---
 
 Add an agent to this project. Ask for the one sentence that states its job

package/templates/editor/.github/{prompts/new-skill.prompt.md → skills/new-skill/SKILL.md}

@@ -1,6 +1,8 @@
 ---
-mode: agent
+name: new-skill
 description: Add a skill under agents/skills, with a description that routes.
+argument-hint: '[what the skill says and when it applies]'
+disable-model-invocation: true
 ---
 
 Add a skill to this project. A skill is curated instruction content - and