portable-agent-layer 0.57.1 → 0.59.0

package/assets/agents/skill-author.md

@@ -0,0 +1,54 @@
+---
+name: skill-author
+description: Authors a new personal PAL skill end-to-end — writes the SKILL.md (and any tools), links it into every installed agent, and runs the doctor. Invoked by the create-skill skill to delegate the creative authoring to a flagship model.
+
+claude:
+  tools: Bash, Read, Write, Edit, Grep, Glob
+  model: fable
+
+opencode:
+  mode: subagent
+  permission:
+    read: allow
+    write: allow
+    edit: allow
+    bash: allow
+
+cursor:
+  model: inherit
+  readonly: false
+  is_background: false
+---
+
+You author a single new personal skill for this user. You are handed a **skill name** and a **skill description**, and optionally hints about tooling or triggers.
+
+## Steps
+
+1. Read the authoring guide — it is the single source of truth for what a good skill is and the exact anatomy to follow:
+   ```bash
+   cat ~/.pal/skills/create-skill/authoring-guide.md
+   ```
+2. Validate the name: lowercase-kebab, no spaces, not colliding with an existing skill (check `~/.pal/skills/` and the active skill list). If it collides or is malformed, stop and report the conflict instead of overwriting.
+3. Create the skill and write its `SKILL.md`, populated per the guide's anatomy (frontmatter + Workflow + Output format + When to use):
+   ```bash
+   mkdir -p ~/.pal/skills/<name>
+   ```
+4. If the skill needs runtime tooling, scaffold a `tools/` subdir alongside `SKILL.md` and write the scripts there.
+5. Link the skill into every installed agent:
+   ```bash
+   pal cli skill link <name>
+   ```
+6. Run the doctor and fix every `✗` error it reports; weigh each `⚠`:
+   ```bash
+   pal cli skill doctor <name>
+   ```
+   A name/folder mismatch or a misnamed file makes the skill silently fail to load — never skip this.
+7. Hand-check what the doctor can't: trigger clarity, step concreteness (every step has a verb and an object), output specification, and scope discipline (one skill, one job).
+
+## Output
+
+Return, concisely:
+- The path of the created `SKILL.md` (under `~/.pal/skills/<name>/`).
+- The agents it was linked into (from the `pal cli skill link` output).
+- The doctor's final result (errors resolved).
+- A 2-3 sentence summary of the trigger and workflow, and how to invoke it.

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

@@ -8,65 +8,28 @@ argument-hint: <skill name> <skill description>
 
 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.
 
-## What makes a good skill
+The quality rules and the exact skill anatomy live in one place — read them before writing anything:
 
-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.
-
-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: <what it does + WHEN to invoke>   # the dispatcher matches on this
-argument-hint: <args>                  # optional; how the user passes input
----
-
-## Overview / Workflow
-
-Numbered, concrete steps the assistant follows on invocation.
-
-## Output format
-
-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.
+```bash
+cat ~/.pal/skills/create-skill/authoring-guide.md
 ```
 
-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:
+1. Check whether a flagship authoring model is configured for the current agent:
    ```bash
-   pal cli skill doctor <name>
+   pal cli skill author-model
    ```
-   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.
+2. **If it prints a model** → delegate the authoring to the `skill-author` subagent. That subagent is preconfigured to run on that flagship model; hand it the skill name, description, and any trigger/tooling hints, and let it write the SKILL.md, scaffold tools, run `pal cli skill link`, and run the doctor. Relay its result.
+3. **If it prints nothing** → author the skill inline yourself:
+   - Read `authoring-guide.md` (above) and follow its anatomy.
+   - `mkdir -p ~/.pal/skills/<name>` and write `~/.pal/skills/<name>/SKILL.md`.
+   - If the skill needs runtime tooling, scaffold a `tools/` subdir and write the scripts there.
+   - Link it into every installed agent: `pal cli skill link <name>`.
+   - Run `pal cli skill doctor <name>` and fix every `✗`; weigh each `⚠`.
+   - Hand-check the items the doctor can't judge (see the guide's final section).
+
+Either path: validate the name first (lowercase-kebab, no spaces, not colliding with an existing skill in `~/.pal/skills/` or the active skill list), and confirm the trigger with the user if the description is ambiguous about *when* the skill should fire.
 
 ## Output format
 

package/assets/skills/create-skill/authoring-guide.md

@@ -0,0 +1,48 @@
+# Skill authoring guide
+
+The canonical rules for authoring a personal PAL skill. Both the `create-skill`
+dispatcher and the delegated `skill-author` subagent follow this file, so it is
+the single source of truth for skill quality.
+
+## What makes a good skill
+
+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.
+
+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.
+
+4. **Self-contained and portable.** Everything the skill needs lives inside its own folder — `SKILL.md` plus a `tools/` subdir for scripts and any reference files — so it travels intact on export/import. Don't reach into sibling skills or reference files outside the folder. Prefer `$HOME`/`~` or an env var over a hardcoded absolute path like `/Users/you/…` so the skill still works on another machine; `pal cli skill doctor` warns (never errors) on machine-specific absolute paths.
+
+A personal skill **may** contain this user's own context — their paths, project names, preferences, conventions. That is the point of a personal skill; portability (rule 4) is a preference, not a hard rule — a deliberate machine-specific mount is fine.
+
+## Skill anatomy
+
+```markdown
+---
+name: <slug>                           # the slash-command name; lowercase-kebab
+description: <what it does + WHEN to invoke>   # the dispatcher matches on this
+argument-hint: <args>                  # optional; how the user passes input
+---
+
+## Overview / Workflow
+
+Numbered, concrete steps the assistant follows on invocation.
+
+## Output format
+
+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.
+```
+
+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.
+
+## Hand-checks the doctor can't judge
+
+- **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.

package/package.json

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

package/src/cli/index.ts

@@ -262,6 +262,7 @@ function showHelp() {
                                             (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
+    pal cli skill author-model              Print the flagship model that authors skills for the active agent
     pal cli debug [on|off]                  Enable/disable verbose hook debug logging (persisted)
 
   Environment:

package/src/cli/skill.ts

@@ -5,9 +5,13 @@
  *                                 every installed agent so it is discoverable.
  *   pal cli skill doctor <name>   Evaluate ~/.pal/skills/<name>/ against the
  *                                 skill-authoring best practices.
+ *   pal cli skill author-model    Print the flagship model configured to author
+ *                                 skills for the active agent (empty if none).
  */
 
 import { resolve } from "node:path";
+import { getActiveAgent } from "../hooks/lib/agent";
+import { flagshipAuthorModel } from "../hooks/lib/models";
 import { palHome } from "../hooks/lib/paths";
 import { linkPersonalSkill, log } from "../targets/lib";
 import { formatReport, lintSkill } from "../tools/skill-doctor";
@@ -15,6 +19,12 @@ import { formatReport, lintSkill } from "../tools/skill-doctor";
 export async function runSkill(args: string[]): Promise<number> {
   const [sub, name] = args;
 
+  if (sub === "author-model") {
+    const model = flagshipAuthorModel(getActiveAgent());
+    if (model) console.log(model);
+    return 0;
+  }
+
   if (sub === "doctor") {
     if (!name) {
       log.error("Usage: pal cli skill doctor <name>");
@@ -50,6 +60,6 @@ export async function runSkill(args: string[]): Promise<number> {
     }
   }
 
-  log.error("Usage: pal cli skill <link|doctor> <name>");
+  log.error("Usage: pal cli skill <link|doctor|author-model> [name]");
   return 1;
 }

package/src/hooks/lib/agent.ts

@@ -11,7 +11,7 @@
  * vars are used as secondary fallbacks for environments that forward them.
  */
 
-type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode";
+export type AgentType = "claude" | "cursor" | "codex" | "copilot" | "opencode";
 
 const KNOWN_AGENTS: ReadonlySet<AgentType> = new Set([
   "claude",

package/src/hooks/lib/models.ts

@@ -2,8 +2,29 @@
  * Single source of truth for model IDs and pricing.
  */
 
+import type { AgentType } from "./agent";
+
 export const HAIKU_MODEL = "claude-haiku-4-5-20251001";
 export const SONNET_MODEL = "claude-sonnet-4-6";
+export const FABLE_MODEL = "claude-fable-5";
+
+/**
+ * Per-agent flagship model used to AUTHOR new skills (via `create-skill`).
+ *
+ * This is the single extension point for delegated skill authoring: an agent
+ * present here → `create-skill` spins up that agent's `skill-author` subagent on
+ * this model; an agent absent → `create-skill` authors inline. Add a provider by
+ * adding one entry (and a matching platform block in assets/agents/skill-author.md).
+ */
+export const FLAGSHIP_AUTHOR_MODEL: Partial<Record<AgentType, string>> = {
+  claude: FABLE_MODEL,
+  // codex: "gpt-5.5",   // enable once Codex ships a tool-capable flagship subagent
+};
+
+/** Flagship authoring model for an agent, or undefined if none is configured. */
+export function flagshipAuthorModel(agent: AgentType): string | undefined {
+  return FLAGSHIP_AUTHOR_MODEL[agent];
+}
 
 /** Pricing per million tokens (USD) — from https://platform.claude.com/docs/en/about-claude/pricing */
 export const MODEL_PRICING: Record<

package/src/tools/skill-doctor.ts

@@ -10,7 +10,7 @@
  */
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { basename, extname, relative, resolve } from "node:path";
 import { palHome } from "../hooks/lib/paths";
 
 type Level = "pass" | "warn" | "error";
@@ -41,6 +41,44 @@ const MAX_NAME = 64;
 const MAX_DESCRIPTION = 1024;
 const MAX_BODY_LINES = 500;
 
+/** File extensions worth scanning for hardcoded paths (SKILL.md + its scripts). */
+const SCANNABLE_EXT = new Set([".md", ".ts", ".js", ".mjs", ".cjs", ".sh", ".py"]);
+
+/** Machine/user-specific absolute paths that will not survive an export to
+ * another machine or user: POSIX home dirs and Windows user profiles. Portable
+ * forms ($HOME, ~, %USERPROFILE%, env vars) are deliberately not matched. */
+const ABSOLUTE_PATH_RE =
+  /(?:\/(?:Users|home)\/[A-Za-z0-9._-]+|\/root\/[A-Za-z0-9._-]|[A-Za-z]:\\Users\\[A-Za-z0-9._-]+)/;
+
+/** Collect SKILL.md and sibling script files, skipping vendored/VCS trees. */
+function collectSkillFiles(skillDir: string): string[] {
+  const out: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+      const full = resolve(dir, entry.name);
+      if (entry.isDirectory()) walk(full);
+      else if (entry.isFile() && SCANNABLE_EXT.has(extname(entry.name))) out.push(full);
+    }
+  };
+  walk(skillDir);
+  return out;
+}
+
+/** Find machine-specific absolute paths across a skill's files. */
+function findAbsolutePaths(skillDir: string): string[] {
+  const hits: string[] = [];
+  for (const file of collectSkillFiles(skillDir)) {
+    const rel = relative(skillDir, file).replaceAll("\\", "/");
+    const lines = readFileSync(file, "utf-8").split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const m = ABSOLUTE_PATH_RE.exec(lines[i]);
+      if (m) hits.push(`${rel}:${i + 1} → ${m[0]}`);
+    }
+  }
+  return hits;
+}
+
 /** Split a SKILL.md into frontmatter fields and body. */
 function parseSkill(content: string): ParsedSkill {
   const parts = content.split(/^---\s*$/m);
@@ -238,6 +276,23 @@ export function lintSkill(skillDir: string): DoctorReport {
     ? add("warn", "paths", "Windows-style backslash path found — use forward slashes")
     : add("pass", "paths", "forward-slash paths");
 
+  // ── machine-specific absolute paths (portability) ──
+  // A personal skill MAY legitimately hardcode a machine-specific path (e.g. a
+  // cloud-mount vault), so this is a warning, never an error — it flags paths
+  // that will not survive being exported to another machine or user.
+  const absHits = findAbsolutePaths(skillDir);
+  if (absHits.length > 0) {
+    const shown = absHits.slice(0, 3).join("; ");
+    const more = absHits.length > 3 ? ` (+${absHits.length - 3} more)` : "";
+    add(
+      "warn",
+      "paths.absolute",
+      `hardcoded absolute path(s) that won't be portable across machines: ${shown}${more} — prefer $HOME/~ or an env var, or ignore if this is an intentional machine-specific mount`
+    );
+  } else {
+    add("pass", "paths.absolute", "no machine-specific absolute 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 };