@groeponline/pi-wishcraft 0.24.0 → 0.25.0

package/CHANGELOG.md

@@ -2,10 +2,13 @@
 
 ## [Unreleased]
 
+## [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 and inserting installed skills, `/skills doctor` health table.
 - [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,6 @@
 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.
 
 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.25.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

@@ -28,6 +28,7 @@ import {
   type SkillCategory,
   type SkillEntry,
 } from "./skill-registry.ts";
+import { runSkillDoctor } from "./skill-doctor.ts";
 
 const CATEGORY_LABELS: Record<SkillCategory | "all", string> = {
   all: "alles",
@@ -470,17 +471,28 @@ 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` for a health table",
+    handler: async (args: string, ctx: any) => {
       if (!rt.enabled || !ctx.hasUI) {
         ctx.ui.notify("Powerline UI is disabled", "info");
         return;
       }
+      const sub = args?.trim().split(/\s+/)[0]?.toLowerCase();
+      if (sub === "doctor") {
+        await runDoctor(ctx);
+        return;
+      }
       await showSkillManager(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;
 }