portable-agent-layer 0.46.0 → 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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.46.0",
+  "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 {