@holt-os/holt 0.10.0 → 0.12.0

package/README.md

@@ -206,20 +206,37 @@ Wiki pages also participate in recall: each page is embedded and indexed like a
 
 A skill is a folder with a `SKILL.md`: YAML frontmatter (`name`, `description`) plus Markdown instructions. Same convention as agentskills.io and Claude Code, so skills are portable both ways. Skills are prompt text only; Holt never executes their contents.
 
-Holt looks in two places (workspace wins on a name clash): `./.holt/skills/` for this folder, `~/.holt/skills/` for every folder (`--global`).
+Holt looks in three places, in precedence order (workspace shadows global shadows builtin on a name clash): `./.holt/skills/` for this folder, `~/.holt/skills/` for every folder (`--global`), and a read-only set of **built-in skills** that ship inside Holt and are available in every folder out of the box.
 
 ```
 holt skill list                        list installed skills
 holt skill show <name>                 print a skill
 holt skill create <name> [--global]    scaffold a new skill
 holt skill search <query>              find skills in the registry
-holt skill add <src|name> [--global]   install from a git URL, path, or registry name
+holt skill add <src|name> [--global]   install from a git URL, git-url#subdir, path, or registry name
 holt skill publish [<name>]            prepare a skill for the registry (prints a PR entry)
 holt skill remove <name>               delete a skill
 ```
 
+A source may carry a `#<subdir>` suffix (split on the first `#`) that points at one skill folder inside a repo or path: `holt skill add https://github.com/holt-os/registry#skills/pm-prd`. The subdir is a path, relative to the source root, that contains a `SKILL.md`. This lets a single repo hold many skills (one monorepo), which is exactly how the community registry is laid out. The subdir is validated to stay inside the source (absolute paths and `..` traversal are refused), since a registry entry is remote-controlled. Without a `#`, behaviour is unchanged: Holt looks for a `SKILL.md` at the source root or in exactly one immediate subfolder.
+
 In chat, run one with `/skill <name> [your input]`. Available skills are also listed to the brain each turn, so it knows what it can be asked to follow.
 
+### Built-in skills
+
+Holt ships with a small, curated set of general-purpose skills, available in every folder with no setup. They are read-only (`holt skill remove` will not delete them); to change one, create a workspace or global skill with the same name and it takes over.
+
+- **summarize**: condense a document, article, transcript, or pasted text into its key points.
+- **explain**: explain a concept, error message, or piece of jargon in plain language.
+- **action-items**: pull decisions, tasks, and owners out of messy notes or a meeting transcript.
+- **brief**: a short briefing on the state of the current folder, using recalled memory plus your input.
+- **code-review**: review a file or a diff for correctness bugs, edge cases, and simplifications.
+- **explain-code**: walk through what a file or function does and how it fits into the wider system.
+- **commit**: draft a clear commit message from staged changes or a described change.
+- **plan**: break a goal into a concrete, ordered set of steps.
+- **rewrite**: tighten and clarify a piece of text without changing its meaning.
+- **decide**: weigh a decision and give a clear recommendation.
+
 ### Skill registry (`holt skill search` / `publish`)
 
 Beyond pasting URLs, Holt can discover and share skills through a **git-based registry**: a single JSON index living in a git repo. No server, no infra, in keeping with the rest of Holt.
@@ -241,7 +258,7 @@ The index is a JSON document:
 }
 ```
 
-`source` is anything `holt skill add` already accepts: a git URL (its `SKILL.md` may sit in one subfolder) or a local path. `tags` is optional. Only `name` and `source` are required per entry; malformed rows are skipped rather than failing the whole index.
+`source` is anything `holt skill add` already accepts: a git URL (its `SKILL.md` may sit in one subfolder), a local path, or either of those with a `#<subdir>` suffix pointing at one skill folder inside the repo. That last form lets one repo hold many skills, so the community registry can be a single monorepo (e.g. `"source": "https://github.com/holt-os/registry#skills/pm-prd"`). `tags` is optional. Only `name` and `source` are required per entry; malformed rows are skipped rather than failing the whole index.
 
 - **Find:** `holt skill search <query>` fetches the index and lists skills whose name, description, or tags match (case-insensitive substring, name matches first). An empty query lists everything. It prints name, author, description, and source.
 - **Install by name:** `holt skill add <name>` resolves the name in the registry to its `source`, then installs through the exact same clone/copy path as `holt skill add <url|path>`. A git URL or an existing local path is still installed directly, unchanged.

package/dist/cli.js

@@ -1032,9 +1032,15 @@ async function runApiBrain(brain, prompt, onChunk) {
 
 // src/skills.ts
 import { readFileSync as readFileSync6, readdirSync, existsSync as existsSync6, statSync as statSync2 } from "fs";
-import { join as join6 } from "path";
+import { join as join6, dirname as dirname2 } from "path";
+import { fileURLToPath } from "url";
+function builtinSkillsRoot() {
+  return join6(dirname2(fileURLToPath(import.meta.url)), "..", "skills");
+}
 function skillsRoot(scope) {
-  return scope === "workspace" ? join6(wsHoltDir(), "skills") : join6(GLOBAL_DIR, "skills");
+  if (scope === "workspace") return join6(wsHoltDir(), "skills");
+  if (scope === "builtin") return builtinSkillsRoot();
+  return join6(GLOBAL_DIR, "skills");
 }
 function sanitizeName(name) {
   return (name || "").trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "").replace(/-{2,}/g, "-");
@@ -1114,6 +1120,7 @@ function listScope(scope) {
 }
 function listSkills() {
   const byName = /* @__PURE__ */ new Map();
+  for (const s of listScope("builtin")) byName.set(s.name, s);
   for (const s of listScope("global")) byName.set(s.name, s);
   for (const s of listScope("workspace")) byName.set(s.name, s);
   return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
@@ -3695,14 +3702,14 @@ import {
   cpSync,
   mkdtempSync
 } from "fs";
-import { join as join12, resolve as resolve3 } from "path";
+import { join as join12, resolve as resolve3, sep, isAbsolute as isAbsolute3 } from "path";
 import { tmpdir } from "os";
 import { spawnSync as spawnSync2 } from "child_process";
 
 // src/registry.ts
 import { readFileSync as readFileSync12, writeFileSync as writeFileSync9, existsSync as existsSync11, mkdirSync as mkdirSync8, statSync as statSync4 } from "fs";
 import { join as join11, isAbsolute as isAbsolute2, resolve as resolve2 } from "path";
-import { pathToFileURL, fileURLToPath } from "url";
+import { pathToFileURL, fileURLToPath as fileURLToPath2 } from "url";
 var DEFAULT_REGISTRY_URL = "https://raw.githubusercontent.com/holt-os/registry/main/registry.json";
 var REGISTRY_REPO_URL = "https://github.com/holt-os/registry";
 var CACHE_TTL_MS = 60 * 60 * 1e3;
@@ -3767,7 +3774,7 @@ function writeCache(url, registry) {
 function localPathFor(loc) {
   if (loc.startsWith("file://")) {
     try {
-      return fileURLToPath(loc);
+      return fileURLToPath2(loc);
     } catch {
       return null;
     }
@@ -3859,7 +3866,7 @@ function usage() {
     "  holt skill show <name>              print a skill",
     "  holt skill create <name> [--global] scaffold a new skill",
     "  holt skill search <query>           find skills in the registry",
-    "  holt skill add <src|name> [--global] install from a git URL, path, or registry name",
+    "  holt skill add <src|name> [--global] install from a git URL, git-url#subdir, path, or registry name",
     "  holt skill publish [<name>]         prepare a skill for the registry (prints a PR entry)",
     "  holt skill remove <name>            delete a skill",
     "",
@@ -3895,6 +3902,20 @@ var SKILL_TEMPLATE = (name) => [
 function isGitUrl(s) {
   return s.includes("://") || s.endsWith(".git") || s.startsWith("git@");
 }
+function splitSubpath(source) {
+  const i = source.indexOf("#");
+  if (i === -1) return { base: source, subpath: "" };
+  return { base: source.slice(0, i), subpath: source.slice(i + 1) };
+}
+function resolveSubpathDir(fetched, subpath) {
+  if (isAbsolute3(subpath)) return null;
+  const segments = subpath.split(/[\\/]/);
+  if (segments.some((s) => s === "..")) return null;
+  const target = resolve3(fetched, subpath);
+  const root = resolve3(fetched);
+  if (target !== root && !target.startsWith(root + sep)) return null;
+  return target;
+}
 function findSkillDir(root) {
   if (existsSync12(join12(root, "SKILL.md"))) return root;
   let subs = [];
@@ -3921,14 +3942,15 @@ function cmdList() {
   }
   const nameW = Math.max(4, ...skills.map((s) => s.name.length));
   const scopeW = Math.max(5, ...skills.map((s) => s.scope.length));
-  console.log("\n" + c.accent("Skills") + c.dim("  (workspace shadows global on name clash)"));
+  console.log("\n" + c.accent("Skills") + c.dim("  (workspace shadows global shadows builtin on name clash)"));
   console.log(
     "  " + c.dim("name".padEnd(nameW)) + "  " + c.dim("scope".padEnd(scopeW)) + "  " + c.dim("description")
   );
   for (const s of skills) {
     const desc = s.description.length > 68 ? s.description.slice(0, 67) + "\u2026" : s.description;
+    const scopeCol = s.scope === "workspace" ? c.cyan(s.scope.padEnd(scopeW)) : s.scope === "builtin" ? c.accent(s.scope.padEnd(scopeW)) : c.dim(s.scope.padEnd(scopeW));
     console.log(
-      "  " + c.bold(s.name.padEnd(nameW)) + "  " + (s.scope === "workspace" ? c.cyan(s.scope.padEnd(scopeW)) : c.dim(s.scope.padEnd(scopeW))) + "  " + (desc || c.dim("(no description)"))
+      "  " + c.bold(s.name.padEnd(nameW)) + "  " + scopeCol + "  " + (desc || c.dim("(no description)"))
     );
   }
   console.log(c.dim("\n  holt skill show <name>   print a skill"));
@@ -3978,14 +4000,15 @@ function cmdCreate(name, global) {
   console.log(c.dim('  Edit it, then run it in chat with "/skill ' + clean + '".\n'));
 }
 function installFromSource(source, scope) {
+  const { base, subpath } = splitSubpath(source);
   let fetched = "";
   let tempDir = "";
   try {
-    if (isGitUrl(source)) {
+    if (isGitUrl(base)) {
       tempDir = mkdtempSync(join12(tmpdir(), "holt-skill-"));
       console.log(c.dim(`
-  Cloning ${source} ...`));
-      const res = spawnSync2("git", ["clone", "--depth", "1", source, tempDir], { stdio: "ignore" });
+  Cloning ${base} ...`));
+      const res = spawnSync2("git", ["clone", "--depth", "1", base, tempDir], { stdio: "ignore" });
       if (res.status !== 0) {
         console.error(c.red("  Clone failed. Check the URL and that git is installed.\n"));
         process.exitCode = 1;
@@ -3993,7 +4016,7 @@ function installFromSource(source, scope) {
       }
       fetched = tempDir;
     } else {
-      fetched = resolve3(source);
+      fetched = resolve3(base);
       if (!existsSync12(fetched)) {
         console.error(c.red(`
   No such path: ${fetched}
@@ -4002,9 +4025,31 @@ function installFromSource(source, scope) {
         return false;
       }
     }
-    const skillDir = findSkillDir(fetched);
+    let searchRoot = fetched;
+    if (subpath) {
+      const target = resolveSubpathDir(fetched, subpath);
+      if (!target) {
+        console.error(c.red(`
+  Refusing unsafe subpath "${subpath}": it must stay inside the source (no absolute or "..").
+`));
+        process.exitCode = 1;
+        return false;
+      }
+      if (!existsSync12(target) || !statSync5(target).isDirectory()) {
+        console.error(c.red(`
+  Subpath "${subpath}" does not exist in the source.
+`));
+        process.exitCode = 1;
+        return false;
+      }
+      searchRoot = target;
+    }
+    const skillDir = findSkillDir(searchRoot);
     if (!skillDir) {
-      console.error(c.red("\n  Could not find a SKILL.md at the source root or in a single subfolder.\n"));
+      const where = subpath ? `subpath "${subpath}"` : "the source root or in a single subfolder";
+      console.error(c.red(`
+  Could not find a SKILL.md at ${where}.
+`));
       process.exitCode = 1;
       return false;
     }
@@ -4048,11 +4093,12 @@ function installFromSource(source, scope) {
 }
 async function cmdAdd(source, global, refresh) {
   if (!source) {
-    console.log(c.dim("\n  Usage: holt skill add <git-url|path|name> [--global]\n"));
+    console.log(c.dim("\n  Usage: holt skill add <git-url|git-url#subdir|path|name> [--global]\n"));
     return;
   }
   const scope = global ? "global" : "workspace";
-  if (isGitUrl(source) || existsSync12(resolve3(source))) {
+  const { base } = splitSubpath(source);
+  if (isGitUrl(base) || existsSync12(resolve3(base))) {
     installFromSource(source, scope);
     return;
   }
@@ -4181,6 +4227,13 @@ async function cmdRemove(name, ask) {
   const globalDir = join12(skillsRoot("global"), clean);
   const target = existsSync12(wsDir) ? wsDir : existsSync12(globalDir) ? globalDir : "";
   if (!target) {
+    if (existsSync12(join12(skillsRoot("builtin"), clean))) {
+      console.error(c.red(`
+  "${clean}" is a built-in skill and cannot be removed; it ships inside Holt.`));
+      console.error(c.dim("  Override it instead: create a workspace or global skill with the same name.\n"));
+      process.exitCode = 1;
+      return;
+    }
     console.error(c.dim(`
   No skill named "${clean}" found.
 `));
@@ -4248,7 +4301,7 @@ async function skillCmd(sub, rest = []) {
 
 // src/commands/graph.ts
 import { writeFileSync as writeFileSync11, mkdirSync as mkdirSync10, existsSync as existsSync13 } from "fs";
-import { join as join14, dirname as dirname3, resolve as resolve4 } from "path";
+import { join as join14, dirname as dirname4, resolve as resolve4 } from "path";
 import { spawn as spawn4 } from "child_process";
 
 // src/communities.ts
@@ -5046,7 +5099,7 @@ function renderGraphHtml(graph2, meta) {
 
 // src/ingest.ts
 import { readdirSync as readdirSync4, readFileSync as readFileSync14, statSync as statSync6 } from "fs";
-import { join as join13, relative, sep, extname, dirname as dirname2, basename as basename2 } from "path";
+import { join as join13, relative, sep as sep2, extname, dirname as dirname3, basename as basename2 } from "path";
 var CODE_EXT = /* @__PURE__ */ new Set([
   "js",
   "jsx",
@@ -5097,7 +5150,7 @@ var MAX_FILES = 2e3;
 var MAX_FILE_BYTES = 400 * 1024;
 var MAX_TOTAL_BYTES = 64 * 1024 * 1024;
 function toPosix(p) {
-  return sep === "/" ? p : p.split(sep).join("/");
+  return sep2 === "/" ? p : p.split(sep2).join("/");
 }
 function ingestFolder(root, want = { code: true, docs: true }) {
   const files = [];
@@ -5286,7 +5339,7 @@ function resolvePySpec(f, spec, byId) {
   return null;
 }
 function toPosixDir(id) {
-  const d = toPosix(dirname2(id));
+  const d = toPosix(dirname3(id));
   return d === "" || d === "." ? "." : d;
 }
 var MD_LINK_RE = /\[[^\]]*\]\(([^)\s]+)(?:\s+["'][^"']*["'])?\)/g;
@@ -5489,7 +5542,7 @@ async function graph(args = []) {
   if (opts.report) {
     const md = renderReport(g, { workspace: workspace() });
     const reportPath = opts.out ? resolve4(opts.out) : join14(workspace(), "GRAPH_REPORT.md");
-    mkdirSync10(dirname3(reportPath), { recursive: true });
+    mkdirSync10(dirname4(reportPath), { recursive: true });
     writeFileSync11(reportPath, md, "utf8");
     const communities = new Set(g.nodes.map((n) => n.community ?? "0")).size;
     console.log("\n" + c.accent("Graph report written") + c.dim("  (this folder)"));
@@ -5511,7 +5564,7 @@ async function graph(args = []) {
     edges: g.edges.length
   });
   const outPath = opts.out ? resolve4(opts.out) : join14(wsHoltDir(), "graph.html");
-  mkdirSync10(dirname3(outPath), { recursive: true });
+  mkdirSync10(dirname4(outPath), { recursive: true });
   writeFileSync11(outPath, html, "utf8");
   console.log("\n" + c.accent("Memory graph built") + c.dim("  (this folder)"));
   const parts = [`${turns.length} turns`, `${conceptCount} concepts`];
@@ -5800,7 +5853,7 @@ function holtTools() {
 }
 
 // src/version.ts
-var VERSION = "0.10.0";
+var VERSION = "0.12.0";
 
 // src/commands/mcp.ts
 function printSetup() {
@@ -5847,7 +5900,7 @@ async function mcp(sub, rest = []) {
 
 // src/commands/hook.ts
 import { readFileSync as readFileSync15, writeFileSync as writeFileSync12, existsSync as existsSync14, mkdirSync as mkdirSync11, copyFileSync, realpathSync as realpathSync2 } from "fs";
-import { join as join15, dirname as dirname4 } from "path";
+import { join as join15, dirname as dirname5 } from "path";
 import { homedir as homedir3 } from "os";
 var EVENT = {
   inject: "UserPromptSubmit",
@@ -5873,7 +5926,7 @@ function readSettings(path) {
   }
 }
 function writeSettings(path, settings) {
-  mkdirSync11(dirname4(path), { recursive: true });
+  mkdirSync11(dirname5(path), { recursive: true });
   writeFileSync12(path, JSON.stringify(settings, null, 2) + "\n", "utf8");
 }
 function backup(path) {
@@ -6319,7 +6372,7 @@ async function run(args) {
 // src/commands/schedule.ts
 import { spawnSync as spawnSync4 } from "child_process";
 import { writeFileSync as writeFileSync15, mkdirSync as mkdirSync13, rmSync as rmSync6, existsSync as existsSync15 } from "fs";
-import { dirname as dirname5 } from "path";
+import { dirname as dirname6 } from "path";
 
 // src/scheduler.ts
 import { homedir as homedir4 } from "os";
@@ -6483,7 +6536,7 @@ function parseAdd(rest) {
 }
 function installDarwin(job, holtPath) {
   const path = plistPath(job.id);
-  mkdirSync13(dirname5(path), { recursive: true });
+  mkdirSync13(dirname6(path), { recursive: true });
   writeFileSync15(path, buildLaunchdPlist(job, holtPath), "utf8");
   const res = spawnSync4("launchctl", ["load", "-w", path], { encoding: "utf8" });
   if (res.status === 0) {
@@ -6636,7 +6689,7 @@ async function schedule(sub, rest = []) {
 // src/commands/routine.ts
 import { spawnSync as spawnSync5 } from "child_process";
 import { writeFileSync as writeFileSync17, mkdirSync as mkdirSync15, rmSync as rmSync7, existsSync as existsSync16 } from "fs";
-import { dirname as dirname6, resolve as resolve6 } from "path";
+import { dirname as dirname7, resolve as resolve6 } from "path";
 
 // src/routines.ts
 import { readFileSync as readFileSync17, writeFileSync as writeFileSync16, mkdirSync as mkdirSync14 } from "fs";
@@ -6717,7 +6770,7 @@ function routineJobId(name) {
 }
 function installDarwin2(job, holtPath) {
   const path = plistPath(job.id);
-  mkdirSync15(dirname6(path), { recursive: true });
+  mkdirSync15(dirname7(path), { recursive: true });
   writeFileSync17(path, buildLaunchdPlist(job, holtPath), "utf8");
   const res = spawnSync5("launchctl", ["load", "-w", path], { encoding: "utf8" });
   if (res.status === 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holt-os/holt",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "An open-source personal agent OS: any LLM, private memory you can see and walk.",
   "type": "module",
   "license": "MIT",
@@ -32,6 +32,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/action-items/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: action-items
+description: Pull decisions, tasks, and owners out of messy notes or a meeting transcript. Use to turn a raw log into a clean follow-up list.
+---
+
+# action-items
+
+## When to use
+
+The user pastes meeting notes, a call transcript, a chat log, or scattered notes and wants the concrete outcomes extracted so nothing gets lost.
+
+## Instructions
+
+1. Read the whole input and separate the substance from the chit-chat. Ignore greetings, tangents, and thinking-out-loud that led nowhere.
+2. Sort what remains into three groups: DECISIONS (what was settled), TODOS (what someone will do), and OPEN QUESTIONS (what is unresolved).
+3. Write each TODO as "owner: task (due date if stated)". If no owner is named, mark it "unassigned". Preserve names and dates exactly as written.
+4. Write each DECISION as a short statement of what was chosen and, if given, why.
+5. Keep each item to one line. Do not invent owners, dates, or actions that were not in the source.
+6. Output the three lists in that order. Omit a list only if it is genuinely empty.
+
+## Example
+
+DECISIONS
+- Ship the beta to the waitlist on Monday, not the public.
+
+TODOS
+- Sam: send the waitlist export to marketing (by Fri).
+- unassigned: write the launch FAQ.
+
+OPEN QUESTIONS
+- Do we gate signups behind an invite code?

package/skills/brief/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: brief
+description: A short briefing on the state of the current folder, using recalled memory plus the user's input. Use to get oriented fast.
+---
+
+# brief
+
+## When to use
+
+The user wants a quick read on what is going on here: what they were working on, what is decided, and what is next. This skill pairs with Holt's memory recall, which surfaces relevant past notes for the current folder.
+
+## Instructions
+
+1. Assume relevant past notes and facts have been injected as context above. Treat them as your source of truth for prior state; combine them with anything new in the user's input.
+2. Synthesize the state into three threads: what is IN PROGRESS, what is DECIDED, and what is OPEN or NEXT.
+3. Lead with the single most important thing: the item that most needs attention or that unblocks the rest.
+4. Keep it scannable: a short intro line, then tight bullets. This is a briefing, not a report.
+5. If the recalled context is thin or empty, say so plainly and ask the user for the one detail that would make the brief useful, rather than guessing.
+6. Do not restate the raw notes; distill them into current status.
+
+## Example
+
+Most important: the migration is blocked on a schema review that has been open three days.
+
+In progress: rewriting the importer; decided: drop the legacy CSV path; open: who signs off on the schema change.

package/skills/code-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: code-review
+description: Review a file or a diff for correctness bugs, edge cases, and simplifications. Use before merging or when a change feels risky.
+---
+
+# code-review
+
+## When to use
+
+The user shares a file, a function, or a diff and wants a focused review. The goal is catching real problems, not restyling working code.
+
+## Instructions
+
+1. Read for real defects first: logic errors, off-by-one and boundary mistakes, unhandled error paths, null or empty cases, security holes (injection, unescaped input, secrets), and resource leaks (unclosed files, sockets, handles).
+2. Then look for clarity and simplification: duplicated logic, dead code, overly clever constructs, and places a simpler shape would do the same job.
+3. Then note style issues, but only if they hurt readability. Skip pure nits unless the user asks for them.
+4. Report each finding as file:line, then what is wrong, then why it matters, then a concrete fix or the corrected snippet.
+5. Rank findings by severity: bugs and security first, then simplifications, then minor. Put the most important at the top.
+6. Be concise. If a change is clean, say so plainly instead of manufacturing feedback.
+
+## Example
+
+- api.ts:42 (bug): the loop uses <= arr.length, so the last iteration reads arr[arr.length] which is undefined. Change to <.
+- api.ts:88 (simplify): this if/else both return the same object with one field flipped; collapse to one return with a ternary.

package/skills/commit/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: commit
+description: Draft a clear commit message from staged changes or a described change. Use when you want a clean, conventional message.
+---
+
+# commit
+
+## When to use
+
+The user has staged changes (or describes a change in words) and wants a well-formed commit message.
+
+## Instructions
+
+1. Write a concise subject line in the imperative mood ("add", "fix", "remove", not "added" or "fixes"). Keep it under about 72 characters and do not end it with a period.
+2. If the change is trivial, the subject alone is enough. Stop there.
+3. If the change is non-trivial, add a blank line, then a short body that explains what changed and why, not how. The diff already shows how.
+4. If unrelated changes are bundled together, note that they would be cleaner as separate commits, but still give a usable message.
+5. Write a plain message. Do not add tool-attribution footers, "generated by" lines, or co-author trailers unless the user explicitly asks.
+6. If the intent is ambiguous from the changes, ask one clarifying question before guessing.
+
+## Example
+
+Subject: fix off-by-one in pagination cursor
+
+Body:
+The cursor advanced past the last page because the bound used <= instead of <, returning an empty final page. Correct the comparison so the last item is included.

package/skills/decide/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: decide
+description: Weigh a decision and give a clear recommendation. Use when the user is stuck between options and wants a reasoned call.
+---
+
+# decide
+
+## When to use
+
+The user faces a choice (which tool, which approach, whether to do something) and wants help thinking it through and a straight recommendation, not just a list of considerations.
+
+## Instructions
+
+1. Restate the decision and the options on the table in one line each, so you are answering the real question.
+2. List the factors that actually matter for this choice: cost, time, risk, reversibility, effort, fit. Drop factors that do not move the decision.
+3. For each option, give honest pros and cons against those factors. Do not stack the deck; name the real downside of the option you prefer.
+4. Make a clear recommendation. State the main reason it wins and the biggest risk it carries.
+5. If the call genuinely hinges on one unknown, do not guess: name that missing fact and ask for it before committing.
+6. Keep it decisive. The user wants a lean, not a shrug.
+
+## Example
+
+Decision: build the export feature now, or ship without it.
+
+Build it: pro, unblocks the biggest customer; con, adds a week.
+Ship without: pro, launch on time; con, that customer may churn.
+
+Recommendation: build it. Losing the anchor customer outweighs a week's delay. Biggest risk: the week slips to two. Missing fact: has the customer given a hard deadline?

package/skills/explain/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: explain
+description: Explain a concept, error message, or piece of jargon in plain language. Use when the user wants to understand something unfamiliar.
+---
+
+# explain
+
+## When to use
+
+The user asks what something means: a concept, an acronym, an error message, a term of art, or a confusing sentence. They want clarity, not a lecture.
+
+## Instructions
+
+1. Say what it is in one plain sentence, no jargon. If you must use a technical term, define it in the same breath.
+2. Say why it matters or where it shows up, so the user knows why they should care.
+3. Give one concrete analogy or a small worked example that makes it click.
+4. Match the level to the audience. If the user asks for "explain to a beginner" or "to a senior engineer", adjust depth, assumed background, and vocabulary accordingly. When unsure, aim for a smart non-expert.
+5. Keep it short. Stop once the idea lands; offer to go deeper rather than front-loading everything.
+
+## Example
+
+Request: explain what a race condition is, to a beginner.
+
+A race condition is when the result of your program depends on which of two things happens first, and you cannot control the order. It matters because it makes bugs that appear only sometimes. Think of two people editing the same shared doc line at the same time: whoever saves last wins, and the other edit silently vanishes.

package/skills/explain-code/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: explain-code
+description: Walk through what a file or function does and how it fits into the wider system. Use to onboard onto unfamiliar code.
+---
+
+# explain-code
+
+## When to use
+
+The user shares a file or function they did not write (or wrote a while ago) and wants to understand what it does, how it works, and how it connects to the rest of the code.
+
+## Instructions
+
+1. Start with a one-line purpose: what this code is for, in plain terms.
+2. Describe the flow and structure: the main steps or branches, in the order they run. Explain intent, not every line.
+3. Call out key dependencies and side effects: what it imports or calls, what state it reads or mutates, what it writes to disk, network, or the console.
+4. Flag any gotchas: assumptions it makes, inputs it does not handle, and non-obvious behavior a reader would trip on.
+5. Match depth to size. A small helper gets a few sentences; a large module gets a section per responsibility. Do not restate the code line by line.
+6. If something is genuinely unclear or looks buggy, say so rather than inventing a rationale.
+
+## Example
+
+Purpose: parses a config file and returns a typed settings object.
+
+Flow: reads the file, tries JSON.parse, falls back to defaults on any error, then validates required keys.
+
+Gotcha: it swallows parse errors silently, so a malformed config looks identical to a missing one.

package/skills/plan/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: plan
+description: Break a goal into a concrete, ordered set of steps. Use when a task is big enough to need sequencing before starting.
+---
+
+# plan
+
+## When to use
+
+The user states a goal or a task and wants it broken into an actionable, ordered plan they can execute or hand off.
+
+## Instructions
+
+1. Restate the goal in one line so the target is unambiguous.
+2. List the steps in the order they must happen. Each step gets a clear done-condition: how you will know it is finished.
+3. Flag dependencies explicitly (step 4 needs step 2 done first) so the sequence is not just a wish list.
+4. Call out the riskiest or most uncertain step, the one most likely to blow up the timeline, so it can be tackled or de-risked early.
+5. Keep it actionable, not aspirational. Prefer "write the migration script and run it on a copy" over "improve the database".
+6. End with the single immediate next action the user should take right now.
+
+## Example
+
+Goal: move the app from the old auth library to the new one.
+
+1. Inventory every call site of the old library (done: a list exists).
+2. Write an adapter matching the old interface (done: tests pass). RISKIEST: the token refresh path differs.
+3. Swap call sites behind a flag (done: app runs on the flag).
+
+Next action: run the inventory grep in step 1.

package/skills/rewrite/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: rewrite
+description: Tighten and clarify a piece of text without changing its meaning. Use for a neutral clarity pass on text the user provides.
+---
+
+# rewrite
+
+## When to use
+
+The user pastes a paragraph, email, or passage and wants it cleaner and clearer while keeping the same meaning. This is a neutral clarity pass, distinct from a voice-anchored writing task: keep the author's own voice unless a tone is requested.
+
+## Instructions
+
+1. Preserve intent and every fact. Do not add claims, drop caveats, or change the point being made.
+2. Cut filler and hedging: "just", "really", "I think that", "in order to", throat-clearing intros, and redundant phrases.
+3. Prefer plain words over inflated ones ("use" not "utilize", "help" not "facilitate").
+4. Vary sentence length so it reads naturally; break up run-ons, and do not make everything staccato.
+5. Keep the author's voice and register. Only shift tone (more formal, warmer, punchier) if the user asks for it.
+6. Return only the rewritten text, then one short line noting what you changed (for example: "tightened, cut hedging, split two long sentences").
+
+## Example
+
+Before: I just wanted to reach out in order to see if you might possibly have some availability to maybe hop on a quick call sometime.
+
+After: Do you have time for a quick call this week?
+
+Changed: cut hedging and filler, made it a direct ask.

package/skills/summarize/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: summarize
+description: Condense a document, article, transcript, or pasted text into its key points. Use when the input is long and the user wants the gist fast.
+---
+
+# summarize
+
+## When to use
+
+The user pastes or points at a document, article, transcript, email thread, or any long block of text and wants a shorter version that keeps what matters.
+
+## Instructions
+
+1. Read the whole input first and identify its core purpose in one sentence (what it is and why it exists).
+2. Open with a one-line TLDR that captures the single most important takeaway.
+3. Pull the main points: arguments, decisions, numbers, dates, and named people or systems. Keep these verbatim where accuracy matters.
+4. Drop filler: greetings, repetition, hedging, and asides that do not change the meaning.
+5. Scale the output to the input. A few paragraphs get a short bulleted list; a long report gets tight prose grouped by theme. Do not pad.
+6. Do not add facts, opinions, or conclusions that are not in the source.
+
+## Example
+
+TLDR: The team is shipping the payments rewrite next week despite one open risk.
+
+- Decision: launch v2 on the 14th, feature-flagged to 10 percent of users.
+- Open risk: the refund path is untested under load.
+- Owner: Priya to run a load test before Friday.