portable-agent-layer 0.57.0 → 0.58.0

package/assets/STATUSLINE.md

@@ -71,18 +71,22 @@ On Cursor, session cost and rate limits are usually absent from stdin — the sc
 
 ### On Windows
 
-1. Add to `~/.claude/settings.json`:
+The installer does this automatically. To wire it manually, copy `statusline.ps1` to
+`~/.claude/statusline.ps1` and add to `~/.claude/settings.json`:
 ```json
 {
   "statusLine": {
     "type": "command",
-    "command": "powershell -NoProfile -Command \"Get-Content -Raw | & 'C:\\path\\to\\statusline.ps1'\"",
+    "command": "powershell -NoProfile -ExecutionPolicy Bypass -File ~/.claude/statusline.ps1",
     "padding": 2
   }
 }
 ```
 
-Or copy `statusline.ps1` to `~/.claude/statusline.ps1` and reference it from settings.
+`-ExecutionPolicy Bypass` (which must precede `-File`) lets the unsigned script run under a
+`Restricted`/`AllSigned` machine policy — the common reason the status line silently fails to
+appear. It does **not** override a policy enforced via Group Policy (`MachinePolicy`/`UserPolicy`);
+run `Get-ExecutionPolicy -List` to check the scope, and if it's a GPO scope, that case needs IT.
 
 The statusline script is at: `portable-agent-layer/assets/statusline.ps1`
 
@@ -104,7 +108,7 @@ The statusline script is at: `portable-agent-layer/assets/statusline.ps1`
 ## Dependencies
 
 - **macOS/Linux:** `bash`, `jq`, `git` (for branch detection)
-- **Windows:** PowerShell 7+, `git` (for branch detection)
+- **Windows:** Windows PowerShell 5.1 (invoked as `powershell`; the script is 5.1-compatible) or PowerShell 7, `git` (for branch detection)
 
 ## Customization
 

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,46 @@
+# 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.
+
+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.
+```
+
+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.0",
+  "version": "0.58.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/targets/lib.ts

@@ -1042,7 +1042,7 @@ function statuslineCommand(target: StatuslineTarget): string {
       : "~/.cursor/statusline.sh";
   }
   return isPlatformWin32
-    ? "powershell -NoProfile -File ~/.claude/statusline.ps1"
+    ? "powershell -NoProfile -ExecutionPolicy Bypass -File ~/.claude/statusline.ps1"
     : "~/.claude/statusline.sh";
 }
 
@@ -1105,6 +1105,23 @@ export function removeStatusline(target: StatuslineTarget = "claude"): boolean {
   }
 }
 
+function isOldGetContentClaudeCommand(cmd: string): boolean {
+  return cmd.includes("Get-Content -Raw");
+}
+
+function isPalWindowsClaudeCommandMissingBypass(cmd: string): boolean {
+  return (
+    process.platform === "win32" &&
+    isPalStatuslineCommand(cmd, "claude") &&
+    cmd.includes("powershell") &&
+    !cmd.includes("-ExecutionPolicy Bypass")
+  );
+}
+
+function claudeStatuslineNeedsRefresh(cmd: string): boolean {
+  return isOldGetContentClaudeCommand(cmd) || isPalWindowsClaudeCommandMissingBypass(cmd);
+}
+
 /** Add statusLine config if not already present or if using an old broken command */
 export function addStatuslineConfig(
   settings: Record<string, unknown>,
@@ -1115,8 +1132,7 @@ export function addStatuslineConfig(
   if (statusLine && typeof statusLine === "object" && statusLine.command) {
     const cmd = statusLine.command as string;
     if (target === "claude") {
-      // Keep existing config unless it's the old broken Get-Content pattern
-      if (!cmd.includes("Get-Content -Raw")) {
+      if (!claudeStatuslineNeedsRefresh(cmd)) {
         return settings;
       }
     } else if (!isPalStatuslineCommand(cmd, "cursor")) {