privateer-agent 0.1.0 → 0.2.1

package/README.md

@@ -12,15 +12,25 @@
   <a href="https://github.com/privateer-agent/privateer-agent/actions/workflows/ci.yml">
     <img src="https://github.com/privateer-agent/privateer-agent/actions/workflows/ci.yml/badge.svg" alt="CI" />
   </a>
+  <a href="https://www.npmjs.com/package/privateer-agent">
+    <img src="https://img.shields.io/npm/v/privateer-agent" alt="npm" />
+  </a>
   <img src="https://img.shields.io/badge/node-%E2%89%A520-brightgreen" alt="Node >= 20" />
   <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License" />
   <img src="https://img.shields.io/badge/providers-OpenRouter%20·%20Anthropic%20·%20OpenAI%20·%20Ollama%20·%20NEAR%20AI-5b8def" alt="Providers" />
   <img src="https://img.shields.io/badge/built%20on-Vercel%20AI%20SDK-black" alt="Vercel AI SDK" />
 </p>
 
+```bash
+curl -fsSL https://privateer.pro/install.sh | sh    # installs the `privateer` command
+npx privateer-agent                                 # or run it instantly, nothing installed
+```
+
 Switch between **OpenRouter**, **Anthropic**, **OpenAI**, local **Ollama**, and **NEAR AI**
 (private, attestable inference) with one command. Built on the Vercel AI SDK, so tool-calling
 and streaming work identically across every provider — no model lock-in, no separate code paths.
+MCP servers, Claude Code-compatible skills, scheduled routines, and approval from your phone
+included.
 
 <p align="center">
   <img src="docs/screenshot.png" alt="Privateer running in the terminal" width="820" />
@@ -30,63 +40,61 @@ and streaming work identically across every provider — no model lock-in, no se
 
 - **No lock-in.** Point it at a frontier model today and a local Ollama model tomorrow —
   `/model` swaps mid-session. Your config, commands, and agents come along for the ride.
+- **No API key required.** Bring your own key (BYOK) from any supported provider, run
+  keyless against a local Ollama — or `/login` to bill a Privateer account instead.
 - **The agent UX you already know.** Plan mode, checkpoint/rewind, a modal prompt, slash
   commands, sub-agents, and project memory — but vendor-neutral.
 - **Genuinely extensible.** MCP servers, lifecycle hooks, custom commands, output styles,
-  and sub-agents are all just files under `.privateer/`. No plugins to compile.
+  sub-agents, and skills are all just files under `.privateer/`. No plugins to compile.
 - **Zero binary deps.** The file/search/shell tools are pure Node — nothing to install
   beyond `node`.
 
 ## Highlights
 
+- **MCP servers** (local stdio + remote HTTP/SSE, with interactive OAuth), lifecycle
+  **hooks**, and **custom sub-agents**
+- **Claude Code-compatible skills** — published Agent Skills drop in unchanged; install
+  from GitHub with `/skills install owner/repo`
+- **Scheduled routines** — a daemon runs approved tasks unattended, cron or one-off
+- **Approve it from your phone** — link the terminal to the Privateer app with
+  `/remote-access` (off by default) and Allow/Deny every action remotely
+- **Zero-Data-Retention surfacing** for OpenRouter: a status-bar shield colors the selected
+  model's retention posture, and `/zdr` pins routing to zero-retention endpoints
+- **Private, verifiable inference** via NEAR AI: every model runs in a TEE, a `⛉ TEE` status
+  shield reflects the live attestation, and `/verify` fetches the attestation report (validate
+  the raw quote chains with the NEAR Cloud Verifier for full cryptographic proof)
+- **Plan mode** (read-only → present a plan → approve), **checkpoint/rewind** of
+  conversation and files
 - A modal prompt with `/` command and `@` file autocomplete, `!` shell passthrough,
   `#` memory append, input history, optional **vim** mode, and **ctrl-r** history search
 - Layered `settings.json` (user → project → local → managed), **custom slash commands**
   and **output styles** as markdown files
-- **Plan mode** (read-only → present a plan → approve), **checkpoint/rewind** of
-  conversation and files
-- Extensible: **MCP servers** (local stdio + remote HTTP/SSE, with interactive OAuth),
-  lifecycle **hooks**, and **custom sub-agents**
 - Background shells, bounded parallel sub-agents, thinking display, structured compaction,
   and image attachment for vision-capable models
-- **Zero-Data-Retention surfacing** for OpenRouter: a status-bar shield colors the selected
-  model's retention posture, and `/zdr` pins routing to zero-retention endpoints
-- **Private, verifiable inference** via NEAR AI: every model runs in a TEE, a `⛉ TEE` status
-  shield reflects the live attestation, and `/verify` fetches the attestation report (validate
-  the raw quote chains with the NEAR Cloud Verifier for full cryptographic proof)
 
 ## Quickstart
 
 ```bash
-npx privateer-agent                     # zero-install, runs the latest
-```
-
-Or install the `privateer` command on your PATH:
-
-```bash
-npm install -g privateer-agent          # then just run: privateer
-# or, the one-liner installer (checks Node, then installs):
-curl -fsSL https://privateer.pro/install.sh | sh
-```
-
-```bash
-export OPENROUTER_API_KEY=sk-or-...     # one provider is enough — or run /login
-privateer                               # launches the interactive TUI
+curl -fsSL https://privateer.pro/install.sh | sh    # or: npm install -g privateer-agent
+export OPENROUTER_API_KEY=sk-or-...                 # one provider is enough — or skip and run /login
+privateer                                           # launches the interactive TUI
 ```
 
 First run walks you through picking a provider and default model. From there, just type.
+(No install at all: `npx privateer-agent`.)
 
 ## Contents
 
-- [Requirements](#requirements) · [Install](#install) · [Configure a provider](#configure-a-provider) · [Model routing](#model-routing) · [Data retention (ZDR)](#data-retention-zdr) · [Private inference (NEAR AI)](#private-inference-near-ai) · [Usage](#usage)
+- [Requirements](#requirements) · [Install](#install) · [Configure a provider](#configure-a-provider) · [Model routing](#model-routing) · [Data retention (ZDR)](#data-retention-zdr) · [Private inference (NEAR AI)](#private-inference-near-ai) · [Privateer account](#privateer-account-billed-inference--what-it-sees) · [Usage](#usage)
 - [The prompt](#the-prompt) · [Slash commands](#slash-commands) · [Tools](#tools)
 - [Customize & extend](#customize--extend) · [Permission modes](#permission-modes) · [Project context](#project-context)
-- [Develop](#develop) · [Caveats](#caveats) · [Docs](#docs) · [License](#license)
+- [How it compares](#how-it-compares) · [Develop](#develop) · [Caveats](#caveats) · [Docs](#docs) · [License](#license)
 
 ## Requirements
 
-- Node.js ≥ 20
-- An API key for at least one provider (or a local Ollama install)
+- macOS or Linux
+- Node.js ≥ 20 (pure Node, zero binary dependencies)
+- An API key for at least one provider — or a local Ollama install, or a Privateer account (`/login`)
 
 ## Install
 
@@ -352,14 +360,19 @@ Built-ins (plus any custom commands you add):
 | Command | |
 |---|---|
 | `/help` `/doctor` `/config` | help, diagnostics, resolved settings layers |
-| `/model [spec]` `/provider` `/login` | choose a model, list providers, re-run onboarding |
+| `/model [spec]` `/provider` `/keys` | choose a model, list providers, manage API keys |
+| `/login` `/logout` | sign a Privateer account in/out (see [Privateer account](#privateer-account-billed-inference--what-it-sees)) |
+| `/remote-access [on\|off\|status]` | link this terminal to the Privateer app for phone approval (off by default) |
 | `/permissions [mode]` `/cost` `/context` | permission mode, token usage, context window |
-| `/init` `/memory` | write/show `PRIVATEER.md` |
+| `/init` `/memory` `/todo` | write/show `PRIVATEER.md`; show the task list |
 | `/agents` `/mcp [logout]` `/hooks` | inspect sub-agents; MCP status / clear OAuth; hooks |
+| `/skills [list\|info\|install\|remove]` | manage skills (see [Customize & extend](#customize--extend)) |
+| `/routine [list\|pause\|resume\|rm\|run]` | manage scheduled routines |
 | `/output-style [name]` `/vim` `/verbose` | persona, modal editing, full tool output |
 | `/zdr` | toggle OpenRouter zero-data-retention enforcement (see [Data retention](#data-retention-zdr)) |
 | `/verify` | fetch the NEAR AI TEE attestation for the current model (see [Private inference](#private-inference-near-ai)) |
 | `/rewind` `/compact` `/clear` `/export` | restore a checkpoint, compact, clear, save transcript |
+| `/resume` `/sessions` | pick up an earlier session in this directory |
 | `/exit` | quit |
 
 - `/model` — open a picker of each provider's live models (or `/model provider:id` to set one directly).
@@ -392,6 +405,14 @@ Everything below is optional and lives under `.privateer/` (project) or `~/.priv
   Switch with `/output-style <name>` (or `default`).
 - **Sub-agents** — `.privateer/agents/<name>.md` with frontmatter (`description`, `tools`,
   `model`). Invoke via the `task` tool's `subagent_type`; `/agents` lists them.
+- **Skills** — `.privateer/skills/<name>/SKILL.md` (frontmatter `name`/`description` +
+  instruction body, plus any bundled `scripts/`/`references/` files). The format is
+  Claude Code-compatible, so published Agent Skills drop in unchanged. The agent sees a
+  catalog of names and descriptions and loads a skill's full instructions on demand via
+  the `skill` tool; `/skill-name` invokes one explicitly. Manage with `/skills`
+  (`list`, `info <name>`, `install <owner/repo[/path]> [--project] [--all] [--force]`,
+  `remove <name>`) — install fetches from GitHub with a shallow clone and never executes
+  anything it downloads.
 - **Hooks** — a `hooks` section in `settings.json` runs shell commands on `PreToolUse`,
   `PostToolUse`, `UserPromptSubmit`, and `Stop`. A hook blocks by exiting `2` or printing
   `{"decision":"block"}`; `UserPromptSubmit` can inject `additionalContext`. `/hooks` lists them.
@@ -414,6 +435,13 @@ Everything below is optional and lives under `.privateer/` (project) or `~/.priv
     }
   }
   ```
+- **Routines** — saved tasks the scheduler daemon (`privateer daemon --detach`) runs
+  unattended, recurring (cron) or one-off. Ask the agent ("summarize world news every
+  morning") and approve; manage with `/routine` (list/pause/resume/rm/run). Runs use a safe
+  read/web toolset by default; a routine's `tools` list can also grant specific MCP tools
+  (`server__tool` or `server__*`) — flagged at approval, since they then run with no one
+  watching. See the [Sheet → WhatsApp recipe](docs/recipes/sheet-to-whatsapp.md) for a
+  full business automation built this way.
 - **Status line** — set `statusLine` to a shell command; it receives session JSON on stdin
   and its stdout becomes the status line.
 
@@ -422,18 +450,42 @@ Everything below is optional and lives under `.privateer/` (project) or `~/.priv
 | Mode | Behavior |
 |---|---|
 | `default` | prompt before edits and shell commands |
-| `acceptEdits` | auto-approve file edits; still prompt for other shell commands (the default) |
+| `acceptEdits` | auto-approve file edits; still prompt for shell commands |
 | `bypass` | no prompts (also `--dangerously-skip-permissions` or `--no-quarter`) |
 | `plan` | read-only; the agent presents a plan, then you approve to leave plan mode |
 
-At an approval prompt: **y** allow once · **a** always · **n** deny. In plan mode, after the
-agent presents its plan: **a** approve and exit plan mode · **k** keep planning.
+Out of the box the mode is **`acceptEdits`** (naming is a nod to convention: the mode
+called `default` prompts on everything, but isn't the shipped default). Edits are still
+checkpointed, so `/rewind` undoes them; prefer prompting on every edit? Run
+`/permissions default` once — it persists. At an approval prompt: **y** allow once ·
+**a** always · **n** deny. In plan mode, after the agent presents its plan: **a** approve
+and exit plan mode · **k** keep planning.
 
 ## Project context
 
 Create a `PRIVATEER.md` in your repo (via `/init`) to give the agent standing
 context — conventions, architecture notes, anything it should always know.
 
+## How it compares
+
+There are excellent terminal coding agents already. What this one does differently:
+
+- **Provider-agnostic by construction, not adaptation.** One agent loop over the Vercel AI
+  SDK; OpenRouter, Anthropic, OpenAI, local Ollama, and NEAR AI are interchangeable at
+  `/model` time, including mid-session. No vendor's models are privileged.
+- **Retention posture is a UI element.** ZDR status is visible before you send and
+  enforceable per request (`/zdr`); TEE inference is attestable (`/verify`). Most tools
+  leave this to the provider's terms-of-service page.
+- **Phone approval.** `/remote-access` relays each proposed action to the Privateer app
+  for Allow/Deny while execution stays on your machine — useful for long agent runs you
+  want to supervise from anywhere.
+- **Interop over ecosystem.** Skills use the Agent Skills format, so Claude Code skills
+  drop in unchanged; MCP covers tools. The goal is to reuse what exists, not grow a
+  parallel plugin world.
+
+And, honestly, what it doesn't have: the maturity of the incumbents. It's a young
+codebase — see [Caveats](#caveats) for the sharp edges we know about.
+
 ## Develop
 
 ```bash
@@ -467,6 +519,7 @@ deliberately simplified for now:
 ## Docs
 
 - [Architecture](docs/ARCHITECTURE.md) — how the provider layer, agent loop, tools, and permissions fit together
+- [Recipe: Sheet → WhatsApp](docs/recipes/sheet-to-whatsapp.md) — an unattended routine + MCP servers messaging new spreadsheet rows
 - [Brand assets](brand/README.md) — the logo and icon set
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "privateer-agent",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Privateer — a provider-agnostic terminal coding agent. Bring your own model (OpenRouter, Anthropic, OpenAI, Ollama, NEAR AI).",
   "type": "module",
   "license": "MIT",

package/src/auth/privateer.ts

@@ -145,6 +145,32 @@ function tryChmod(path: string, mode: number): void {
   }
 }
 
+// ── Session-expiry notification ──────────────────────────────────────────────
+// Fired when the machine login is invalidated server-side: the parent refresh
+// token's TTL lapsed (14 days for email logins, 60 for wallet — each session
+// spawn slides it forward, so this means the machine sat unused that long), or
+// it was revoked (from the app's Linked Devices, or by reuse detection).
+// Without a listener the credentials are wiped silently and Privateer just
+// stops working; the UI subscribes to announce the sign-out prominently.
+
+type SessionExpiredListener = () => void;
+const _expiredListeners = new Set<SessionExpiredListener>();
+
+export function onSessionExpired(listener: SessionExpiredListener): () => void {
+  _expiredListeners.add(listener);
+  return () => _expiredListeners.delete(listener);
+}
+
+function notifySessionExpired(): void {
+  for (const listener of _expiredListeners) {
+    try {
+      listener();
+    } catch {
+      /* a failing listener must not break the auth path */
+    }
+  }
+}
+
 // ── Device authorization flow ────────────────────────────────────────────────
 
 export interface DeviceCode {
@@ -271,7 +297,10 @@ async function spawnChildSession(): Promise<ChildSession> {
   });
   if (!res.ok) {
     // Parent refresh token invalid/expired → the machine login is gone.
-    if (res.status === 401) clearCredentials();
+    if (res.status === 401) {
+      clearCredentials();
+      notifySessionExpired();
+    }
     throw new Error("Your Privateer session expired. Run /login to sign in again.");
   }
   const { accessToken, refreshToken } = (await res.json()) as ChildSession;
@@ -279,6 +308,22 @@ async function spawnChildSession(): Promise<ChildSession> {
   return _child;
 }
 
+/**
+ * Eagerly spawn this terminal's child session at startup so an expired machine
+ * login is announced (via onSessionExpired) at launch rather than surfacing as
+ * an inference error on the first prompt of the day. Best effort: transient
+ * network failures stay silent here — the first real request retries the spawn
+ * and reports through the normal error path.
+ */
+export async function warmSession(): Promise<void> {
+  if (!hasCredentials()) return;
+  try {
+    await ensureChildSession();
+  } catch {
+    /* expiry is announced via onSessionExpired; other failures retry on use */
+  }
+}
+
 // Ensure a child session exists, de-duping concurrent spawns within this process.
 function ensureChildSession(): Promise<ChildSession> {
   if (_child) return Promise.resolve(_child);
@@ -363,6 +408,31 @@ export async function apiRequest(path: string, init: RequestInit = {}): Promise<
   return authedFetch(`${base}${path}`, init);
 }
 
+/**
+ * Best-effort revoke of THIS terminal's child session on exit, so the terminal
+ * disappears from the app's Linked Devices list immediately instead of
+ * lingering until its access-token rows expire (24h server-side).
+ *
+ * Deliberately NOT authedFetch: that would spawn/refresh a session just to kill
+ * it. If no child was ever spawned (e.g. BYO-key run), there's nothing to do.
+ * Bounded by a short timeout — exit must never hang on a slow network — and all
+ * failures are swallowed; the server's TTL remains the fallback.
+ */
+export async function revokeChildSession(timeoutMs = 1500): Promise<void> {
+  const child = _child;
+  if (!child) return;
+  _child = null; // never reuse a session we've asked the server to revoke
+  try {
+    await fetch(`${serverBaseUrl()}/auth/session/current`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${child.accessToken}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    /* best effort — the session expires server-side regardless */
+  }
+}
+
 // ── Logout ───────────────────────────────────────────────────────────────────
 
 /**

package/src/commands/custom.ts

@@ -15,23 +15,71 @@ export interface CustomCommand {
   scope: "project" | "user";
 }
 
-// Minimal YAML-ish frontmatter: a leading `---` block of `key: value` lines.
+// Minimal YAML-ish frontmatter: a leading `---` block of `key: value` lines. Values
+// may be quoted, continue onto indented lines, or use block scalars (`key: |` / `key: >`)
+// — enough for real-world command/agent/skill files without a YAML dependency.
 export function parseFrontmatter(raw: string): { meta: Record<string, string>; body: string } {
   const lines = raw.split("\n");
   if (lines[0]?.trim() !== "---") return { meta: {}, body: raw };
   const meta: Record<string, string> = {};
   let i = 1;
+  let lastKey: string | undefined;
   for (; i < lines.length; i++) {
-    if (lines[i].trim() === "---") {
+    const line = lines[i];
+    if (line.trim() === "---") {
       i++;
       break;
     }
-    const m = lines[i].match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
-    if (m) meta[m[1].toLowerCase()] = m[2].trim();
+    const m = line.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+    if (m) {
+      const key = m[1].toLowerCase();
+      const val = m[2].trim();
+      const block = /^([|>])[+-]?$/.exec(val);
+      if (block) {
+        // Block scalar: consume the following blank or more-indented lines. Literal
+        // (|) keeps line breaks; folded (>) joins lines with spaces.
+        const parts: string[] = [];
+        let indent = 0;
+        while (i + 1 < lines.length) {
+          const next = lines[i + 1];
+          const blank = next.trim() === "";
+          if (!blank && !/^[ \t]/.test(next)) break;
+          i++;
+          if (blank) {
+            parts.push("");
+            continue;
+          }
+          const lead = next.match(/^[ \t]*/)![0].length;
+          if (!indent) indent = lead;
+          parts.push(next.slice(Math.min(indent, lead)));
+        }
+        meta[key] =
+          block[1] === "|"
+            ? parts.join("\n").replace(/\s+$/, "")
+            : parts
+                .map((p) => p.trim())
+                .filter(Boolean)
+                .join(" ");
+      } else {
+        meta[key] = unquote(val);
+      }
+      lastKey = key;
+      continue;
+    }
+    // An indented non-empty line after `key: value` continues that value.
+    if (lastKey && /^[ \t]/.test(line) && line.trim() !== "") {
+      meta[lastKey] = `${meta[lastKey]} ${line.trim()}`.trim();
+    }
   }
   return { meta, body: lines.slice(i).join("\n").replace(/^\n+/, "") };
 }
 
+// Strip one pair of matching surrounding quotes from a scalar value.
+function unquote(v: string): string {
+  const m = /^"(.*)"$/.exec(v) ?? /^'(.*)'$/.exec(v);
+  return m ? m[1] : v;
+}
+
 function loadFromDir(dir: string, scope: "project" | "user"): CustomCommand[] {
   if (!existsSync(dir)) return [];
   const out: CustomCommand[] = [];

package/src/commands/registry.ts

@@ -6,6 +6,7 @@ import { configLayers } from "../config/load.ts";
 import { expandCommand, type CustomCommand } from "./custom.ts";
 import { loadOutputStyles } from "../context/outputStyles.ts";
 import { loadAgents } from "../agents/loader.ts";
+import { loadSkills, type SkillDefinition } from "../skills/loader.ts";
 import { loadHooks } from "../hooks/engine.ts";
 import { configuredProviders, parseModelSpec } from "../providers/resolve.ts";
 import { currentUser, serverBaseUrl } from "../auth/privateer.ts";
@@ -56,7 +57,12 @@ export type CommandResult =
   // Sign out of the Privateer account on this terminal.
   | { type: "privateerLogout" }
   // Toggle remote access (let the Privateer app drive this terminal). on=true/false; null=show status.
-  | { type: "remoteAccess"; on: boolean | null };
+  | { type: "remoteAccess"; on: boolean | null }
+  // Manage routines via the daemon (resolved in the App over IPC).
+  // action defaults to "list"; arg is the routine name/id for the targeted actions.
+  | { type: "routine"; action: "list" | "pause" | "resume" | "remove" | "run"; arg?: string }
+  // Install or remove an agent skill (async fetch/fs work, resolved by the App).
+  | { type: "skillOp"; op: "install" | "remove"; arg: string; project?: boolean; all?: boolean; force?: boolean };
 
 export interface CommandContext {
   config: Config;
@@ -69,6 +75,7 @@ export interface CommandContext {
   cwd: string;
   todos: TodoItem[];
   customCommands?: CustomCommand[];
+  skills?: SkillDefinition[];
 }
 
 interface CommandDef {
@@ -86,9 +93,16 @@ const COMMANDS: CommandDef[] = [
       const custom = (ctx.customCommands ?? [])
         .map((c) => `  /${c.name.padEnd(11)} ${c.description}`)
         .join("\n");
+      const skills = (ctx.skills ?? [])
+        .map((s) => `  /${s.name.padEnd(11)} ${s.description.split("\n")[0]}`)
+        .join("\n");
       return {
         type: "notice",
-        text: "Commands:\n" + builtin + (custom ? "\n\nCustom commands:\n" + custom : ""),
+        text:
+          "Commands:\n" +
+          builtin +
+          (custom ? "\n\nCustom commands:\n" + custom : "") +
+          (skills ? "\n\nSkills:\n" + skills : ""),
       };
     },
   },
@@ -332,6 +346,28 @@ const COMMANDS: CommandDef[] = [
       return { type: "mcp" };
     },
   },
+  {
+    name: "routine",
+    summary: "routines: list, or `pause|resume|rm|run <name>`",
+    run: (args) => {
+      const [sub, ...rest] = args.trim().split(/\s+/).filter(Boolean);
+      const arg = rest.join(" ") || undefined;
+      switch (sub) {
+        case "pause":
+          return { type: "routine", action: "pause", arg };
+        case "resume":
+          return { type: "routine", action: "resume", arg };
+        case "rm":
+        case "remove":
+        case "delete":
+          return { type: "routine", action: "remove", arg };
+        case "run":
+          return { type: "routine", action: "run", arg };
+        default:
+          return { type: "routine", action: "list" };
+      }
+    },
+  },
   {
     name: "hooks",
     summary: "list configured lifecycle hooks",
@@ -371,6 +407,70 @@ const COMMANDS: CommandDef[] = [
       return { type: "notice", text: `Sub-agents:\n${lines.join("\n")}` };
     },
   },
+  {
+    name: "skills",
+    summary: "list agent skills, or install/remove one (install <src> | info | remove <name>)",
+    run: (args, ctx) => {
+      const parts = args.trim().split(/\s+/).filter(Boolean);
+      const flags = new Set(parts.filter((p) => p.startsWith("--")));
+      const words = parts.filter((p) => !p.startsWith("--"));
+      const sub = words[0] ?? "list";
+      const project = flags.has("--project");
+      switch (sub) {
+        case "list": {
+          const { skills, warnings } = loadSkills(ctx.cwd);
+          if (skills.length === 0 && warnings.length === 0) {
+            return {
+              type: "notice",
+              text:
+                "No skills installed. Add SKILL.md directories under .privateer/skills/, " +
+                "or install one with /skills install <owner/repo[/path]>.",
+            };
+          }
+          const lines = skills.map(
+            (s) => `  ${s.name} (${s.scope})\n    ${s.description.split("\n")[0]}`,
+          );
+          const warn = warnings.length ? `\n\nWarnings:\n${warnings.map((w) => `  ${w}`).join("\n")}` : "";
+          return { type: "notice", text: `Skills:\n${lines.join("\n")}${warn}` };
+        }
+        case "info": {
+          const name = words[1];
+          if (!name) return { type: "notice", tone: "error", text: "Usage: /skills info <name>" };
+          const skill = loadSkills(ctx.cwd).skills.find((s) => s.name === name);
+          if (!skill) return { type: "notice", tone: "error", text: `No skill "${name}". See /skills.` };
+          const head = skill.body.split("\n").slice(0, 30).join("\n");
+          const fields = [
+            `name: ${skill.name} (${skill.scope})`,
+            `dir: ${skill.dir}`,
+            skill.model ? `model: ${skill.model}` : null,
+            skill.allowedTools?.length ? `allowed-tools: ${skill.allowedTools.join(", ")}` : null,
+            `description: ${skill.description}`,
+          ].filter(Boolean);
+          return { type: "notice", text: `${fields.join("\n")}\n\n${head}` };
+        }
+        case "install": {
+          if (!words[1]) {
+            return {
+              type: "notice",
+              tone: "error",
+              text: "Usage: /skills install <owner/repo[/path] | github url> [--project] [--all] [--force]",
+            };
+          }
+          return { type: "skillOp", op: "install", arg: words[1], project, all: flags.has("--all"), force: flags.has("--force") };
+        }
+        case "remove": {
+          if (!words[1]) return { type: "notice", tone: "error", text: "Usage: /skills remove <name> [--project]" };
+          return { type: "skillOp", op: "remove", arg: words[1], project };
+        }
+        default:
+          return {
+            type: "notice",
+            tone: "error",
+            text: `Unknown subcommand "${sub}". Use /skills [list | info <name> | install <src> | remove <name>].`,
+          };
+      }
+    },
+  },
   {
     name: "compact",
     summary: "summarize older history to free up context",
@@ -480,9 +580,16 @@ export const COMMAND_LIST: { name: string; summary: string }[] = COMMANDS.map((c
   summary: c.summary,
 }));
 
-// Built-ins plus any custom commands, for autocomplete.
-export function commandList(custom: CustomCommand[] = []): { name: string; summary: string }[] {
-  return [...COMMAND_LIST, ...custom.map((c) => ({ name: c.name, summary: c.description }))];
+// Built-ins plus any custom commands and skills, for autocomplete.
+export function commandList(
+  custom: CustomCommand[] = [],
+  skills: SkillDefinition[] = [],
+): { name: string; summary: string }[] {
+  return [
+    ...COMMAND_LIST,
+    ...custom.map((c) => ({ name: c.name, summary: c.description })),
+    ...skills.map((s) => ({ name: s.name, summary: `skill — ${s.description.split("\n")[0]}` })),
+  ];
 }
 
 // Parse and run a "/command args" line. Returns null if not a slash command.
@@ -495,5 +602,17 @@ export function runCommand(raw: string, ctx: CommandContext): CommandResult | nu
   if (cmd) return cmd.run(args, ctx);
   const custom = ctx.customCommands?.find((c) => c.name === name);
   if (custom) return { type: "runPrompt", text: expandCommand(custom, args) };
+  // A skill name invokes the skill via the tool (not by inlining the body): the
+  // tool's execute is what unlocks reads of the skill's bundled files.
+  const skill = ctx.skills?.find((s) => s.name === name);
+  if (skill) {
+    const req = args.trim();
+    return {
+      type: "runPrompt",
+      text:
+        `Load the "${skill.name}" skill with the skill tool and follow its instructions` +
+        (req ? ` for this request: ${req}` : "."),
+    };
+  }
   return { type: "notice", tone: "error", text: `Unknown command "/${name}". Try /help.` };
 }