portable-agent-layer 0.45.2 → 0.47.0

package/README.md

@@ -85,6 +85,7 @@ 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 |
 
 ### Target flags
 

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

@@ -1,69 +1,72 @@
 ---
 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. Validate before declaring done:
+   - **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/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: playwright
+description: Capture a screenshot of a URL or local page and load it into context for a visual check. Use when asked to check visually, use playwright, screenshot a page, see or look at the design yourself, or verify a layout on desktop and mobile widths.
+argument-hint: <url> [--viewport WxH] [--full-page] [--selector <css>]
+---
+
+## Overview
+
+Take a screenshot of a running page and `Read` it into context so you can see the rendered result yourself — for design review, responsive checks (desktop + mobile widths), and confirming a layout fix actually looks right. This skill returns an **image**, not page data.
+
+## Engine selection (handled by the tool)
+
+The bundled tool picks the best available local engine automatically:
+
+1. **System `playwright-cli`** (Microsoft's stateful agent CLI) — used when it is on `PATH` and no exact viewport/full-page is requested (its `screenshot` command can't set those).
+2. **PAL-installed Playwright, launched via Node** — the cross-platform-safe path (Playwright's Chromium hangs under Bun on Windows). Honors `--viewport`, `--full-page`, and `--selector` precisely.
+
+If neither engine is usable, the tool prints `NO_PLAYWRIGHT_CLI` and exits non-zero — only then use the **Playwright MCP** (tier 3) in step 4.
+
+## Workflow
+
+1. Resolve the URL. If it's a local app, make sure the dev server is already running first.
+2. Run the tool (it prints the absolute PNG path as its last stdout line):
+
+   ```bash
+   node --experimental-strip-types ~/.pal/skills/playwright/tools/shot.ts <url> \
+     [--viewport 1440x900] [--full-page] [--selector "<css>"] [-o <out.png>]
+   ```
+
+3. `Read` the printed path so the screenshot enters your context. For a responsive check, run once per width (e.g. `--viewport 1440x900` then `--viewport 390x844`) and Read each.
+4. If the tool exits with `NO_PLAYWRIGHT_CLI`:
+   - If Playwright MCP tools (`mcp__playwright__browser_*`) are available: `browser_navigate` to the URL, `browser_take_screenshot` to a file, then `Read` it.
+   - Otherwise, tell the user Playwright isn't installed and suggest running `pal cli install`.
+
+## Output format
+
+The screenshot image (via `Read`) plus one line stating the URL and viewport captured. Add a review only if the caller asked you to assess the design.
+
+## When to use
+
+- "check visually", "use playwright", "screenshot this", "see/look at the design yourself", "does this look right", desktop/mobile layout verification.
+
+## Do NOT use
+
+- To scrape page text or DOM data — fetch the page directly instead; this returns an image.
+- To measure computed styles, element sizes, or horizontal overflow — use the Playwright MCP `browser_evaluate` for metrics; this skill does not return numbers.

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

@@ -0,0 +1,61 @@
+// Pure, side-effect-free helpers for the playwright skill tool.
+// Kept separate from shot.ts so they can be unit-tested without launching a browser.
+
+export type ShotOptions = {
+  url: string;
+  out: string;
+  viewport?: { width: number; height: number };
+  fullPage: boolean;
+  selector?: string;
+  waitMs?: number;
+};
+
+const USAGE =
+  "usage: shot.ts <url> [-o <file>] [--viewport WxH] [--full-page] [--selector <css>] [--wait <ms>]";
+
+export function parseArgs(argv: string[]): ShotOptions {
+  let url = "";
+  let out = "";
+  let viewport: ShotOptions["viewport"];
+  let fullPage = false;
+  let selector: string | undefined;
+  let waitMs: number | undefined;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-o" || a === "--out") out = argv[++i] ?? "";
+    else if (a === "--viewport") {
+      const m = /^(\d+)[x,](\d+)$/.exec(argv[++i] ?? "");
+      if (!m) throw new Error("--viewport expects WxH, e.g. 1440x900");
+      viewport = { width: Number(m[1]), height: Number(m[2]) };
+    } else if (a === "--full-page") fullPage = true;
+    else if (a === "--selector") selector = argv[++i];
+    else if (a === "--wait") {
+      const n = Number(argv[++i]);
+      if (!Number.isFinite(n)) throw new Error("--wait expects a number of milliseconds");
+      waitMs = n;
+    } else if (!a.startsWith("-") && !url) url = a;
+    else throw new Error(`unknown argument: ${a}\n${USAGE}`);
+  }
+
+  if (!url) throw new Error(`a URL is required\n${USAGE}`);
+  return { url, out, viewport, fullPage, selector, waitMs };
+}
+
+export type Tier = "cli" | "node";
+
+/**
+ * Decide which local engine to use. `playwright-cli` (Microsoft's stateful agent CLI)
+ * is preferred when present, but its `screenshot` command cannot set a viewport or
+ * capture full-page — so any request that needs exact size/full-page falls to the
+ * Node-launched PAL Playwright, which honors them precisely.
+ */
+export function chooseTier(opts: {
+  cliAvailable: boolean;
+  viewport?: unknown;
+  fullPage?: boolean;
+}): Tier {
+  if (!opts.cliAvailable) return "node";
+  if (opts.viewport || opts.fullPage) return "node";
+  return "cli";
+}

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

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// playwright skill tool: capture a screenshot of a URL and print its absolute path.
+//
+// Engine selection (see chooseTier):
+//   Tier 1 — system `playwright-cli` binary (Microsoft's stateful agent CLI), when on
+//            PATH and no exact viewport/full-page is requested.
+//   Tier 2 — PAL-installed Playwright, launched via Node. (Playwright's chromium.launch
+//            hangs under Bun on Windows — the same Node exception create-pdf relies on.)
+// If neither engine works, prints NO_PLAYWRIGHT_CLI on stderr and exits non-zero so the
+// caller (SKILL.md) can fall back to the Playwright MCP.
+//
+// Run with Node:
+//   node --experimental-strip-types ~/.pal/skills/playwright/tools/shot.ts <url> [opts]
+
+import { spawnSync } from "node:child_process";
+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";
+
+function playwrightCliAvailable(): boolean {
+  try {
+    return spawnSync("playwright-cli", ["--version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+
+function runViaCli(opts: ShotOptions, out: string): boolean {
+  // 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.
+// "error" = the engine ran but the page/screenshot failed → a real error, not an MCP case.
+type NodeResult = "ok" | "unavailable" | "error";
+
+async function runViaNode(opts: ShotOptions, out: string): Promise<NodeResult> {
+  let chromium: typeof import("playwright").chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    return "unavailable"; // package not resolvable
+  }
+
+  let browser: Awaited<ReturnType<typeof chromium.launch>>;
+  try {
+    browser = await chromium.launch();
+  } catch (e) {
+    console.error(`chromium launch failed: ${(e as Error).message}`);
+    return "unavailable"; // browser not installed / can't launch
+  }
+
+  try {
+    const page = await browser.newPage(opts.viewport ? { viewport: opts.viewport } : {});
+    await page.goto(opts.url, { waitUntil: "networkidle" });
+    if (opts.waitMs) await page.waitForTimeout(opts.waitMs);
+    if (opts.selector) await page.locator(opts.selector).screenshot({ path: out });
+    else await page.screenshot({ path: out, fullPage: opts.fullPage });
+    return existsSync(out) ? "ok" : "error";
+  } catch (e) {
+    console.error(`screenshot failed: ${(e as Error).message}`);
+    return "error";
+  } finally {
+    await browser.close();
+  }
+}
+
+async function main(): Promise<void> {
+  let opts: ShotOptions;
+  try {
+    opts = parseArgs(process.argv.slice(2));
+  } catch (e) {
+    console.error((e as Error).message);
+    process.exit(2);
+  }
+
+  const out = opts.out ? resolve(opts.out) : join(tmpdir(), `pal-shot-${Date.now()}.png`);
+  const tier = chooseTier({
+    cliAvailable: playwrightCliAvailable(),
+    viewport: opts.viewport,
+    fullPage: opts.fullPage,
+  });
+
+  if (tier === "cli" && runViaCli(opts, out)) {
+    console.log(out);
+    return;
+  }
+
+  const result = await runViaNode(opts, out);
+  if (result === "ok") {
+    console.log(out);
+    return;
+  }
+  if (result === "unavailable") {
+    console.error("NO_PLAYWRIGHT_CLI");
+    process.exit(3); // no local engine → caller falls back to Playwright MCP
+  }
+  process.exit(1); // engine ran but the capture failed — a real error, not an MCP case
+}
+
+await main();

package/package.json

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

package/src/cli/index.ts

@@ -16,6 +16,7 @@
  *   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
  */
 
 import { spawnSync } from "node:child_process";
@@ -192,6 +193,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 +241,7 @@ 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
 
   Environment:
     PAL_HOME              Override user state directory (default: ~/.pal or repo root)

package/src/cli/skill.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+
+import { linkPersonalSkill, log } from "../targets/lib";
+
+export async function runSkill(args: string[]): Promise<number> {
+  const [sub, name] = args;
+
+  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 <name>");
+  return 1;
+}

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 {