portable-agent-layer 0.46.0 → 0.48.0

package/README.md

@@ -85,6 +85,8 @@ pal cli status        # check your setup
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
+| `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |
+| `pal cli skill doctor <name>` | Evaluate a skill against the authoring best practices (folder/file-name match, name, description, body length, point-of-view, reference depth) |
 
 ### Target flags
 

package/assets/skills/create-skill/SKILL.md

@@ -1,69 +1,77 @@
 ---
 name: create-skill
-description: Scaffold a new PAL skill from a description. Use when creating a new skill, adding a capability, or building a custom command. Enforces general, assistant-facing, personally-clean skill writing.
+description: Create a new personal skill for this user, scaffolded into their own ~/.pal/skills/ and linked into every installed agent. Use when the user asks to create a skill, add a capability, build a custom command, or "make a skill that…".
 argument-hint: <skill name> <skill description>
 ---
 
-## What makes a good PAL skill
+# Create a personal skill
 
-Before writing any skill, internalize these three rules. A skill that violates them gets re-written, not committed.
+This scaffolds a personal skill into the user's own `~/.pal/skills/<name>/` and links it into every installed agent so it is immediately discoverable.
 
-1. **Pointed at the assistant, not the user.** A skill is *instructions you (the assistant) follow*. Write in second person addressing yourself ("read X", "extract Y", "output Z"). Prescriptive verbs, deterministic flow. It is **not** a user tutorial, marketing blurb, or README. The user reads `README.md`; you read `SKILL.md`.
+## What makes a good skill
 
-2. **Zero personal information.** No usernames, real names, employer names, project codenames, dataset names, hostnames, absolute home paths (`C:\Users\someone\…`), email addresses, or anecdotes about the author's own work. A skill must be reusable by any user. If the rule is "don't expand `~` on Windows cmd," that is the rule — don't add "because $username's primary shell is cmd." Personal context belongs in the user's private memory, never in the skill body.
+1. **Pointed at the assistant, not the user.** A skill is *instructions you (the assistant) follow*. Write in second person addressing yourself ("read X", "run Y", "output Z"). Prescriptive verbs, deterministic flow — not a tutorial or marketing blurb.
 
-3. **General, not user-specific.** A skill describes a *workflow class* (e.g. "build a deck," "summarize a PDF," "lint a python file"), not a single user's habits. Use placeholders (`<deck-dir>`, `<input.pdf>`), not hardcoded paths. If the workflow only makes sense for one person, it is a memory entry or a personal hook, not a skill.
+2. **One skill, one job.** A skill describes a single workflow. If it needs branches like "for case A do X, for case B do Y," it is two skills.
+
+3. **Concise and concrete.** Assume the model is already smart — only add what it doesn't already know. Every step has a verb and an object; no "as needed" or "appropriately." Keep the SKILL.md body well under 500 lines; push long reference material into sibling files linked one level deep.
+
+A personal skill **may** contain this user's own context — their paths, project names, preferences, conventions. That is the point of a personal skill.
 
 ## Skill anatomy
 
 ```markdown
 ---
 name: <slug>                           # the slash-command name; lowercase-kebab
-description: <one sentence trigger>    # WHEN to invoke (used by the dispatcher), not WHAT it does
+description: <what it does + WHEN to invoke>   # the dispatcher matches on this
 argument-hint: <args>                  # optional; how the user passes input
 ---
 
 ## Overview / Workflow
 
-Numbered steps the assistant follows on invocation. Each step is concrete:
-read this file, run this command, ask this question, output this format.
+Numbered, concrete steps the assistant follows on invocation.
 
 ## Output format
 
-Exactly what the assistant returns to the user. Specify structure if the
-caller will parse it; specify tone if the caller is a human.
+Exactly what the assistant returns — structure if it will be parsed, tone if a human reads it.
 
 ## When to use / Do NOT use
 
-Two short lists. The "do not" list disambiguates this skill from neighbours
-that would otherwise also match the user's request.
+Two short lists; the "do not" list disambiguates this skill from neighbours.
 ```
 
-## Workflow when the user invokes `/create-skill <name> <description>`
-
-1. Sanity-check the name and description against the three rules above. If the description leaks personal info ("a skill for me to clean my Notion db"), rewrite it to the general form ("clean a Notion database via the API") before scaffolding.
-2. Create `assets/skills/<name>/SKILL.md` in the repo (the canonical source). The installed copy at `~/.pal/skills/<name>/SKILL.md` may be a junction to this path — verify the user's setup before assuming.
-3. Populate the SKILL.md from the anatomy above. Required fields: `name`, `description`, body sections (Workflow, Output format, When to use). Add `argument-hint` if the skill takes arguments.
-4. If the skill needs runtime tooling (TypeScript, scripts, vendored assets), scaffold a `tools/` subdir alongside SKILL.md. Otherwise leave the skill markdown-only.
-5. Validate before declaring done:
-   - **Trigger clarity** — could a model decide *not* to invoke this skill from the description alone? If yes, tighten the description.
-   - **Step concreteness** — every step has a verb and an object; no "as needed" or "appropriately."
-   - **Output specification** — caller knows what they get back.
-   - **Scope discipline** — one skill, one job. If the skill needs section headers like "for case A do X, for case B do Y," it is two skills.
-   - **Personal-info scan** — grep the new SKILL.md for usernames, real names, absolute home paths, employer or project codenames; remove any hits.
-   - **Generality test** — could a stranger with the same workflow need use this unchanged? If no, factor the user-specific bits into memory.
-
-## Anti-patterns to refuse
-
-- A SKILL.md whose description starts with "I want…" or "My …" — that's a journal entry, not a skill.
-- Hardcoded paths under `C:\Users\<name>\…` or `/Users/<name>/…` — use `~` (and document the cmd.exe `%USERPROFILE%` alternative if Windows is in scope).
-- Brand- or company-specific defaults baked into the skill body. Default brand colors, footer strings, etc. belong in *templates* (user data) or *config*, never in the skill.
-- A description longer than ~30 words, or one that explains the implementation rather than the trigger.
-- Skills that duplicate an existing skill's trigger surface. Read the existing skills index before scaffolding.
+The `description` should state **both what the skill does and when to invoke it**, in third person, with the trigger terms a model would match on. A vague description ("helps with documents") will not trigger reliably.
+
+## Workflow when invoked with `<name> <description>`
+
+1. Validate the name: lowercase-kebab, no spaces, not colliding with an existing skill (check `~/.pal/skills/` and the active skill list).
+2. Confirm the trigger with the user if the description is ambiguous about *when* the skill should fire.
+3. Create the directory and SKILL.md at the user's PAL home:
+   ```bash
+   mkdir -p ~/.pal/skills/<name>
+   ```
+   Write `~/.pal/skills/<name>/SKILL.md` populated from the anatomy above (frontmatter + Workflow + Output format + When to use).
+4. If the skill needs runtime tooling, scaffold a `tools/` subdir alongside SKILL.md and write the scripts there.
+5. Link the new skill into every installed agent so it is discoverable:
+   ```bash
+   pal cli skill link <name>
+   ```
+   This creates the per-skill discovery symlink in each installed agent's skills directory (Claude Code, Cursor, Copilot, Codex); opencode discovers it automatically via `~/.pal/skills/`.
+6. Run the doctor and resolve every error it reports:
+   ```bash
+   pal cli skill doctor <name>
+   ```
+   It checks the mechanical rules (folder/file-name match, name length/charset, description length, point-of-view, body length, reference depth). Fix all `✗` errors; weigh each `⚠` warning. A name/folder mismatch or a misnamed file makes the skill silently fail to load, so never skip this.
+7. Validate the rest by hand — the doctor can't judge these:
+   - **Trigger clarity** — could a model decide *not* to invoke this from the description alone? If so, tighten it.
+   - **Step concreteness** — every step has a verb and an object.
+   - **Output specification** — the caller knows what they get back.
+   - **Scope discipline** — one skill, one job.
 
 ## Output format
 
 After scaffolding, return:
-- The path of the created `SKILL.md`.
+- The path of the created `SKILL.md` (under `~/.pal/skills/<name>/`).
+- The agents it was linked into (from the `pal cli skill link` output).
 - A 2-3 sentence summary of the trigger and workflow.
-- Any anti-pattern violations you caught and corrected during scaffolding (so the user learns the rule).
+- How to invoke it (its `/<name>` slash command or trigger phrase).

package/assets/skills/playwright/tools/shot.ts

@@ -13,7 +13,7 @@
 //   node --experimental-strip-types ~/.pal/skills/playwright/tools/shot.ts <url> [opts]
 
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { chooseTier, parseArgs, type ShotOptions } from "./shot-lib.ts";
@@ -27,13 +27,23 @@ function playwrightCliAvailable(): boolean {
 }
 
 function runViaCli(opts: ShotOptions, out: string): boolean {
-  const open = spawnSync("playwright-cli", ["open", opts.url], { stdio: "inherit" });
-  if (open.status !== 0) return false;
-  const args = ["screenshot", `--filename=${out}`];
-  if (opts.selector) args.push(opts.selector);
-  const shot = spawnSync("playwright-cli", args, { stdio: "inherit" });
-  spawnSync("playwright-cli", ["close"], { stdio: "ignore" });
-  return shot.status === 0 && existsSync(out);
+  // playwright-cli writes a `.playwright-cli/` session dir (logs + page snapshots)
+  // into its cwd. Run it inside a throwaway temp dir so nothing lands in the user's
+  // repo, then remove it. `out` is already absolute, so the screenshot is unaffected.
+  // Cross-platform: os.tmpdir + fs.mkdtemp/rm — no shell, no platform-specific paths.
+  const work = mkdtempSync(join(tmpdir(), "pal-pwcli-"));
+  const run = (args: string[], quiet = false) =>
+    spawnSync("playwright-cli", args, { stdio: quiet ? "ignore" : "inherit", cwd: work });
+  try {
+    if (run(["open", opts.url]).status !== 0) return false;
+    const args = ["screenshot", `--filename=${out}`];
+    if (opts.selector) args.push(opts.selector);
+    const shot = run(args);
+    run(["close"], true);
+    return shot.status === 0 && existsSync(out);
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+  }
 }
 
 // "unavailable" = the engine itself can't run (package or Chromium missing) → MCP fallback.

package/assets/templates/PAL/ALGORITHM.md

@@ -165,6 +165,18 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 - Decide execution order — what's serial, what can parallelize
 - **Extended+:** use EnterPlanMode for user alignment before executing
 
+**Grounding Gate — verify the premises before EXECUTE.**
+
+Don't just *list* what must be true — actively confirm the load-bearing facts the criteria rest on. For each premise (a reported behavior, a provider/API contract, an external tool's CLI, a file's contents, a claim about system state):
+- **Reproduce** the reported behavior before designing a fix — no fix on an unreproduced bug.
+- **Fetch the authoritative source** (live docs, the actual file, `gh api`) before asserting how something works.
+- **Probe the dependency/contract** (tool availability, MCP account, env var, DB connectivity, exact CLI) before building on it.
+- **Confirm one concrete artifact** (a commit, a shebang, a line of output) behind any external claim.
+
+No criterion may rest on an unverified premise. If a premise can't be verified now, mark it explicitly as an assumption and add a criterion to check it during EXECUTE. After 2 failed attempts at the same sub-problem, stop and re-ground — re-run OBSERVE rather than iterating on a bad premise.
+
+Output: `🧭 GROUNDING: [premises verified, or assumptions flagged]`
+
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
 
 Do the work. Invoke selected capabilities via tool calls.
@@ -217,9 +229,11 @@ Focus: reasoning approach, problem decomposition, anticipation, blind spots.
 
 ```bash
 bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed N --failed N --sentiment 1-10 \
-  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection"
+  --q1 "self reflection" --q2 "algorithm reflection" --q3 "AI reflection" --scope general
 ```
 
+Set `--scope task-specific` when the Q2 idea is bound to this one task (e.g. a criterion that only matters for the specific file, API, or dataset you were handling) and would not generalize to the algorithm; use `general` (the default) for reusable structural improvements. This keeps the algorithm-update synthesis focused on changes worth folding into ALGORITHM.md.
+
 **3. Relationship note** — write one Session entry capturing what was done this session:
 
 ```bash
@@ -316,6 +330,7 @@ Only write if the insight is **genuine and reusable** — not every session prod
 ━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
 🧠 PREMORTEM: [failure modes]
+🧭 GROUNDING: [premises verified, or assumptions flagged]
 📐 APPROACH: [execution plan]
 
 ━━━ ⚡ EXECUTE ━━━ 3/5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {

package/src/cli/index.ts

@@ -16,6 +16,8 @@
  *   status                            Show current PAL configuration
  *   doctor                            Check prerequisites and system health
  *   usage                             Summarize token usage and cost
+ *   skill link <name>                 Link a personal ~/.pal/skills/<name>/ into installed agents
+ *   skill doctor <name>               Evaluate a skill against the authoring best practices
  */
 
 import { spawnSync } from "node:child_process";
@@ -192,6 +194,12 @@ async function runCli(command: string | undefined, args: string[]) {
       if (code !== 0) process.exit(code);
       break;
     }
+    case "skill": {
+      const { runSkill } = await import("./skill");
+      const code = await runSkill(args);
+      if (code !== 0) process.exit(code);
+      break;
+    }
     case "--help":
     case "-h":
     case "help":
@@ -234,6 +242,8 @@ function showHelp() {
     pal cli usage                           Summarize token usage and cost
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)
+    pal cli skill link <name>               Link a personal ~/.pal/skills/<name>/ into installed agents
+    pal cli skill doctor <name>             Evaluate a skill against the authoring best practices
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)

package/src/cli/skill.ts

@@ -0,0 +1,55 @@
+/**
+ * pal cli skill — manage personal skills under ~/.pal/skills/.
+ *
+ *   pal cli skill link <name>     Link an existing ~/.pal/skills/<name>/ into
+ *                                 every installed agent so it is discoverable.
+ *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
+ *                                 skill-authoring best practices.
+ */
+
+import { resolve } from "node:path";
+import { palHome } from "../hooks/lib/paths";
+import { linkPersonalSkill, log } from "../targets/lib";
+import { formatReport, lintSkill } from "../tools/skill-doctor";
+
+export async function runSkill(args: string[]): Promise<number> {
+  const [sub, name] = args;
+
+  if (sub === "doctor") {
+    if (!name) {
+      log.error("Usage: pal cli skill doctor <name>");
+      return 1;
+    }
+    const report = lintSkill(resolve(palHome(), "skills", name));
+    console.log(formatReport(report));
+    return report.errors > 0 ? 1 : 0;
+  }
+
+  if (sub === "link") {
+    if (!name) {
+      log.error("Usage: pal cli skill link <name>");
+      return 1;
+    }
+    try {
+      const linked = linkPersonalSkill(name);
+      if (linked.length === 0) {
+        log.warn(
+          `'${name}' linked to no per-skill agents (none installed). ` +
+            "It is still discoverable by opencode via ~/.pal/skills/."
+        );
+      } else {
+        log.success(
+          `Linked '${name}' into: ${linked.join(", ")} ` +
+            "(opencode: auto via ~/.pal/skills/)"
+        );
+      }
+      return 0;
+    } catch (e) {
+      log.error(e instanceof Error ? e.message : String(e));
+      return 1;
+    }
+  }
+
+  log.error("Usage: pal cli skill <link|doctor> <name>");
+  return 1;
+}

package/src/hooks/lib/algorithm-review.ts

@@ -0,0 +1,85 @@
+/**
+ * Algorithm-review cadence — decides when to nudge the MAINTAINER to run an
+ * `/algorithm-update` session (fold accumulated Q2 reflections into ALGORITHM.md).
+ *
+ * Maintainer-only by construction: the nudge fires solely in a PAL repo checkout,
+ * detected by the presence of the repo-only `.agents/skills/algorithm-update`
+ * skill. That path never ships to downstream installs — package.json `files`
+ * lists only `src/` and `assets/`, so `.agents/` is absent everywhere except a
+ * source checkout. Downstream users therefore never see this nudge.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { readReflections } from "./learning-store";
+import { palPkg, paths } from "./paths";
+
+const NUDGE_MIN_COUNT = 25;
+const NUDGE_MIN_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+function markFile(): string {
+  return resolve(paths.state(), "algorithm-review.json");
+}
+
+export function readReviewMark(): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastReviewedTs === "string" ? parsed.lastReviewedTs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeReviewMark(ts: string): void {
+  writeFileSync(markFile(), `${JSON.stringify({ lastReviewedTs: ts }, null, 2)}\n`);
+}
+
+/** True only in a maintainer repo checkout — the repo-only update skill is present. */
+export function isMaintainerEnv(): boolean {
+  return existsSync(
+    resolve(palPkg(), ".agents", "skills", "algorithm-update", "SKILL.md")
+  );
+}
+
+/** Count reflections newer than the last review mark (all of them, if never reviewed). */
+export function countUnreviewed(mark: string | null = readReviewMark()): number {
+  const reflections = readReflections(paths.reflectionsFile());
+  if (!mark) return reflections.length;
+  const cutoff = new Date(mark).getTime();
+  return reflections.filter((r) => r.ts && new Date(r.ts).getTime() > cutoff).length;
+}
+
+export interface ReviewNudge {
+  count: number;
+  sinceDays: number;
+  since: string | null;
+}
+
+/**
+ * Nudge data when BOTH thresholds are met (≥25 new AND ≥7 days) in a maintainer
+ * env, else null. `now` is injected for testability.
+ */
+export function algorithmReviewNudge(now: Date): ReviewNudge | null {
+  if (!isMaintainerEnv()) return null;
+  const mark = readReviewMark();
+  const count = countUnreviewed(mark);
+  if (count < NUDGE_MIN_COUNT) return null;
+  const sinceDays = mark
+    ? Math.floor((now.getTime() - new Date(mark).getTime()) / DAY_MS)
+    : Number.POSITIVE_INFINITY;
+  if (sinceDays < NUDGE_MIN_DAYS) return null;
+  return { count, sinceDays, since: mark };
+}
+
+/** Formatted nudge section for the session reminder, or "" when it shouldn't fire. */
+export function loadAlgorithmReviewNudge(now: Date = new Date()): string {
+  const n = algorithmReviewNudge(now);
+  if (!n) return "";
+  const since = n.since ? new Date(n.since).toISOString().slice(0, 10) : "the start";
+  const age = Number.isFinite(n.sinceDays) ? `, ${n.sinceDays}d` : "";
+  return [
+    "## Algorithm Review Due",
+    `🔧 ${n.count} new algorithm reflections since ${since}${age} — run \`/algorithm-update\` to fold the recurring ones into ALGORITHM.md.`,
+  ].join("\n");
+}

package/src/hooks/lib/context.ts

@@ -6,6 +6,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { loadAlgorithmReviewNudge } from "./algorithm-review";
 import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
@@ -312,9 +313,12 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
     ? loadSessionIntelligence()
     : "";
   const handoff = settings.isEnabled("handoff") ? loadHandoff() : "";
+  // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
+  const algoReview = loadAlgorithmReviewNudge();
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
+  if (algoReview) parts.push(algoReview);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);

package/src/hooks/lib/learning-store.ts

@@ -158,3 +158,48 @@ export function readLearnings(baseDir: string, limit?: number): LearningEntry[]
 
   return entries;
 }
+
+// ── Reflections ──
+
+export interface ReflectionEntry {
+  ts: string;
+  cwd: string;
+  task: string;
+  sentiment: number;
+  q1: string;
+  q2: string;
+  q3: string;
+  /** Whether the improvement ideas generalize to the algorithm, or are task-bound. */
+  scope: "general" | "task-specific";
+}
+
+/**
+ * Read algorithm reflections from the JSONL store, newest first. Each line is one
+ * reflection produced at the end of an Algorithm run (q1 = what I'd do differently,
+ * q2 = algorithm improvement, q3 = AI-level insight).
+ */
+export function readReflections(file: string, limit?: number): ReflectionEntry[] {
+  if (!existsSync(file)) return [];
+  const entries: ReflectionEntry[] = [];
+  for (const line of readFileSync(file, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const o = JSON.parse(line);
+      entries.push({
+        ts: o.timestamp || "",
+        cwd: o.cwd || "",
+        task: o.task || "",
+        sentiment: typeof o.sentiment === "number" ? o.sentiment : 0,
+        q1: o.q1 || "",
+        q2: o.q2 || "",
+        q3: o.q3 || "",
+        // Untagged (e.g. the existing backlog) defaults to general — the common case.
+        scope: o.scope === "task-specific" ? "task-specific" : "general",
+      });
+    } catch {
+      /* skip malformed line */
+    }
+  }
+  entries.reverse(); // JSONL is appended chronologically → newest first
+  return limit ? entries.slice(0, limit) : entries;
+}

package/src/hooks/lib/paths.ts

@@ -50,6 +50,9 @@ export const paths = {
   knowledge: () => ensureDir(home("memory", "knowledge")),
   knowledgeDomain: (d: string) => ensureDir(home("memory", "knowledge", d)),
   failures: () => ensureDir(home("memory", "learning", "failures")),
+  reflections: () => ensureDir(home("memory", "learning", "reflections")),
+  reflectionsFile: () =>
+    home("memory", "learning", "reflections", "algorithm-reflections.jsonl"),
   retrievalIndex: () => home("memory", "learning", ".retrieval-index.json"),
   progress: () => ensureDir(home("memory", "state", "progress")),
   projectHistory: () => ensureDir(home("memory", "projects")),

package/src/hooks/lib/retrieval-index.ts

@@ -1,6 +1,6 @@
 /**
  * Retrieval index — single JSON file with per-doc term-frequency vectors and a global
- * document-frequency table over the failures + wisdom-frames corpus.
+ * document-frequency table over the failures + wisdom-frames + reflections corpus.
  *
  * Built once on first read, rebuilt in the background when source dirs change.
  * Read by the UserPromptSubmit retrieval handler; written by ensureIndex (sync bootstrap)
@@ -11,17 +11,18 @@ import { spawn } from "node:child_process";
 import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { SIMILARITY_THRESHOLD } from "./graduation";
-import { readFailures } from "./learning-store";
+import { readFailures, readReflections } from "./learning-store";
 import { logDebug, logError } from "./log";
 import { palPkg, paths } from "./paths";
 import { similarity, tokenize } from "./text-similarity";
 import { readFramesForRetrieval } from "./wisdom";
 
-const INDEX_VERSION = 1;
+// v2: added "reflection" source — bump invalidates v1 caches so they rebuild with it.
+const INDEX_VERSION = 2;
 
 export interface IndexedDoc {
   id: string;
-  source: "failure" | "wisdom";
+  source: "failure" | "wisdom" | "reflection";
   path: string;
   rating: number;
   ts: string;
@@ -144,6 +145,32 @@ export function buildIndex(): RetrievalIndex {
     });
   }
 
+  // Reflections — each Algorithm run's self-observations. q1 ("what I'd do
+  // differently") is the actionable lesson; q2/q3 add process and reasoning signal.
+  for (const r of readReflections(paths.reflectionsFile())) {
+    const tokens = buildDocTokens([
+      { text: r.q1, weight: 3 },
+      { text: r.task, weight: 2 },
+      { text: r.q2, weight: 2 },
+      { text: r.q3, weight: 1 },
+    ]);
+    if (tokens.length === 0) continue;
+    const { tf, len } = buildTermFreq(tokens);
+    for (const term of Object.keys(tf)) df[term] = (df[term] ?? 0) + 1;
+    docs.push({
+      id: `reflect:${r.ts}`,
+      source: "reflection",
+      path: paths.reflectionsFile(),
+      rating: r.sentiment,
+      ts: r.ts,
+      tf,
+      len,
+      displayPrinciple: r.q1,
+      displayContext: r.task,
+      cwd: r.cwd || undefined,
+    });
+  }
+
   return {
     version: INDEX_VERSION,
     builtAt: new Date().toISOString(),
@@ -173,7 +200,7 @@ export function readIndex(): RetrievalIndex | null {
 export function isStale(index: RetrievalIndex): boolean {
   try {
     const builtMs = new Date(index.builtAt).getTime();
-    for (const dir of [paths.failures(), paths.wisdom()]) {
+    for (const dir of [paths.failures(), paths.wisdom(), paths.reflections()]) {
       if (!existsSync(dir)) continue;
       if (statSync(dir).mtimeMs > builtMs) return true;
     }

package/src/hooks/lib/retrieval.ts

@@ -131,7 +131,8 @@ function formatLine(s: ScoredDoc): string {
     return `- ${tag} ${principle} (CRYSTAL ${s.doc.rating}%)`;
   }
   const ago = formatAgo(s.doc.ts);
-  const meta = ago ? `rating ${s.doc.rating}/10, ${ago}` : `rating ${s.doc.rating}/10`;
+  const kind = s.doc.source === "reflection" ? "reflection" : "rating";
+  const meta = ago ? `${kind} ${s.doc.rating}/10, ${ago}` : `${kind} ${s.doc.rating}/10`;
   return `- ${tag} ${principle} (${meta})`;
 }
 

package/src/hooks/lib/semi-static.ts

@@ -9,7 +9,7 @@
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { parse } from "./frontmatter";
-import { readFailures } from "./learning-store";
+import { type FailureEntry, readFailures } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { palHome, paths } from "./paths";
 import { readFramePrinciples } from "./wisdom";
@@ -100,16 +100,39 @@ export function loadSynthesisRecommendations(): string {
   }
 }
 
-/** Build the 5 most recent failure lessons as an avoid-list. */
+/**
+ * Rank failures for injection: same-project (cwd match) first, then by recency.
+ * Project-relevant lessons are never crowded out by more-recent other-project
+ * ones — fixing the case where (e.g.) a web-app's cache lessons dominate a CLI
+ * session purely because they were logged last. Returns the top `limit`.
+ */
+export function rankFailures(
+  entries: FailureEntry[],
+  cwd: string,
+  limit = 5
+): FailureEntry[] {
+  return [...entries]
+    .sort((a, b) => {
+      const am = a.cwd === cwd;
+      const bm = b.cwd === cwd;
+      if (am !== bm) return am ? -1 : 1;
+      return (b.ts || "").localeCompare(a.ts || ""); // recency desc within a group
+    })
+    .slice(0, limit);
+}
+
+/** Build the failure avoid-list, prioritized by relevance to the current project. */
 export function loadFailurePatterns(): string {
   try {
-    const entries = readFailures(paths.failures(), 5);
-    if (entries.length === 0) return "";
+    const cwd = process.cwd();
+    const all = readFailures(paths.failures());
+    if (all.length === 0) return "";
 
-    const lines = entries.map((e) => {
+    const lines = rankFailures(all, cwd).map((e) => {
       const label = e.rating ? `[${e.rating}/10]` : "";
+      const tag = e.cwd === cwd ? "[project]" : "[other]";
       const text = e.principle || e.context;
-      return `- ${label} ${text}`.trim();
+      return `- ${label} ${tag} ${text}`.trim();
     });
 
     return ["## Lessons from Recent Failures — Apply These Now", ...lines].join("\n");

package/src/targets/lib.ts

@@ -506,6 +506,46 @@ export function copySkills(claudeSkillsDir: string): number {
   return count;
 }
 
+/**
+ * Agent skills directories that need a per-skill discovery link.
+ *
+ * opencode is intentionally absent: it discovers the whole ~/.pal/skills/ tree
+ * via the ~/.agents/skills → ~/.pal/skills symlink, so any personal skill is
+ * picked up without a per-skill link.
+ */
+function perSkillAgentDirs(): { agent: string; dir: string }[] {
+  return [
+    { agent: "claude", dir: resolve(platform.claudeDir(), "skills") },
+    { agent: "cursor", dir: resolve(platform.cursorDir(), "skills") },
+    { agent: "copilot", dir: resolve(platform.copilotDir(), "skills") },
+    { agent: "codex", dir: resolve(platform.codexDir(), "skills") },
+  ];
+}
+
+/**
+ * Link a personal skill that already lives at ~/.pal/skills/<name>/ into every
+ * installed agent's skills directory so the agent discovers it. Mirrors the
+ * per-skill discovery link copySkills() creates for shipped skills.
+ *
+ * An agent counts as installed when its skills directory already exists.
+ * Returns the agents a discovery link was created for (opencode excluded — it
+ * is covered by the whole-dir ~/.agents/skills link).
+ */
+export function linkPersonalSkill(name: string): string[] {
+  const palLink = resolve(PAL_SKILLS_DIR, name);
+  if (!existsSync(resolve(palLink, "SKILL.md"))) {
+    throw new Error(`No skill found at ${palLink}/SKILL.md`);
+  }
+  const linkType = process.platform === "win32" ? "junction" : "dir";
+  const linked: string[] = [];
+  for (const { agent, dir } of perSkillAgentDirs()) {
+    if (!existsSync(dir)) continue; // agent not installed
+    ensureSymlink(resolve(dir, name), palLink, linkType);
+    linked.push(agent);
+  }
+  return linked;
+}
+
 /** Create or update a symlink/junction, replacing any non-symlink entry. */
 function ensureSymlink(link: string, target: string, type: "dir" | "junction"): void {
   try {

package/src/tools/agent/algorithm-reflect.ts

@@ -12,8 +12,7 @@
  *     --q3 "Missed the implicit constraint about cross-platform"
  */
 
-import { appendFileSync, existsSync, mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { appendFileSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { paths } from "../../hooks/lib/paths";
 
@@ -30,14 +29,15 @@ interface AlgorithmReflection {
   q1: string;
   q2: string;
   q3: string;
+  /** general = the improvement ideas generalize to the algorithm; task-specific = bound to this task. */
+  scope: "general" | "task-specific";
 }
 
 // ── Core ──
 
 function reflectionsPath(): string {
-  const dir = resolve(paths.learning(), "reflections");
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  return resolve(dir, "algorithm-reflections.jsonl");
+  paths.reflections(); // ensures the directory exists
+  return paths.reflectionsFile();
 }
 
 function appendReflection(reflection: AlgorithmReflection): {
@@ -70,6 +70,7 @@ function run() {
       q1: { type: "string" },
       q2: { type: "string" },
       q3: { type: "string" },
+      scope: { type: "string" },
       help: { type: "boolean", short: "h" },
     },
   });
@@ -91,6 +92,7 @@ Arguments:
   --q1          Q1 — Self: what I'd do differently
   --q2          Q2 — Algorithm: structural improvement
   --q3          Q3 — AI: reasoning blind spot
+  --scope       general (default) | task-specific — is the algorithm idea reusable or task-bound?
 
 Output: algorithm-reflections.jsonl in memory/learning/reflections/
 `);
@@ -113,6 +115,9 @@ Output: algorithm-reflections.jsonl in memory/learning/reflections/
     q1: values.q1,
     q2: values.q2,
     q3: values.q3,
+    // Default to general (the ~94% case); only "task-specific" suppresses it
+    // from algorithm-update clustering.
+    scope: values.scope === "task-specific" ? "task-specific" : "general",
   };
 
   const result = appendReflection(reflection);

package/src/tools/agent/algorithm-synthesize.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env bun
+/**
+ * algorithm-synthesize — surface the Q2 field ("what a smarter algorithm would
+ * have done") across algorithm reflections, pre-sorted into candidate areas, to
+ * drive the periodic algorithm-update session: the loop from collected
+ * reflections back into ALGORITHM.md itself.
+ *
+ * IMPORTANT — the keyword BUCKETS are a *heuristic pre-sort hint only*, biased to
+ * the current model's English phrasing. They are NOT the clustering authority:
+ * another model wording the same idea differently ("double-check the assumption"
+ * vs "verify the premise") will not match. The real clustering is semantic, done
+ * by the model reading this report in the session. Therefore the tool NEVER drops
+ * data — every unmatched Q2 is surfaced in full under "Unbucketed", so nothing is
+ * invisible even when (especially when) the keyword sort misses or mis-sorts it.
+ *
+ * Library:  import { synthesizeAlgorithm, formatAlgorithmReport } from ".../algorithm-synthesize"
+ * Script:   bun src/tools/agent/algorithm-synthesize.ts [--since <ISO>] [--json]
+ */
+
+import { parseArgs } from "node:util";
+import { readReflections } from "../../hooks/lib/learning-store";
+import { paths } from "../../hooks/lib/paths";
+
+/** Algorithm areas a Q2 idea can target, mapped to ALGORITHM.md structure. */
+const BUCKETS: { key: string; label: string; patterns: RegExp }[] = [
+  {
+    key: "verify-gate",
+    label: "Establish grounding before acting (verify a fact / prerequisite first)",
+    patterns:
+      /pre-?check|pre-?mortem|premise|primary source|verif\w+|reproduce|before (writ|cod|propos|assert|implement|build|run|any|attempt|fetch|explor)|dependency scan|sanity-check|confirm .* before|prerequisite|gate (in|before)|trace .* first|check\w* .* before|anchor on|upfront|connectivity before|resolve .* before|triangulat|contradiction-detection|credibility gate|escalation|after \d+ (failed|iteration)/i,
+  },
+  {
+    key: "criteria",
+    label: "Criteria quality (atomicity, splitting, coverage, anti-criteria)",
+    patterns: /criteri|atomic|anti-criter|split .* criter|a .* criterion|enumerate/i,
+  },
+  {
+    key: "capability",
+    label: "Capability selection (plan mode, subagents, parallelism, research)",
+    patterns:
+      /capabilit|plan ?mode|askuser|sub-?agent|parallel|in one (agent|batch)|research|worktree/i,
+  },
+  {
+    key: "read-first",
+    label: "Read existing code/docs first (prior-artifact / context scan)",
+    patterns:
+      /read (the|existing|both)|inspect|prior-?artifact|existing (code|repo|hook|target)|grep|survey .* (before|first)/i,
+  },
+  {
+    key: "phase-structure",
+    label: "Phase structure (OBSERVE / PLAN / EXECUTE / VERIFY / LEARN ordering)",
+    patterns:
+      /observe|\bplan phase\b|execute|\bverify phase\b|\blearn phase\b|between (observe|plan|execute|verify)|new phase|a .* phase\b/i,
+  },
+  {
+    key: "scope",
+    label: "Scope & altitude (minimal change, avoid over-engineering)",
+    patterns: /scope|altitude|minimal|over-?eng|too (broad|wide|much)|narrow/i,
+  },
+];
+
+interface AlgorithmBucket {
+  key: string;
+  label: string;
+  count: number;
+  avgSentiment: number;
+  projects: number;
+  quotes: string[];
+}
+
+export interface AlgorithmSynthesis {
+  /** Count of general Q2s clustered (task-specific ones are surfaced separately). */
+  total: number;
+  since: string | null;
+  buckets: AlgorithmBucket[];
+  /** Count of general Q2s the keyword pre-sort matched no bucket for. */
+  unbucketed: number;
+  /** Full deduped text of every unbucketed general Q2 — the safety net, never just a count. */
+  unbucketedQuotes: string[];
+  /** Count of Q2s tagged task-specific (excluded from clustering, kept for review). */
+  taskSpecific: number;
+  /** Full deduped text of task-specific Q2s — surfaced, never dropped. */
+  taskSpecificQuotes: string[];
+}
+
+function projectOf(cwd: string): string {
+  return cwd.split("/").filter(Boolean).pop() ?? "";
+}
+
+/**
+ * Cluster Q2 reflections into candidate algorithm-improvement areas. A Q2 may
+ * land in multiple buckets (ideas often span areas); `unbucketed` counts Q2s
+ * that matched none, so blind spots in the bucket set stay visible.
+ */
+export function synthesizeAlgorithm(since?: Date): AlgorithmSynthesis {
+  const all = readReflections(paths.reflectionsFile());
+  const filtered = since ? all.filter((r) => r.ts && new Date(r.ts) >= since) : all;
+  const withQ2 = filtered.filter((r) => r.q2.trim());
+  // Cluster only general ideas; task-specific ones don't generalize to the
+  // algorithm, so surface them separately rather than polluting the buckets.
+  const q2s = withQ2.filter((r) => r.scope !== "task-specific");
+  const taskSpecificQuotes = [
+    ...new Set(withQ2.filter((r) => r.scope === "task-specific").map((r) => r.q2.trim())),
+  ];
+
+  const acc = new Map<
+    string,
+    { sentiments: number[]; projects: Set<string>; quotes: string[] }
+  >();
+  for (const b of BUCKETS) {
+    acc.set(b.key, { sentiments: [], projects: new Set(), quotes: [] });
+  }
+
+  let unbucketed = 0;
+  const unbucketedQuotes: string[] = [];
+  for (const r of q2s) {
+    const matched = BUCKETS.filter((b) => b.patterns.test(r.q2));
+    if (matched.length === 0) {
+      unbucketed += 1;
+      unbucketedQuotes.push(r.q2.trim());
+      continue;
+    }
+    for (const b of matched) {
+      const a = acc.get(b.key);
+      if (!a) continue;
+      a.sentiments.push(r.sentiment);
+      if (r.cwd) a.projects.add(projectOf(r.cwd));
+      a.quotes.push(r.q2.trim());
+    }
+  }
+
+  const buckets: AlgorithmBucket[] = BUCKETS.map((b) => {
+    const a = acc.get(b.key);
+    const sentiments = a?.sentiments ?? [];
+    const avg = sentiments.length
+      ? sentiments.reduce((s, n) => s + n, 0) / sentiments.length
+      : 0;
+    // Full deduped membership, longest (most specific) first. Not capped here —
+    // --json carries every member so nothing is lost; the human report caps the
+    // display per bucket. Zero-loss is the contract.
+    const quotes = [...new Set(a?.quotes ?? [])].sort((x, y) => y.length - x.length);
+    return {
+      key: b.key,
+      label: b.label,
+      count: sentiments.length,
+      avgSentiment: Math.round(avg * 10) / 10,
+      projects: a?.projects.size ?? 0,
+      quotes,
+    };
+  })
+    .filter((b) => b.count > 0)
+    .sort((x, y) => y.count - x.count);
+
+  return {
+    total: q2s.length,
+    since: since ? since.toISOString() : null,
+    buckets,
+    unbucketed,
+    unbucketedQuotes: [...new Set(unbucketedQuotes)],
+    taskSpecific: taskSpecificQuotes.length,
+    taskSpecificQuotes,
+  };
+}
+
+/** Render the synthesis as a markdown candidate-changes report. */
+export function formatAlgorithmReport(s: AlgorithmSynthesis): string {
+  const sinceLabel = s.since ? ` since ${s.since.slice(0, 10)}` : " (all time)";
+  const tsLabel = s.taskSpecific > 0 ? ` (+${s.taskSpecific} task-specific, below)` : "";
+  const lines = [
+    "# Algorithm Update — Candidate Changes",
+    `Source: ${s.total} general Q2 reflections${sinceLabel}${tsLabel}`,
+    "",
+    "> The buckets below are a keyword pre-sort hint (biased to current wording).",
+    "> Cluster semantically yourself — and read the Unbucketed section in full,",
+    "> since that is where wording the heuristic missed lands.",
+    "",
+    "## Pre-sorted candidate areas",
+  ];
+  s.buckets.forEach((b, i) => {
+    lines.push(
+      `### ${i + 1}. ${b.label}`,
+      `${b.count} reflections · avg sentiment ${b.avgSentiment}/10 · ${b.projects} project(s)`,
+      ""
+    );
+    for (const q of b.quotes.slice(0, 5)) lines.push(`- ${q}`);
+    if (b.quotes.length > 5) lines.push(`- _…+${b.quotes.length - 5} more (see --json)_`);
+    lines.push("");
+  });
+  lines.push(
+    `## Unbucketed — ${s.unbucketed} general Q2s the pre-sort missed (cluster these by hand)`,
+    ""
+  );
+  for (const q of s.unbucketedQuotes) lines.push(`- ${q}`);
+  if (s.taskSpecific > 0) {
+    lines.push(
+      "",
+      `## Task-specific — ${s.taskSpecific} Q2s tagged not-generalizable (review, don't fold into ALGORITHM.md)`,
+      ""
+    );
+    for (const q of s.taskSpecificQuotes) lines.push(`- ${q}`);
+  }
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      since: { type: "string" },
+      json: { type: "boolean", default: false },
+    },
+  });
+  const since = values.since ? new Date(values.since) : undefined;
+  const result = synthesizeAlgorithm(since);
+  console.log(
+    values.json ? JSON.stringify(result, null, 2) : formatAlgorithmReport(result)
+  );
+}

package/src/tools/skill-doctor.ts

@@ -0,0 +1,254 @@
+/**
+ * skill-doctor — static evaluator for a SKILL.md against Anthropic's
+ * skill-authoring best practices. Checks only what is mechanically verifiable:
+ * name/description constraints, body length, point-of-view, and reference depth.
+ *
+ * Library:  import { lintSkill, formatReport } from ".../skill-doctor"
+ * Script:   bun src/tools/skill-doctor.ts <skill-dir-or-name>
+ *           (resolves a path, or a name under ~/.pal/skills/)
+ * CLI:      pal cli skill doctor <name>   (see src/cli/skill.ts)
+ */
+
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { palHome } from "../hooks/lib/paths";
+
+type Level = "pass" | "warn" | "error";
+
+interface DoctorFinding {
+  level: Level;
+  check: string;
+  message: string;
+}
+
+export interface DoctorReport {
+  dir: string;
+  name: string | null;
+  findings: DoctorFinding[];
+  errors: number;
+  warnings: number;
+}
+
+interface ParsedSkill {
+  name: string | null;
+  description: string | null;
+  body: string;
+}
+
+const RESERVED_WORDS = ["anthropic", "claude"];
+const MAX_NAME = 64;
+const MAX_DESCRIPTION = 1024;
+const MAX_BODY_LINES = 500;
+
+/** Split a SKILL.md into frontmatter fields and body. */
+function parseSkill(content: string): ParsedSkill {
+  const parts = content.split(/^---\s*$/m);
+  if (parts.length < 3) {
+    return { name: null, description: null, body: content };
+  }
+  const frontmatter = parts[1];
+  const body = parts.slice(2).join("---");
+  const name = /^name:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
+  const description = /^description:\s*"?(.+?)"?\s*$/m.exec(frontmatter)?.[1] ?? null;
+  return { name, description, body };
+}
+
+/** Remove fenced and inline code so prose checks don't trip on examples. */
+function stripCode(s: string): string {
+  return s.replace(/```[\s\S]*?```/g, "").replace(/`[^`]*`/g, "");
+}
+
+/**
+ * Evaluate the skill at `skillDir` (a folder containing SKILL.md) and return a
+ * structured report. Hard rules from Anthropic's validation surface as errors;
+ * best-practice nudges surface as warnings.
+ */
+export function lintSkill(skillDir: string): DoctorReport {
+  const findings: DoctorFinding[] = [];
+  const add = (level: Level, check: string, message: string) =>
+    findings.push({ level, check, message });
+
+  if (!existsSync(skillDir)) {
+    add("error", "structure", `No skill directory at ${skillDir}`);
+    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
+  }
+
+  // The runtime only loads a file named exactly `SKILL.md`. On case-insensitive
+  // filesystems (macOS, Windows) `existsSync` would accept `skill.md`, so match
+  // the real on-disk entry, not a case-folded path.
+  const skillFile = readdirSync(skillDir).find((e) => e.toLowerCase() === "skill.md");
+  if (!skillFile) {
+    add("error", "structure", `No SKILL.md found in ${skillDir}`);
+    return { dir: skillDir, name: null, findings, errors: 1, warnings: 0 };
+  }
+  skillFile === "SKILL.md"
+    ? add("pass", "file.name", "skill file is named SKILL.md")
+    : add(
+        "error",
+        "file.name",
+        `skill file is "${skillFile}" — must be exactly "SKILL.md" or the skill is silently ignored`
+      );
+
+  const { name, description, body } = parseSkill(
+    readFileSync(resolve(skillDir, skillFile), "utf-8")
+  );
+
+  // The runtime keys a skill by its folder name; a mismatched frontmatter `name`
+  // makes the skill silently fail to load.
+  const folder = basename(skillDir);
+  if (name) {
+    name === folder
+      ? add("pass", "name.folder", `matches folder "${folder}"`)
+      : add(
+          "error",
+          "name.folder",
+          `name "${name}" must equal the folder name "${folder}" verbatim — otherwise the skill is silently ignored`
+        );
+  }
+
+  // ── name ──
+  if (!name) {
+    add("error", "name", "Missing `name` in frontmatter");
+  } else {
+    name.length <= MAX_NAME
+      ? add("pass", "name.length", `${name.length}/${MAX_NAME} chars`)
+      : add("error", "name.length", `${name.length} chars exceeds ${MAX_NAME}`);
+    /^[a-z0-9-]+$/.test(name)
+      ? add("pass", "name.charset", "lowercase letters, numbers, hyphens only")
+      : add(
+          "error",
+          "name.charset",
+          `"${name}" must be lowercase a-z, 0-9, hyphens only`
+        );
+    const reserved = RESERVED_WORDS.find((w) => name.toLowerCase().includes(w));
+    reserved
+      ? add("error", "name.reserved", `contains reserved word "${reserved}"`)
+      : add("pass", "name.reserved", "no reserved words");
+  }
+
+  // ── description ──
+  if (!description) {
+    add("error", "description", "Missing `description` in frontmatter");
+  } else {
+    description.length <= MAX_DESCRIPTION
+      ? add(
+          "pass",
+          "description.length",
+          `${description.length}/${MAX_DESCRIPTION} chars`
+        )
+      : add(
+          "error",
+          "description.length",
+          `${description.length} chars exceeds ${MAX_DESCRIPTION}`
+        );
+    /<[^>]+>/.test(description)
+      ? add(
+          "warn",
+          "description.xml",
+          "contains angle-bracket content — Anthropic disallows XML tags; rephrase placeholders like <x> in prose"
+        )
+      : add("pass", "description.xml", "no XML tags");
+    /\bwhen/i.test(description)
+      ? add("pass", "description.trigger", "states when to use the skill")
+      : add(
+          "warn",
+          "description.trigger",
+          "no 'when to use' trigger — add 'Use when …' so the dispatcher can match it"
+        );
+    /\b(I can|I['’]ll|I will|I help|you can|you will|you could|you['’]ll)\b/i.test(
+      description
+    )
+      ? add(
+          "warn",
+          "description.pov",
+          "reads first/second person — write descriptions in third person (e.g. 'Processes…', 'Generates…')"
+        )
+      : add("pass", "description.pov", "third person");
+  }
+
+  // ── body ──
+  const bodyLines = body.split("\n").length;
+  bodyLines <= MAX_BODY_LINES
+    ? add("pass", "body.length", `${bodyLines}/${MAX_BODY_LINES} lines`)
+    : add(
+        "warn",
+        "body.length",
+        `${bodyLines} lines exceeds ${MAX_BODY_LINES} — split into reference files`
+      );
+
+  const prose = stripCode(body);
+  /\b(I['’]m|I will|I['’]ll|in my experience|my workflow|I wrote|I created)\b/i.test(
+    prose
+  )
+    ? add(
+        "warn",
+        "body.pov",
+        "body uses first-person author voice — write it as second-person instructions to the assistant"
+      )
+    : add("pass", "body.pov", "instructional voice");
+
+  // ── reference depth (one level deep) ──
+  const linkRe = /\[[^\]]+\]\(([^)]+\.md)\)/g;
+  const hasMdLink = /\[[^\]]+\]\([^)]+\.md\)/;
+  let nested = false;
+  for (const m of body.matchAll(linkRe)) {
+    const target = m[1];
+    if (/^https?:/.test(target)) continue;
+    const targetPath = resolve(skillDir, target);
+    if (!existsSync(targetPath)) continue;
+    const refContent = readFileSync(targetPath, "utf-8");
+    if (hasMdLink.test(refContent)) {
+      nested = true;
+      add(
+        "warn",
+        "references.depth",
+        `${target} links to further .md files — keep references one level deep from SKILL.md`
+      );
+    }
+  }
+  if (!nested) add("pass", "references.depth", "references are one level deep");
+
+  // ── windows-style paths ──
+  /\b[\w.-]+\\[\w.-]+\.(py|ts|js|sh|md|json)\b/.test(body)
+    ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
+    : add("pass", "paths", "forward-slash paths");
+
+  const errors = findings.filter((f) => f.level === "error").length;
+  const warnings = findings.filter((f) => f.level === "warn").length;
+  return { dir: skillDir, name, findings, errors, warnings };
+}
+
+/** Render a report as a human-readable string. */
+export function formatReport(r: DoctorReport): string {
+  const icon = { pass: "✓", warn: "⚠", error: "✗" } as const;
+  const lines = [`skill-doctor: ${r.name ?? "(unparsed)"}  —  ${r.dir}`];
+  for (const f of r.findings) {
+    lines.push(`  ${icon[f.level]} ${f.check}: ${f.message}`);
+  }
+  let verdict: string;
+  if (r.errors > 0) {
+    verdict = `FAIL — ${r.errors} error(s), ${r.warnings} warning(s)`;
+  } else if (r.warnings > 0) {
+    verdict = `OK with ${r.warnings} warning(s)`;
+  } else {
+    verdict = "PASS — all checks clean";
+  }
+  lines.push(`  ${verdict}`);
+  return lines.join("\n");
+}
+
+if (import.meta.main) {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("Usage: bun src/tools/skill-doctor.ts <skill-dir-or-name>");
+    process.exit(2);
+  }
+  let dir = resolve(arg);
+  if (!existsSync(resolve(dir, "SKILL.md"))) {
+    const byName = resolve(palHome(), "skills", arg);
+    if (existsSync(resolve(byName, "SKILL.md"))) dir = byName;
+  }
+  const report = lintSkill(dir);
+  console.log(formatReport(report));
+  process.exit(report.errors > 0 ? 1 : 0);
+}