@groeponline/pi-wishcraft 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -2,10 +2,18 @@
 
 ## [Unreleased]
 
+## [0.26.0] - 2026-08-20
+
+### Added
+- `/skills new <name> [template]` writes a SKILL.md from standard, browser-workflow, CLI-workflow, or review-checklist. `ctrl+n` opens the template picker.
+
+## [0.25.0] - 2026-08-20
+
 ## [0.24.0] - 2026-08-20
 
 ### Added
 - Declarative policy engine (`wishcraft.policy`): in-process deny/inject rules in global settings, evaluated before command hooks. No process spawn. `policyEnabled: false` is the kill-switch.
+- `/skills doctor` health table: broken frontmatter, descriptions over 240 chars, global/project duplicates, unused skills.
 
 ## [0.23.4] - 2026-08-20
 

package/docs/index.md

@@ -8,7 +8,7 @@ The README is the public landing page (`banner.png` only). Everything below live
 - [Configuration](./configuration.md) — custom items, hooks, repairs, token budget, labels, templates, layout, cost alert, and display formats.
 - [Bash mode](./bash-mode.md) — sticky shell, ghost suggestions, and shell config.
 - [Stash & shortcuts](./stash-and-shortcuts.md) — editor stash, prompt history, clipboard/navigation shortcuts, and shortcut config.
-- [Skill manager](./skill-manager.md) — browsing and inserting installed skills.
+- [Skill manager](./skill-manager.md) — browsing, inserting, `/skills doctor`, and `/skills new` templates.
 - [Working vibes](./working-vibes.md) — themed loading messages, modes, and configuration.
 - [Segments & theming](./segments.md) — segment reference, separators, thinking/path/git options, and theme overrides.
 

package/docs/skill-manager.md

@@ -3,5 +3,7 @@
 Browse and insert your installed skills (`SKILL.md` files and `*.md`/`*.txt` prompts) from an interactive TUI overlay:
 
 - **`/skills`** — open the skill manager. Filter with plain typing, `↑↓` to move, `enter` to open a skill's detail body, `↑↓` in the detail to scroll, `enter`/`tab` to insert the skill content into your prompt, `esc` to go back/close.
+- **`/skills doctor`** — health table (not an essay): broken or missing frontmatter, descriptions over 240 characters, the same name in global and project, unused skills (usage ledger count 0). `↑↓` navigate, `enter` copies a row, `esc` closes.
+- **`/skills new <name> [template]`** — write `~/.pi/agent/skills/<name>/SKILL.md` from a template (`standard`, `browser-workflow`, `CLI-workflow`, `review-checklist`), then drop an `$EDITOR` command in the prompt. `/skills new` or `ctrl+n` in the manager opens the template picker. Names reject empty values, `..`, and path separators. No GitHub/npm install.
 
 The manager reuses the same skill discovery as inline `/command`/`$skill` triggers, so anything you can inline you can also browse and insert manually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groeponline/pi-wishcraft",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Wishcraft cockpit for the pi coding agent — powerline status, vibes, idea inbox, bash mode, and full customization.",
   "type": "module",
   "files": [

package/src/extension/skills/skill-doctor.ts

@@ -0,0 +1,263 @@
+/**
+ * Skill health table for `/skills doctor`.
+ * Rows only — no essay. Overlay chrome matches `/powerline doctor`.
+ */
+
+import { readFileSync } from "node:fs";
+import { basename } from "node:path";
+import { copyToClipboard } from "@earendil-works/pi-coding-agent";
+import type { SelectItem } from "@earendil-works/pi-tui";
+
+import { showSelectOverlay } from "../ui/overlay-chrome.ts";
+import {
+  getSkillUsage,
+  invalidateSkillCache,
+  loadSkillCatalog,
+  type SkillEntry,
+  type SkillUsage,
+} from "./skill-registry.ts";
+
+/** Prompt-budget cap for skill descriptions (stricter than core's 1024). */
+export const SKILL_DESCRIPTION_MAX_CHARS = 240;
+
+export type SkillDoctorStatus = "ok" | "warn" | "fail";
+
+export type SkillDoctorIssue =
+  | "unclosed-frontmatter"
+  | "missing-frontmatter"
+  | "missing-description"
+  | "description-budget"
+  | "duplicate-global-project"
+  | "unused"
+  | "warning"
+  | "none";
+
+export interface SkillDoctorRow {
+  status: SkillDoctorStatus;
+  skill: string;
+  issue: SkillDoctorIssue;
+  detail: string;
+}
+
+const ISSUE_LABEL: Record<SkillDoctorIssue, string> = {
+  "unclosed-frontmatter": "unclosed frontmatter",
+  "missing-frontmatter": "missing frontmatter",
+  "missing-description": "missing description",
+  "description-budget": "description over budget",
+  "duplicate-global-project": "duplicate global/project",
+  unused: "unused",
+  warning: "warning",
+  none: "no issues",
+};
+
+export function hasUnclosedFrontmatter(content: string): boolean {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return false;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") return false;
+  }
+  return true;
+}
+
+export function hasClosedFrontmatter(content: string): boolean {
+  const lines = content.split("\n");
+  if (lines[0]?.trim() !== "---") return false;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i]?.trim() === "---") return true;
+  }
+  return false;
+}
+
+function isLoosePromptOrExtraFile(entry: SkillEntry): boolean {
+  return (
+    (entry.category === "prompts" || entry.category === "extra") &&
+    basename(entry.filePath) !== "SKILL.md" &&
+    !entry.isDirectorySkill
+  );
+}
+
+function pushRow(
+  rows: SkillDoctorRow[],
+  skill: string,
+  status: SkillDoctorStatus,
+  issue: SkillDoctorIssue,
+  detail: string,
+): void {
+  rows.push({ status, skill, issue, detail });
+}
+
+/**
+ * Pure table builder. `contents` is optional file text keyed by `filePath`
+ * so unclosed-frontmatter can be detected without the filesystem.
+ */
+export function diagnoseSkills(
+  entries: readonly SkillEntry[],
+  usage: ReadonlyMap<string, SkillUsage>,
+  contents: ReadonlyMap<string, string> = new Map(),
+): SkillDoctorRow[] {
+  const rows: SkillDoctorRow[] = [];
+
+  const byName = new Map<string, SkillEntry[]>();
+  for (const entry of entries) {
+    const key = entry.name.toLowerCase();
+    const list = byName.get(key) ?? [];
+    list.push(entry);
+    byName.set(key, list);
+  }
+
+  const duplicateNames = new Set<string>();
+  for (const [name, group] of byName) {
+    const cats = new Set(group.map((e) => e.category));
+    if (cats.has("global") && cats.has("project")) duplicateNames.add(name);
+  }
+
+  for (const entry of entries) {
+    const content = contents.get(entry.filePath);
+    const description = entry.description.trim();
+    let hadFail = false;
+    if (content !== undefined && hasUnclosedFrontmatter(content)) {
+      hadFail = true;
+      pushRow(
+        rows,
+        entry.name,
+        "fail",
+        "unclosed-frontmatter",
+        `${entry.category} · ${entry.filePath}`,
+      );
+    } else if (
+      content !== undefined &&
+      !hasClosedFrontmatter(content) &&
+      !isLoosePromptOrExtraFile(entry)
+    ) {
+      hadFail = true;
+      pushRow(
+        rows,
+        entry.name,
+        "fail",
+        "missing-frontmatter",
+        `${entry.category} · ${entry.filePath}`,
+      );
+    }
+
+    if (!hadFail && !description) {
+      hadFail = true;
+      pushRow(
+        rows,
+        entry.name,
+        "fail",
+        "missing-description",
+        `${entry.category} · model will not see this skill`,
+      );
+    } else if (!hadFail && description.length > SKILL_DESCRIPTION_MAX_CHARS) {
+      pushRow(
+        rows,
+        entry.name,
+        "warn",
+        "description-budget",
+        `${description.length}/${SKILL_DESCRIPTION_MAX_CHARS} chars`,
+      );
+    }
+
+    if (duplicateNames.has(entry.name.toLowerCase())) {
+      pushRow(
+        rows,
+        entry.name,
+        "warn",
+        "duplicate-global-project",
+        "same name in global and project",
+      );
+    }
+
+    const count = usage.get(entry.name)?.count ?? 0;
+    if (count === 0) {
+      pushRow(rows, entry.name, "warn", "unused", "usage ledger count 0");
+    }
+
+    if (entry.warning && !hadFail) {
+      pushRow(rows, entry.name, "warn", "warning", entry.warning);
+    }
+  }
+
+  const rank: Record<SkillDoctorStatus, number> = { fail: 0, warn: 1, ok: 2 };
+  rows.sort((a, b) => {
+    const s = rank[a.status] - rank[b.status];
+    if (s !== 0) return s;
+    const n = a.skill.localeCompare(b.skill);
+    if (n !== 0) return n;
+    return a.issue.localeCompare(b.issue);
+  });
+
+  if (rows.length === 0) {
+    return [
+      {
+        status: "ok",
+        skill: "catalog",
+        issue: "none",
+        detail: "no issues",
+      },
+    ];
+  }
+  return rows;
+}
+
+export function formatSkillDoctorRow(row: SkillDoctorRow): string {
+  const tag =
+    row.status === "ok" ? "[ok]  " : row.status === "warn" ? "[warn]" : "[fail]";
+  if (row.issue === "none") {
+    return `${tag} catalog · no issues`;
+  }
+  return `${tag} ${row.skill} · ${ISSUE_LABEL[row.issue]}`;
+}
+
+export function skillDoctorRowsToSelectItems(
+  rows: readonly SkillDoctorRow[],
+): SelectItem[] {
+  return rows.map((row) => ({
+    label: formatSkillDoctorRow(row),
+    value: `${row.skill}: ${row.detail}`,
+    description: row.detail,
+  }));
+}
+
+/** Build doctor rows and file contents for a cwd (testable without overlay). */
+export function collectSkillDoctorInputs(cwd: string = process.cwd()): {
+  entries: SkillEntry[];
+  usage: Map<string, SkillUsage>;
+  contents: Map<string, string>;
+} {
+  invalidateSkillCache();
+  const entries = loadSkillCatalog(cwd);
+  const usage = getSkillUsage();
+  const contents = new Map<string, string>();
+  for (const entry of entries) {
+    try {
+      contents.set(entry.filePath, readFileSync(entry.filePath, "utf8"));
+    } catch {
+      // unreadables already surface as registry warnings
+    }
+  }
+  return { entries, usage, contents };
+}
+
+/** Overlay table. Enter copies the selected line. */
+export async function runSkillDoctor(ctx: any): Promise<void> {
+  const cwd = ctx.cwd ?? process.cwd();
+  const { entries, usage, contents } = collectSkillDoctorInputs(cwd);
+  const items = skillDoctorRowsToSelectItems(
+    diagnoseSkills(entries, usage, contents),
+  );
+  const picked = await showSelectOverlay(
+    ctx,
+    "Skills doctor",
+    "↑↓ navigate · enter copy · esc close",
+    items,
+    Math.min(Math.max(items.length, 1), 20),
+  );
+  if (!picked) return;
+  try {
+    await copyToClipboard(picked.value);
+    ctx.ui.notify("Skill doctor row copied to clipboard", "info");
+  } catch {
+    ctx.ui.notify("Could not copy skill doctor row to clipboard", "warning");
+  }
+}

package/src/extension/skills/skill-manager.ts

@@ -14,10 +14,8 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { rmSync } from "node:fs";
-import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { RuntimeState } from "../core/types.ts";
-import { getAgentPath } from "../../paths/agent-dirs.ts";
 import {
   applySkillFilter,
   getSkillUsage,
@@ -28,6 +26,8 @@ import {
   type SkillCategory,
   type SkillEntry,
 } from "./skill-registry.ts";
+import { runSkillDoctor } from "./skill-doctor.ts";
+import { runSkillsNew } from "./skill-templates.ts";
 
 const CATEGORY_LABELS: Record<SkillCategory | "all", string> = {
   all: "alles",
@@ -89,21 +89,20 @@ function editorCommand(path: string): string {
   return `!${ed} ${shellQuote(path)}`;
 }
 
-export async function showSkillManager(ctx: any): Promise<void> {
+export async function showSkillManager(ctx: any): Promise<"new" | null> {
   invalidateSkillCache();
   let entries = loadSkillCatalog(ctx.cwd ?? process.cwd());
   const usage = getSkillUsage();
   if (entries.length === 0) {
     ctx.ui.notify("No skills found", "info");
-    return;
   }
 
-  await ctx.ui.custom(
+  return ctx.ui.custom(
     (
       tui: any,
       theme: Theme,
       _keybindings: any,
-      done: (result: null) => void,
+      done: (result: "new" | null) => void,
     ) => {
       const border = (text: string) => theme.fg("dim", text);
       const wrapRow = (text: string, innerWidth: number): string =>
@@ -182,11 +181,12 @@ export async function showSkillManager(ctx: any): Promise<void> {
             lines.push(border(`├${"─".repeat(innerWidth)}┤`));
 
             if (f.length === 0) {
+              const emptyMsg =
+                entries.length === 0 && !query
+                  ? "No skills installed — ctrl+n to create one"
+                  : `Geen skills voor "${query}"`;
               lines.push(
-                wrapRow(
-                  theme.fg("warning", `Geen skills voor "${query}"`),
-                  innerWidth,
-                ),
+                wrapRow(theme.fg("warning", emptyMsg), innerWidth),
               );
             } else {
               // scroll-window rondom de selectie
@@ -395,13 +395,8 @@ export async function showSkillManager(ctx: any): Promise<void> {
                 return;
               }
             } else if (data === "\x0e") {
-              // ctrl+n = nieuwe skill
-              appendToEditor(
-                ctx,
-                `!mkdir -p ${shellQuote(join(getAgentPath("skills"), "<naam>"))} && ${editorCommand(join(getAgentPath("skills"), "<naam>", "SKILL.md")).slice(1)}`,
-                "Nieuwe skill: vervang <naam>, enter draait 'm",
-              );
-              close();
+              // ctrl+n = new skill from a template
+              done("new");
               return;
             } else if (data === "\x04") {
               // ctrl+d = verwijderen (met confirm)
@@ -470,18 +465,34 @@ export async function showSkillManager(ctx: any): Promise<void> {
 }
 
 /** Registreer de `/skills` command. */
+export type SkillManagerCommandDeps = {
+  runDoctor?: (ctx: any) => Promise<void>;
+};
+
 export function registerSkillManagerCommand(
   pi: ExtensionAPI,
   rt: RuntimeState,
+  deps: SkillManagerCommandDeps = {},
 ): void {
+  const runDoctor = deps.runDoctor ?? runSkillDoctor;
   pi.registerCommand("skills", {
-    description: "Browse installed skills and insert one into your prompt",
-    handler: async (_args: string, ctx: any) => {
+    description: "Browse installed skills, or `doctor` / `new [template]`",
+    handler: async (args: string, ctx: any) => {
       if (!rt.enabled || !ctx.hasUI) {
         ctx.ui.notify("Powerline UI is disabled", "info");
         return;
       }
-      await showSkillManager(ctx);
+      const sub = args?.trim().split(/\s+/)[0]?.toLowerCase();
+      if (sub === "doctor") {
+        await runDoctor(ctx);
+        return;
+      }
+      if (sub === "new") {
+        await runSkillsNew(ctx, args);
+        return;
+      }
+      const result = await showSkillManager(ctx);
+      if (result === "new") await runSkillsNew(ctx, "");
     },
   });
 }

package/src/extension/skills/skill-registry.ts

@@ -11,9 +11,9 @@
 
 import { loadSkills } from "@earendil-works/pi-coding-agent";
 import { existsSync, readdirSync, readFileSync, statSync, writeFileSync, mkdirSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import { getAgentDir, getAgentPath } from "../../paths/agent-dirs.ts";
-import { stripFrontmatter } from "../../core/frontmatter.ts";
+import { parseSkillFrontmatter, stripFrontmatter } from "../../core/frontmatter.ts";
 
 /** Categorie: waar de skill vandaan komt. */
 export type SkillCategory = "global" | "project" | "prompts" | "extra";
@@ -158,6 +158,92 @@ function parseFrontmatterKeys(content: string): string[] {
   return keys;
 }
 
+/** Walk canonical skill trees the same way pi core discovers nested SKILL.md. */
+function walkCanonicalSkillMdFiles(dir: string, visit: (filePath: string) => void): void {
+  if (!existsSync(dir)) return;
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  const skillMd = entries.find((entry) => entry.isFile() && entry.name === "SKILL.md");
+  if (skillMd) {
+    visit(join(dir, skillMd.name));
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") {
+      continue;
+    }
+    walkCanonicalSkillMdFiles(join(dir, entry.name), visit);
+  }
+}
+
+/** Core rejects these paths (skill: null) but still emits diagnostics — surface them for doctor/manager. */
+function buildRejectedSkillEntries(
+  diagnostics: { message: string; path?: string }[],
+  knownPaths: Set<string>,
+  cwd: string,
+  extras: { path: string; category: SkillCategory }[],
+): SkillEntry[] {
+  const byPath = new Map<string, string>();
+  for (const d of diagnostics) {
+    if (!d.path || knownPaths.has(d.path)) continue;
+    if (!byPath.has(d.path)) byPath.set(d.path, d.message);
+  }
+
+  const agent = getAgentDir();
+  for (const root of [join(agent, "skills"), join(cwd, ".pi", "skills"), join(cwd, "skills")]) {
+    walkCanonicalSkillMdFiles(root, (filePath) => {
+      if (!knownPaths.has(filePath) && !byPath.has(filePath)) {
+        byPath.set(filePath, "skill file not loaded by catalog");
+      }
+    });
+  }
+
+  const out: SkillEntry[] = [];
+  for (const [filePath, message] of byPath) {
+    let content = "";
+    let sizeBytes = 0;
+    let lineCount = 0;
+    let mtimeMs = 0;
+    try {
+      content = readFileSync(filePath, "utf8");
+      sizeBytes = Buffer.byteLength(content, "utf8");
+      lineCount = content.split("\n").length;
+      mtimeMs = statSync(filePath).mtimeMs;
+    } catch {
+      // include unreadable paths so doctor can still report them
+    }
+
+    const fm = parseSkillFrontmatter(content);
+    const base = basename(filePath);
+    const name =
+      fm.name ??
+      (base === "SKILL.md"
+        ? basename(dirname(filePath))
+        : base.replace(/\.(md|txt)$/, ""));
+
+    out.push({
+      name,
+      description: fm.description ?? "",
+      filePath,
+      baseDir: dirname(filePath),
+      isDirectorySkill: base === "SKILL.md",
+      category: categorize(filePath, cwd, extras),
+      disableModelInvocation: false,
+      sizeBytes,
+      lineCount,
+      mtimeMs,
+      frontmatterKeys: parseFrontmatterKeys(content),
+      warning: message,
+    });
+    knownPaths.add(filePath);
+  }
+  return out;
+}
+
 /** Bouw de volledige skill-catalogus (gecached, TTL 30s). */
 export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
   const now = Date.now();
@@ -215,10 +301,23 @@ export function loadSkillCatalog(cwd: string = process.cwd()): SkillEntry[] {
 
   // loose entries achteraan; bij naam-collisie wint core
   const looseNames = new Set(loose.map((e) => e.name));
+  const catalogPaths = new Set([
+    ...entries.map((e) => e.filePath),
+    ...loose.map((e) => e.filePath),
+  ]);
+  const rejected = buildRejectedSkillEntries(
+    result.diagnostics,
+    catalogPaths,
+    cwd,
+    extras,
+  );
   cachedAt = now;
-    cachedCwd = cwd;
-  cachedEntries = [...entries.filter((e) => !looseNames.has(e.name)), ...loose]
-    .sort((a, b) => a.name.localeCompare(b.name));
+  cachedCwd = cwd;
+  cachedEntries = [
+    ...entries.filter((e) => !looseNames.has(e.name)),
+    ...loose,
+    ...rejected,
+  ].sort((a, b) => a.name.localeCompare(b.name));
   cachedPathMap = new Map(cachedEntries.map((e) => [e.name, e.filePath] as const));
   return cachedEntries;
 }

package/src/extension/skills/skill-templates.ts

@@ -0,0 +1,267 @@
+/**
+ * `/skills new` templates. No marketplace, no GitHub/npm install.
+ * Writes `~/.pi/agent/skills/<name>/SKILL.md` then opens $EDITOR.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { SelectItem } from "@earendil-works/pi-tui";
+
+import { getAgentPath } from "../../paths/agent-dirs.ts";
+import { showSelectOverlay } from "../ui/overlay-chrome.ts";
+import { invalidateSkillCache } from "./skill-registry.ts";
+
+export const SKILL_TEMPLATE_IDS = [
+  "standard",
+  "browser-workflow",
+  "cli-workflow",
+  "review-checklist",
+] as const;
+
+export type SkillTemplateId = (typeof SKILL_TEMPLATE_IDS)[number];
+
+export class SkillNameError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SkillNameError";
+  }
+}
+
+const TEMPLATE_META: Record<
+  SkillTemplateId,
+  { label: string; description: string }
+> = {
+  standard: {
+    label: "standard",
+    description: "Name, description, and a short body",
+  },
+  "browser-workflow": {
+    label: "browser-workflow",
+    description: "UI verify with screenshots, no profile wipe",
+  },
+  "cli-workflow": {
+    label: "CLI-workflow",
+    description: "Command, flags, and expected output",
+  },
+  "review-checklist": {
+    label: "review-checklist",
+    description: "Diff review gates before merge",
+  },
+};
+
+export function isSkillTemplateId(value: string): value is SkillTemplateId {
+  return (SKILL_TEMPLATE_IDS as readonly string[]).includes(value);
+}
+
+export function sanitizeSkillName(raw: string): string {
+  const trimmed = raw.trim().toLowerCase().replace(/_/g, "-");
+  if (!trimmed) {
+    throw new SkillNameError("Skill name is required");
+  }
+  if (trimmed === "." || trimmed === ".." || trimmed.includes("..")) {
+    throw new SkillNameError("Skill name cannot contain path traversal");
+  }
+  if (trimmed.includes("/") || trimmed.includes("\\")) {
+    throw new SkillNameError("Skill name cannot contain path separators");
+  }
+  if (trimmed.length > 64) {
+    throw new SkillNameError("Skill name must be 64 characters or fewer");
+  }
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(trimmed)) {
+    throw new SkillNameError(
+      "Skill name must be lowercase letters, digits, and hyphens",
+    );
+  }
+  return trimmed;
+}
+
+export function parseSkillsNewArgs(args: string): {
+  name?: string;
+  template: SkillTemplateId;
+} {
+  const parts = args.trim().split(/\s+/).filter(Boolean);
+  if (parts[0]?.toLowerCase() === "new") parts.shift();
+  if (parts.length === 0) return { template: "standard" };
+  if (parts.length === 1) {
+    const singleRaw = parts[0]!.toLowerCase();
+    if (isSkillTemplateId(singleRaw)) return { template: singleRaw };
+    return { name: parts[0], template: "standard" };
+  }
+  const templateRaw = parts[1]!.toLowerCase();
+  if (!isSkillTemplateId(templateRaw)) {
+    throw new SkillNameError(
+      `Unknown template '${parts[1]}'. Use: ${SKILL_TEMPLATE_IDS.join(", ")}`,
+    );
+  }
+  return { name: parts[0], template: templateRaw };
+}
+
+export function renderSkillTemplate(
+  id: SkillTemplateId,
+  name: string,
+): string {
+  const title = name;
+  switch (id) {
+    case "standard":
+      return `---
+name: ${title}
+description: Short skill for ${title}. State when to use it in one sentence.
+---
+
+# ${title}
+
+Use this skill when the operator asks for ${title}.
+
+## Steps
+
+1. Restate the goal in one line.
+2. Do the work with the tools already in session.
+3. Report what changed and how to verify it.
+`;
+    case "browser-workflow":
+      return `---
+name: ${title}
+description: Browser UI verify for ${title}. Screenshot evidence, no profile wipe.
+---
+
+# ${title}
+
+Use for visual checks in a real browser. Do not author layout here.
+
+## Steps
+
+1. Open the target URL in the existing session.
+2. Snapshot the page, then act on stable refs.
+3. Take a screenshot of the result.
+4. Do not wipe profiles, cookies, or login state unless the operator asked.
+`;
+    case "cli-workflow":
+      return `---
+name: ${title}
+description: CLI workflow for ${title}. Command, flags, and expected output.
+---
+
+# ${title}
+
+Use when the work is a command-line tool or script.
+
+## Steps
+
+1. Name the binary and the exact invocation.
+2. List required flags and inputs.
+3. Run the command and capture exit code plus stdout/stderr.
+4. State the expected output and how to rerun it.
+`;
+    case "review-checklist":
+      return `---
+name: ${title}
+description: Review checklist for ${title}. Gates before merge, no rubber-stamp.
+---
+
+# ${title}
+
+Use before marking a change merge-ready.
+
+## Checklist
+
+- [ ] Scope matches the request; no drive-by edits
+- [ ] Tests cover the changed behavior
+- [ ] No secrets in the diff
+- [ ] Docs match the new surface
+- [ ] Independent review is present; do not self-approve
+`;
+  }
+}
+
+export function writeSkillFromTemplate(
+  name: string,
+  template: SkillTemplateId,
+  skillsRoot: string = getAgentPath("skills"),
+): { filePath: string } {
+  const safe = sanitizeSkillName(name);
+  const dir = join(skillsRoot, safe);
+  const filePath = join(dir, "SKILL.md");
+  if (existsSync(filePath)) {
+    throw new SkillNameError(`Skill already exists: ${safe}`);
+  }
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, renderSkillTemplate(template, safe), "utf8");
+  invalidateSkillCache();
+  return { filePath };
+}
+
+export function buildSkillTemplateItems(): SelectItem[] {
+  return SKILL_TEMPLATE_IDS.map((id) => ({
+    value: id,
+    label: TEMPLATE_META[id].label,
+    description: TEMPLATE_META[id].description,
+  }));
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+export function editorCommandFor(path: string): string {
+  const ed = process.env.EDITOR?.trim() || "nvim";
+  return `!${ed} ${shellQuote(path)}`;
+}
+
+function appendEditorText(ctx: any, text: string): void {
+  const current = ctx.ui.getEditorText?.() ?? "";
+  const separator = current && !current.endsWith("\n") ? "\n" : "";
+  ctx.ui.setEditorText(`${current}${separator}${text}\n`);
+}
+
+export async function pickSkillTemplate(
+  ctx: any,
+): Promise<SkillTemplateId | null> {
+  const selected = await showSelectOverlay(
+    ctx,
+    "New skill template",
+    "↑↓ navigate • enter choose • esc cancel",
+    buildSkillTemplateItems(),
+    SKILL_TEMPLATE_IDS.length,
+  );
+  return selected && isSkillTemplateId(selected.value)
+    ? selected.value
+    : null;
+}
+
+export async function runSkillsNew(ctx: any, args: string): Promise<void> {
+  let parsed: { name?: string; template: SkillTemplateId };
+  try {
+    parsed = parseSkillsNewArgs(args);
+  } catch (error) {
+    ctx.ui.notify(
+      error instanceof Error ? error.message : String(error),
+      "error",
+    );
+    return;
+  }
+
+  let template = parsed.template;
+  let name = parsed.name;
+  if (!name) {
+    const picked = await pickSkillTemplate(ctx);
+    if (!picked) return;
+    template = picked;
+    appendEditorText(ctx, `/skills new <name> ${template}`);
+    ctx.ui.notify(
+      `Replace <name> and run to create a ${template} skill.`,
+      "info",
+    );
+    return;
+  }
+
+  try {
+    const { filePath } = writeSkillFromTemplate(name, template);
+    appendEditorText(ctx, editorCommandFor(filePath));
+    ctx.ui.notify(`Created ${name} (${template}). Enter runs the editor.`, "info");
+  } catch (error) {
+    ctx.ui.notify(
+      error instanceof Error ? error.message : String(error),
+      "error",
+    );
+  }
+}