@groeponline/pi-wishcraft 0.23.4 → 0.25.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [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
 
 ### Fixed

package/README.md

@@ -171,6 +171,35 @@ PY
 
 Repairs run on custom/extension tools only, before hooks: drop null optionals, parse JSON-string arrays before wrapping, turn `{}` into `[]` on array keys, wrap bare strings, alias `filePath` / `absolutePath` / `target_file` to `path`, unwrap degenerate markdown auto-links. Core tools (`bash`, `read`, `edit`, `write`, `grep`, `find`, `ls`) are never rewritten. `/repairs` prints the counters.
 
+## Policy
+
+Declarative deny/inject rules in the **global** agent settings file. No shell commands — pure in-process regex. Evaluated before command hooks. `wishcraft.policyEnabled: false` disables policy without deleting rules.
+
+```json
+{
+  "wishcraft": {
+    "policy": [
+      {
+        "action": "deny",
+        "tool": "bash",
+        "match": "sudo\\s+rm",
+        "reason": "destructive sudo rm"
+      },
+      {
+        "action": "inject",
+        "tool": "read",
+        "pathMatch": "\\.env",
+        "context": "Do not leak secrets from .env files into the conversation."
+      }
+    ]
+  }
+}
+```
+
+**deny** — regex on tool input (`bash` uses `command`; other tools use JSON-serialized input). First match wins; the tool call is blocked with `reason`.
+
+**inject** — regex on file path after a matching tool completes; context is appended to the tool result (same shape as postToolUse hook `additionalContext`).
+
 ## Limits
 
 - No mouse on the live footer. Pi core owns that surface.

package/docs/configuration.md

@@ -218,6 +218,8 @@ Set `powerline.costAlert` to a USD threshold to get a single warning notificatio
 
 Command hooks live under `wishcraft.hooks` in the **global** agent settings file. `wishcraft.hooksEnabled: false` is the kill-switch. See the README Hooks section for three copy-paste examples (bash-guard, write-audit, SessionStart git-status).
 
+Declarative policy rules (`wishcraft.policy`) live in the same global file. They run in-process before command hooks: **deny** blocks a tool call when input matches a regex; **inject** appends context after a matching read/write path. `wishcraft.policyEnabled: false` disables policy without deleting rules. See the README Policy section for two copy-paste examples.
+
 Tool-input repairs apply to custom/extension tools only (`wishcraft.repairsEnabled`, default on). `/repairs` prints the counters.
 
 ## Token budget

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.23.4",
+  "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/hooks/index.ts

@@ -27,6 +27,14 @@ import {
   runHookCommand,
   type HookPayload,
 } from "./hooks-runner.ts";
+import {
+  parsePolicySettings,
+  type PolicyRule,
+} from "./policy-config.ts";
+import {
+  evalPostToolUsePolicy,
+  evalPreToolUsePolicy,
+} from "./policy-engine.ts";
 import {
   recordRepairs,
   repairToolInput,
@@ -34,6 +42,8 @@ import {
 
 let hooksSettings: WishcraftHooksSettings = {};
 let hooksEnabled = false;
+let policyRules: PolicyRule[] = [];
+let policyEnabled = false;
 let repairsEnabled = true;
 let pendingSessionContext: string | null = null;
 
@@ -46,6 +56,9 @@ function refreshSettings(cwd: string): void {
   const parsed = parseHooksSettings(globalWishcraft);
   hooksSettings = parsed.hooks;
   hooksEnabled = parsed.enabled && hasAnyHook(parsed.hooks);
+  const policy = parsePolicySettings(globalWishcraft);
+  policyRules = policy.rules;
+  policyEnabled = policy.enabled;
   repairsEnabled =
     !merged ||
     typeof merged !== "object" ||
@@ -125,6 +138,12 @@ export function setupHooks(
       const result = repairToolInput(toolName, event.input);
       if (result.repairs.length > 0) recordRepairs(result);
     }
+    if (policyEnabled) {
+      const policyVerdict = evalPreToolUsePolicy(policyRules, toolName, event.input);
+      if (policyVerdict.block) {
+        return { block: true, reason: policyVerdict.reason };
+      }
+    }
     if (!hooksEnabled) return;
     const cmds = commandsFor(hooksSettings, "preToolUse", toolName);
     if (cmds.length === 0) return;
@@ -147,27 +166,33 @@ export function setupHooks(
   });
 
   pi.on("tool_result", async (event: any, ctx: any) => {
-    if (!hooksEnabled) return;
-    const cmds = commandsFor(hooksSettings, "postToolUse", event.toolName);
-    if (cmds.length === 0) return;
-    const payload = basePayload("postToolUse", ctx);
-    payload.tool_use_id = event.toolCallId;
-    payload.tool_name = event.toolName;
-    payload.tool_input = event.input;
-    payload.tool_response =
-      typeof event.content === "string"
-        ? event.content
-        : Array.isArray(event.content)
-          ? event.content.map((c: any) => c.text ?? "").join("\n")
-          : "";
-    // parallel: één crashende hook annuleert de rest niet
-    const outs = await Promise.all(cmds.map((c) => runHookCommand(c, payload)));
     let extra = "";
-    for (const out of outs) {
-      const add = out.parsed?.hookSpecificOutput?.additionalContext;
-      if (add) extra += (extra ? "\n" : "") + add;
-      if (out.parsed?.systemMessage && ctx?.ui?.notify) {
-        ctx.ui.notify(out.parsed.systemMessage, "info");
+    if (policyEnabled) {
+      const inject = evalPostToolUsePolicy(policyRules, event.toolName, event.input);
+      if (inject) extra = inject.additionalContext;
+    }
+    if (hooksEnabled) {
+      const cmds = commandsFor(hooksSettings, "postToolUse", event.toolName);
+      if (cmds.length > 0) {
+        const payload = basePayload("postToolUse", ctx);
+        payload.tool_use_id = event.toolCallId;
+        payload.tool_name = event.toolName;
+        payload.tool_input = event.input;
+        payload.tool_response =
+          typeof event.content === "string"
+            ? event.content
+            : Array.isArray(event.content)
+              ? event.content.map((c: any) => c.text ?? "").join("\n")
+              : "";
+        // parallel: één crashende hook annuleert de rest niet
+        const outs = await Promise.all(cmds.map((c) => runHookCommand(c, payload)));
+        for (const out of outs) {
+          const add = out.parsed?.hookSpecificOutput?.additionalContext;
+          if (add) extra += (extra ? "\n" : "") + add;
+          if (out.parsed?.systemMessage && ctx?.ui?.notify) {
+            ctx.ui.notify(out.parsed.systemMessage, "info");
+          }
+        }
       }
     }
     if (extra && Array.isArray(event.content)) {

package/src/extension/hooks/policy-config.ts

@@ -0,0 +1,98 @@
+/**
+ * policy-config.ts
+ * ---------------------------------------------------------------------------
+ * Declarative policy rules (deny / inject) from global wishcraft settings.
+ * No process spawn — pure regex evaluation in-process.
+ *
+ *   "wishcraft": {
+ *     "policyEnabled": true,
+ *     "policy": [
+ *       { "action": "deny", "tool": "bash", "match": "sudo\\s+rm", "reason": "…" },
+ *       { "action": "inject", "tool": "read", "pathMatch": "\\.env", "context": "…" }
+ *     ]
+ *   }
+ *
+ * policyEnabled defaults to true when policy is non-empty; explicit false
+ * is the kill-switch. Malformed rules are dropped (no throw).
+ * ---------------------------------------------------------------------------
+ */
+
+export interface DenyPolicyRule {
+  action: "deny";
+  tool: string;
+  match: string;
+  reason: string;
+}
+
+export interface InjectPolicyRule {
+  action: "inject";
+  tool: string;
+  pathMatch: string;
+  context: string;
+}
+
+export type PolicyRule = DenyPolicyRule | InjectPolicyRule;
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function validRegex(pattern: string): boolean {
+  try {
+    new RegExp(pattern);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseDenyRule(v: unknown): DenyPolicyRule | null {
+  if (!isRecord(v) || v.action !== "deny") return null;
+  if (typeof v.tool !== "string" || !v.tool.trim()) return null;
+  if (typeof v.match !== "string" || !v.match.trim()) return null;
+  if (typeof v.reason !== "string" || !v.reason.trim()) return null;
+  if (!validRegex(v.match)) return null;
+  return {
+    action: "deny",
+    tool: v.tool,
+    match: v.match,
+    reason: v.reason,
+  };
+}
+
+function parseInjectRule(v: unknown): InjectPolicyRule | null {
+  if (!isRecord(v) || v.action !== "inject") return null;
+  if (typeof v.tool !== "string" || !v.tool.trim()) return null;
+  if (typeof v.pathMatch !== "string" || !v.pathMatch.trim()) return null;
+  if (typeof v.context !== "string" || !v.context.trim()) return null;
+  if (!validRegex(v.pathMatch)) return null;
+  return {
+    action: "inject",
+    tool: v.tool,
+    pathMatch: v.pathMatch,
+    context: v.context,
+  };
+}
+
+function parsePolicyRule(v: unknown): PolicyRule | null {
+  if (!isRecord(v)) return null;
+  if (v.action === "deny") return parseDenyRule(v);
+  if (v.action === "inject") return parseInjectRule(v);
+  return null;
+}
+
+/** Parse wishcraft policy settings. Invalid rules are dropped. */
+export function parsePolicySettings(wishcraftSettings: unknown): {
+  enabled: boolean;
+  rules: PolicyRule[];
+} {
+  if (!isRecord(wishcraftSettings)) return { enabled: false, rules: [] };
+  const raw = wishcraftSettings.policy;
+  if (!Array.isArray(raw)) return { enabled: false, rules: [] };
+  const rules = raw
+    .map(parsePolicyRule)
+    .filter((r): r is PolicyRule => r !== null);
+  if (rules.length === 0) return { enabled: false, rules: [] };
+  const enabled = wishcraftSettings.policyEnabled !== false;
+  return { enabled, rules };
+}

package/src/extension/hooks/policy-engine.ts

@@ -0,0 +1,80 @@
+/**
+ * policy-engine.ts
+ * ---------------------------------------------------------------------------
+ * Pure in-process policy evaluation (deny before tool use, inject after).
+ * ---------------------------------------------------------------------------
+ */
+
+import type { PolicyRule } from "./policy-config.ts";
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Text to match deny rules against (bash command or serialized input). */
+export function toolInputText(toolName: string, input: unknown): string {
+  if (toolName === "bash" && isRecord(input) && typeof input.command === "string") {
+    return input.command;
+  }
+  try {
+    return JSON.stringify(input ?? {});
+  } catch {
+    return String(input ?? "");
+  }
+}
+
+/** Path from tool input (read/write/edit and common aliases). */
+export function toolPath(input: unknown): string | null {
+  if (!isRecord(input)) return null;
+  for (const key of ["path", "filePath", "absolutePath", "target_file", "file_path"]) {
+    const v = input[key];
+    if (typeof v === "string" && v.length > 0) return v;
+  }
+  return null;
+}
+
+export type PreToolUsePolicyVerdict =
+  | { block: true; reason: string }
+  | { block: false };
+
+/** First matching deny rule wins. */
+export function evalPreToolUsePolicy(
+  rules: PolicyRule[],
+  toolName: string,
+  input: unknown,
+): PreToolUsePolicyVerdict {
+  const text = toolInputText(toolName, input);
+  for (const rule of rules) {
+    if (rule.action !== "deny" || rule.tool !== toolName) continue;
+    try {
+      if (new RegExp(rule.match).test(text)) {
+        return { block: true, reason: rule.reason };
+      }
+    } catch {
+      // invalid regex at runtime — skip
+    }
+  }
+  return { block: false };
+}
+
+/** All matching inject rules contribute context (in order). */
+export function evalPostToolUsePolicy(
+  rules: PolicyRule[],
+  toolName: string,
+  input: unknown,
+): { additionalContext: string } | null {
+  const path = toolPath(input);
+  if (path === null) return null;
+  let extra = "";
+  for (const rule of rules) {
+    if (rule.action !== "inject" || rule.tool !== toolName) continue;
+    try {
+      if (new RegExp(rule.pathMatch).test(path)) {
+        extra += (extra ? "\n" : "") + rule.context;
+      }
+    } catch {
+      // invalid regex at runtime — skip
+    }
+  }
+  return extra ? { additionalContext: extra } : null;
+}

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;
 }