mini-coder 0.0.19 → 0.0.20

package/dist/mc.js

@@ -3,7 +3,7 @@
 
 // src/index.ts
 import { writeSync } from "fs";
-import * as c19 from "yoctocolors";
+import * as c18 from "yoctocolors";
 
 // src/agent/agent.ts
 import * as c12 from "yoctocolors";
@@ -385,39 +385,53 @@ import * as c4 from "yoctocolors";
 function renderInline(text) {
   let out = "";
   let i = 0;
+  let segStart = 0;
   let prevWasBoldClose = false;
   while (i < text.length) {
-    if (text[i] === "`") {
+    const ch = text[i];
+    if (ch === "`") {
       const end = text.indexOf("`", i + 1);
       if (end !== -1) {
+        if (i > segStart)
+          out += text.slice(segStart, i);
         out += c4.yellow(text.slice(i, end + 1));
         i = end + 1;
+        segStart = i;
         prevWasBoldClose = false;
         continue;
       }
     }
-    if (text.slice(i, i + 2) === "**" && text[i + 2] !== "*") {
-      const end = text.indexOf("**", i + 2);
-      if (end !== -1) {
-        out += c4.bold(text.slice(i + 2, end));
-        i = end + 2;
-        prevWasBoldClose = true;
-        continue;
+    if (ch === "*") {
+      if (text[i + 1] === "*" && text[i + 2] !== "*") {
+        const end = text.indexOf("**", i + 2);
+        if (end !== -1) {
+          if (i > segStart)
+            out += text.slice(segStart, i);
+          out += c4.bold(text.slice(i + 2, end));
+          i = end + 2;
+          segStart = i;
+          prevWasBoldClose = true;
+          continue;
+        }
       }
-    }
-    if (text[i] === "*" && text[i + 1] !== "*" && (prevWasBoldClose || text[i - 1] !== "*")) {
-      const end = text.indexOf("*", i + 1);
-      if (end !== -1 && text[end - 1] !== "*") {
-        out += c4.dim(text.slice(i + 1, end));
-        i = end + 1;
-        prevWasBoldClose = false;
-        continue;
+      if (text[i + 1] !== "*" && (prevWasBoldClose || text[i - 1] !== "*")) {
+        const end = text.indexOf("*", i + 1);
+        if (end !== -1 && text[end - 1] !== "*") {
+          if (i > segStart)
+            out += text.slice(segStart, i);
+          out += c4.dim(text.slice(i + 1, end));
+          i = end + 1;
+          segStart = i;
+          prevWasBoldClose = false;
+          continue;
+        }
       }
     }
-    out += text[i];
-    i++;
     prevWasBoldClose = false;
+    i++;
   }
+  if (segStart < text.length)
+    out += text.slice(segStart);
   return out;
 }
 function renderLine(raw, inFence) {
@@ -481,6 +495,39 @@ function renderMarkdown(text) {
 `);
 }
 
+// src/cli/reasoning.ts
+function normalizeReasoningDelta(delta) {
+  return delta.replace(/\r\n?/g, `
+`);
+}
+function normalizeReasoningText(text) {
+  const normalized = normalizeReasoningDelta(text);
+  const lines = normalized.split(`
+`).map((line) => line.replace(/[ \t]+$/g, ""));
+  let start = 0;
+  while (start < lines.length && lines[start]?.trim() === "")
+    start++;
+  let end = lines.length - 1;
+  while (end >= start && lines[end]?.trim() === "")
+    end--;
+  if (start > end)
+    return "";
+  const compact = [];
+  let blankRun = 0;
+  for (const line of lines.slice(start, end + 1)) {
+    if (line.trim() === "") {
+      blankRun += 1;
+      if (blankRun <= 1)
+        compact.push("");
+      continue;
+    }
+    blankRun = 0;
+    compact.push(line);
+  }
+  return compact.join(`
+`);
+}
+
 // src/cli/tool-render.ts
 import { homedir as homedir2 } from "os";
 import * as c5 from "yoctocolors";
@@ -705,7 +752,19 @@ function renderToolResult(toolName, result, isError, _toolCallId) {
   if (toolName === "subagent") {
     const r = result;
     const label = r.agentName ? ` ${c5.dim(c5.cyan(`[@${r.agentName}]`))}` : "";
-    writeln(`    ${c5.cyan("\u2190")}${label} ${c5.dim(`subagent done (${r.inputTokens ?? 0}in / ${r.outputTokens ?? 0}out tokens)`)}`);
+    writeln(`    ${G.agent}${label} ${c5.dim(`subagent done (${r.inputTokens ?? 0}in / ${r.outputTokens ?? 0}out tokens)`)}`);
+    return;
+  }
+  if (toolName === "readSkill") {
+    const r = result;
+    if (!r.skill) {
+      writeln(`    ${G.info} ${c5.dim("skill-auto-load miss")}`);
+      return;
+    }
+    const name = r.skill.name ?? "(unknown)";
+    const source = r.skill.source ?? "unknown";
+    const description = r.skill.description?.trim();
+    writeln(`    ${G.info} ${c5.dim(`skill-auto-loaded name=${name} source=${source}${description ? ` description=${JSON.stringify(description)}` : ""}`)}`);
     return;
   }
   if (toolName === "webSearch") {
@@ -777,16 +836,30 @@ async function renderTurn(events, spinner, opts) {
   let accumulatedText = "";
   let accumulatedReasoning = "";
   let inFence = false;
+  let reasoningBlankLineRun = 0;
   let inputTokens = 0;
   let outputTokens = 0;
   let contextTokens = 0;
   let newMessages = [];
+  function renderSingleLine(raw) {
+    const source = inReasoning ? raw.replace(/[ \t]+$/g, "") : raw;
+    if (inReasoning && source.trim() === "") {
+      reasoningBlankLineRun += 1;
+      if (reasoningBlankLineRun > 1)
+        return null;
+    } else if (inReasoning) {
+      reasoningBlankLineRun = 0;
+    }
+    const rendered = renderLine(source, inFence);
+    inFence = rendered.inFence;
+    return inReasoning ? `${c6.dim("\u2502 ")}${rendered.output}` : rendered.output;
+  }
   function renderAndWrite(raw, endWithNewline) {
     spinner.stop();
-    const rendered = renderLine(raw, inFence);
-    inFence = rendered.inFence;
-    const finalOutput = inReasoning ? c6.dim(rendered.output) : rendered.output;
-    write(finalOutput);
+    const out = renderSingleLine(raw);
+    if (out === null)
+      return;
+    write(out);
     if (endWithNewline) {
       write(`
 `);
@@ -798,17 +871,30 @@ async function renderTurn(events, spinner, opts) {
       writeln();
       inText = false;
       inReasoning = false;
+      reasoningBlankLineRun = 0;
     }
   }
   function flushCompleteLines() {
+    let start = 0;
     let boundary = rawBuffer.indexOf(`
-`);
+`, start);
+    if (boundary === -1)
+      return;
+    spinner.stop();
+    let batchOutput = "";
     while (boundary !== -1) {
-      renderAndWrite(rawBuffer.slice(0, boundary), true);
-      rawBuffer = rawBuffer.slice(boundary + 1);
+      const raw = rawBuffer.slice(start, boundary);
+      start = boundary + 1;
       boundary = rawBuffer.indexOf(`
-`);
+`, start);
+      const out = renderSingleLine(raw);
+      if (out !== null)
+        batchOutput += `${out}
+`;
     }
+    rawBuffer = start > 0 ? rawBuffer.slice(start) : rawBuffer;
+    if (batchOutput)
+      write(batchOutput);
   }
   function flushAll() {
     if (!rawBuffer) {
@@ -834,7 +920,8 @@ async function renderTurn(events, spinner, opts) {
         break;
       }
       case "reasoning-delta": {
-        accumulatedReasoning += event.delta;
+        const delta = normalizeReasoningDelta(event.delta);
+        accumulatedReasoning += delta;
         if (!showReasoning) {
           break;
         }
@@ -843,9 +930,10 @@ async function renderTurn(events, spinner, opts) {
             flushAnyText();
           }
           spinner.stop();
+          writeln(`${G.info} ${c6.dim("reasoning")}`);
           inReasoning = true;
         }
-        rawBuffer += event.delta;
+        rawBuffer += delta;
         flushCompleteLines();
         break;
       }
@@ -862,9 +950,18 @@ async function renderTurn(events, spinner, opts) {
         spinner.start("thinking");
         break;
       }
+      case "context-pruned": {
+        flushAnyText();
+        spinner.stop();
+        writeln(`${G.info} ${c6.dim(`context-pruned mode=${event.mode} removed_messages=${event.removedMessageCount} removed_bytes=${event.removedBytes} messages_before=${event.beforeMessageCount} messages_after=${event.afterMessageCount}`)}`);
+        break;
+      }
       case "turn-complete": {
+        const hadContent = inText || inReasoning;
         flushAnyText();
         spinner.stop();
+        if (!hadContent)
+          writeln();
         inputTokens = event.inputTokens;
         outputTokens = event.outputTokens;
         contextTokens = event.contextTokens;
@@ -895,13 +992,13 @@ async function renderTurn(events, spinner, opts) {
     outputTokens,
     contextTokens,
     newMessages,
-    reasoningText: accumulatedReasoning
+    reasoningText: normalizeReasoningText(accumulatedReasoning)
   };
 }
 
 // src/cli/output.ts
 var HOME2 = homedir3();
-var PACKAGE_VERSION = "0.0.19";
+var PACKAGE_VERSION = "0.0.20";
 function tildePath(p) {
   return p.startsWith(HOME2) ? `~${p.slice(HOME2.length)}` : p;
 }
@@ -1606,7 +1703,7 @@ function deleteAllSnapshots(sessionId) {
 import * as c11 from "yoctocolors";
 
 // src/cli/input.ts
-import { join as join4, relative } from "path";
+import { join as join5, relative } from "path";
 import * as c9 from "yoctocolors";
 
 // src/cli/image-types.ts
@@ -1645,21 +1742,198 @@ async function loadImageFile(filePath) {
 }
 
 // src/cli/skills.ts
-function loadSkills(cwd, homeDir) {
-  return loadMarkdownConfigs({
-    type: "skills",
-    strategy: "nested",
-    nestedFileName: "SKILL.md",
-    cwd,
-    homeDir,
-    includeClaudeDirs: true,
-    mapConfig: ({ name, meta, raw, source }) => ({
-      name,
-      description: meta.description ?? name,
-      content: raw,
+import {
+  closeSync,
+  existsSync as existsSync3,
+  openSync,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync2,
+  readSync,
+  statSync as statSync2
+} from "fs";
+import { homedir as homedir6 } from "os";
+import { dirname, join as join4, resolve } from "path";
+var MAX_FRONTMATTER_BYTES = 64 * 1024;
+var SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+var MIN_SKILL_NAME_LENGTH = 1;
+var MAX_SKILL_NAME_LENGTH = 64;
+var warnedInvalidSkills = new Set;
+function parseSkillFrontmatter(filePath) {
+  let fd = null;
+  try {
+    fd = openSync(filePath, "r");
+    const chunk = Buffer.allocUnsafe(MAX_FRONTMATTER_BYTES);
+    const bytesRead = readSync(fd, chunk, 0, MAX_FRONTMATTER_BYTES, 0);
+    const text = chunk.toString("utf8", 0, bytesRead);
+    const lines = text.split(`
+`);
+    if ((lines[0] ?? "").trim() !== "---")
+      return {};
+    const meta = {};
+    for (let i = 1;i < lines.length; i++) {
+      const line = (lines[i] ?? "").replace(/\r$/, "");
+      if (line.trim() === "---")
+        break;
+      const colon = line.indexOf(":");
+      if (colon === -1)
+        continue;
+      const key = line.slice(0, colon).trim();
+      const value = line.slice(colon + 1).trim().replace(/^["']|["']$/g, "");
+      if (key === "name")
+        meta.name = value;
+      if (key === "description")
+        meta.description = value;
+    }
+    return meta;
+  } catch {
+    return {};
+  } finally {
+    if (fd !== null)
+      closeSync(fd);
+  }
+}
+function getCandidateFrontmatter(candidate) {
+  if (!candidate.frontmatter) {
+    candidate.frontmatter = parseSkillFrontmatter(candidate.filePath);
+  }
+  return candidate.frontmatter;
+}
+function candidateConflictName(candidate) {
+  return getCandidateFrontmatter(candidate).name?.trim() || candidate.folderName;
+}
+function findGitBoundary(cwd) {
+  let current = resolve(cwd);
+  while (true) {
+    if (existsSync3(join4(current, ".git")))
+      return current;
+    const parent = dirname(current);
+    if (parent === current)
+      return null;
+    current = parent;
+  }
+}
+function localSearchRoots(cwd) {
+  const start = resolve(cwd);
+  const stop = findGitBoundary(start);
+  if (!stop)
+    return [start];
+  const roots = [];
+  let current = start;
+  while (true) {
+    roots.push(current);
+    if (current === stop)
+      break;
+    const parent = dirname(current);
+    if (parent === current)
+      break;
+    current = parent;
+  }
+  return roots;
+}
+function listSkillCandidates(skillsDir, source, rootPath) {
+  if (!existsSync3(skillsDir))
+    return [];
+  let entries;
+  try {
+    entries = readdirSync2(skillsDir).sort((a, b) => a.localeCompare(b));
+  } catch {
+    return [];
+  }
+  const candidates = [];
+  for (const entry of entries) {
+    const skillDir = join4(skillsDir, entry);
+    try {
+      if (!statSync2(skillDir).isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    const filePath = join4(skillDir, "SKILL.md");
+    if (!existsSync3(filePath))
+      continue;
+    candidates.push({
+      folderName: entry,
+      filePath,
+      rootPath,
       source
-    })
-  });
+    });
+  }
+  return candidates;
+}
+function warnInvalidSkill(filePath, reason) {
+  const key = `${filePath}:${reason}`;
+  if (warnedInvalidSkills.has(key))
+    return;
+  warnedInvalidSkills.add(key);
+  writeln(`${G.warn} skipping invalid skill ${filePath}: ${reason}`);
+}
+function validateSkill(candidate) {
+  const meta = getCandidateFrontmatter(candidate);
+  const name = meta.name?.trim();
+  const description = meta.description?.trim();
+  if (!name) {
+    warnInvalidSkill(candidate.filePath, "frontmatter field `name` is required");
+    return null;
+  }
+  if (!description) {
+    warnInvalidSkill(candidate.filePath, "frontmatter field `description` is required");
+    return null;
+  }
+  if (name.length < MIN_SKILL_NAME_LENGTH || name.length > MAX_SKILL_NAME_LENGTH) {
+    warnInvalidSkill(candidate.filePath, `name must be ${MIN_SKILL_NAME_LENGTH}-${MAX_SKILL_NAME_LENGTH} characters`);
+    return null;
+  }
+  if (!SKILL_NAME_RE.test(name)) {
+    warnInvalidSkill(candidate.filePath, "name must match lowercase alnum + hyphen format");
+    return null;
+  }
+  return {
+    name,
+    description,
+    source: candidate.source,
+    rootPath: candidate.rootPath,
+    filePath: candidate.filePath
+  };
+}
+function allSkillCandidates(cwd, homeDir) {
+  const home = homeDir ?? homedir6();
+  const localRootsNearToFar = localSearchRoots(cwd);
+  const ordered = [];
+  const globalClaude = listSkillCandidates(join4(home, ".claude", "skills"), "global", home);
+  const globalAgents = listSkillCandidates(join4(home, ".agents", "skills"), "global", home);
+  warnConventionConflicts("skills", "global", globalAgents.map((skill) => candidateConflictName(skill)), globalClaude.map((skill) => candidateConflictName(skill)));
+  ordered.push(...globalClaude, ...globalAgents);
+  for (const root of [...localRootsNearToFar].reverse()) {
+    const localClaude = listSkillCandidates(join4(root, ".claude", "skills"), "local", root);
+    const localAgents = listSkillCandidates(join4(root, ".agents", "skills"), "local", root);
+    warnConventionConflicts("skills", "local", localAgents.map((skill) => candidateConflictName(skill)), localClaude.map((skill) => candidateConflictName(skill)));
+    ordered.push(...localClaude, ...localAgents);
+  }
+  return ordered;
+}
+function loadSkillsIndex(cwd, homeDir) {
+  const index = new Map;
+  for (const candidate of allSkillCandidates(cwd, homeDir)) {
+    const skill = validateSkill(candidate);
+    if (!skill)
+      continue;
+    index.set(skill.name, skill);
+  }
+  return index;
+}
+function loadSkillContentFromMeta(skill) {
+  try {
+    const content = readFileSync2(skill.filePath, "utf-8");
+    return { name: skill.name, content, source: skill.source };
+  } catch {
+    return null;
+  }
+}
+function loadSkillContent(name, cwd, homeDir) {
+  const skill = loadSkillsIndex(cwd, homeDir).get(name);
+  if (!skill)
+    return null;
+  return loadSkillContentFromMeta(skill);
 }
 
 // src/cli/input.ts
@@ -1696,7 +1970,7 @@ async function getAtCompletions(prefix, cwd) {
   const query = prefix.startsWith("@") ? prefix.slice(1) : prefix;
   const results = [];
   const MAX = 10;
-  const skills = loadSkills(cwd);
+  const skills = loadSkillsIndex(cwd);
   for (const [name] of skills) {
     if (results.length >= MAX)
       break;
@@ -1715,7 +1989,7 @@ async function getAtCompletions(prefix, cwd) {
     for await (const file of glob.scan({ cwd, onlyFiles: true })) {
       if (file.includes("node_modules") || file.includes(".git"))
         continue;
-      results.push(`@${relative(cwd, join4(cwd, file))}`);
+      results.push(`@${relative(cwd, join5(cwd, file))}`);
       if (results.length >= MAX)
         break;
     }
@@ -1737,7 +2011,7 @@ async function tryExtractImageFromPaste(pasted, cwd) {
     }
   }
   if (!trimmed.includes(" ") && isImageFilename(trimmed)) {
-    const filePath = trimmed.startsWith("/") ? trimmed : join4(cwd, trimmed);
+    const filePath = trimmed.startsWith("/") ? trimmed : join5(cwd, trimmed);
     const attachment = await loadImageFile(filePath);
     if (attachment) {
       const name = filePath.split("/").pop() ?? trimmed;
@@ -1783,6 +2057,17 @@ function getTurnControlAction(chunk) {
   }
   return null;
 }
+function getSubagentControlAction(chunk) {
+  for (const byte of chunk) {
+    if (byte === CTRL_C_BYTE)
+      return "quit";
+  }
+  for (const byte of chunk) {
+    if (byte === ESC_BYTE)
+      return "cancel";
+  }
+  return null;
+}
 function exitOnCtrlC(opts) {
   if (opts?.printNewline)
     process.stdout.write(`
@@ -1795,15 +2080,16 @@ function exitOnCtrlC(opts) {
   terminal.restoreTerminal();
   process.exit(130);
 }
-function watchForCancel(abortController) {
+function watchForCancel(abortController, options) {
   if (!terminal.isTTY)
     return () => {};
   const onCancel = () => {
     cleanup();
     abortController.abort();
   };
+  const getAction = options?.allowSubagentEsc ? getSubagentControlAction : getTurnControlAction;
   const onData = (chunk) => {
-    const action = getTurnControlAction(chunk);
+    const action = getAction(chunk);
     if (action === "cancel") {
       onCancel();
       return;
@@ -2216,15 +2502,15 @@ import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
 
 // src/llm-api/api-log.ts
 import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync2 } from "fs";
-import { homedir as homedir6 } from "os";
-import { join as join5 } from "path";
+import { homedir as homedir7 } from "os";
+import { join as join6 } from "path";
 var writer2 = null;
 var MAX_ENTRY_BYTES = 8 * 1024;
 function initApiLog() {
   if (writer2)
     return;
-  const dirPath = join5(homedir6(), ".config", "mini-coder");
-  const logPath = join5(dirPath, "api.log");
+  const dirPath = join6(homedir7(), ".config", "mini-coder");
+  const logPath = join6(dirPath, "api.log");
   mkdirSync3(dirPath, { recursive: true });
   writeFileSync2(logPath, "");
   writer2 = Bun.file(logPath).writer();
@@ -3660,9 +3946,23 @@ async function* runTurn(options) {
     if (openAIItemIdsStrippedMessages !== gptSanitizedMessages) {
       logApiEvent("openai item ids stripped from history", { modelString });
     }
-    logApiEvent("turn context pre-prune", getMessageDiagnostics(openAIItemIdsStrippedMessages));
+    const prePruneDiagnostics = getMessageDiagnostics(openAIItemIdsStrippedMessages);
+    logApiEvent("turn context pre-prune", prePruneDiagnostics);
     const prunedMessages = applyContextPruning(openAIItemIdsStrippedMessages, pruningMode);
-    logApiEvent("turn context post-prune", getMessageDiagnostics(prunedMessages));
+    const postPruneDiagnostics = getMessageDiagnostics(prunedMessages);
+    logApiEvent("turn context post-prune", postPruneDiagnostics);
+    if ((pruningMode === "balanced" || pruningMode === "aggressive") && (postPruneDiagnostics.messageCount < prePruneDiagnostics.messageCount || postPruneDiagnostics.totalBytes < prePruneDiagnostics.totalBytes)) {
+      yield {
+        type: "context-pruned",
+        mode: pruningMode,
+        beforeMessageCount: prePruneDiagnostics.messageCount,
+        afterMessageCount: postPruneDiagnostics.messageCount,
+        removedMessageCount: prePruneDiagnostics.messageCount - postPruneDiagnostics.messageCount,
+        beforeTotalBytes: prePruneDiagnostics.totalBytes,
+        afterTotalBytes: postPruneDiagnostics.totalBytes,
+        removedBytes: prePruneDiagnostics.totalBytes - postPruneDiagnostics.totalBytes
+      };
+    }
     const turnMessages = compactToolResultPayloads(prunedMessages, toolResultPayloadCapBytes);
     if (turnMessages !== prunedMessages) {
       logApiEvent("turn context post-compaction", {
@@ -3874,10 +4174,10 @@ function getMostRecentSession() {
 
 // src/tools/snapshot.ts
 import { unlinkSync as unlinkSync2 } from "fs";
-import { isAbsolute, join as join6, relative as relative2 } from "path";
+import { isAbsolute, join as join7, relative as relative2 } from "path";
 async function snapshotBeforeEdit(cwd, sessionId, turnIndex, filePath, snappedPaths) {
   try {
-    const absPath = isAbsolute(filePath) ? filePath : join6(cwd, filePath);
+    const absPath = isAbsolute(filePath) ? filePath : join7(cwd, filePath);
     const relPath = isAbsolute(filePath) ? relative2(cwd, filePath) : filePath;
     if (snappedPaths.has(relPath))
       return;
@@ -3899,7 +4199,7 @@ async function restoreSnapshot(cwd, sessionId, turnIndex) {
       return { restored: false, reason: "not-found" };
     let anyFailed = false;
     for (const file of files) {
-      const absPath = join6(cwd, file.path);
+      const absPath = join7(cwd, file.path);
       if (!file.existed) {
         try {
           if (await Bun.file(absPath).exists()) {
@@ -3928,24 +4228,24 @@ async function restoreSnapshot(cwd, sessionId, turnIndex) {
 }
 
 // src/agent/system-prompt.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
-import { homedir as homedir7 } from "os";
-import { join as join7 } from "path";
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "fs";
+import { homedir as homedir8 } from "os";
+import { join as join8 } from "path";
 function tryReadFile(p) {
-  if (!existsSync3(p))
+  if (!existsSync4(p))
     return null;
   try {
-    return readFileSync2(p, "utf-8");
+    return readFileSync3(p, "utf-8");
   } catch {
     return null;
   }
 }
 function loadGlobalContextFile(homeDir) {
-  const globalDir = join7(homeDir, ".agents");
-  return tryReadFile(join7(globalDir, "AGENTS.md")) ?? tryReadFile(join7(globalDir, "CLAUDE.md"));
+  const globalDir = join8(homeDir, ".agents");
+  return tryReadFile(join8(globalDir, "AGENTS.md")) ?? tryReadFile(join8(globalDir, "CLAUDE.md"));
 }
 function loadLocalContextFile(cwd) {
-  return tryReadFile(join7(cwd, ".agents", "AGENTS.md")) ?? tryReadFile(join7(cwd, "CLAUDE.md")) ?? tryReadFile(join7(cwd, "AGENTS.md"));
+  return tryReadFile(join8(cwd, ".agents", "AGENTS.md")) ?? tryReadFile(join8(cwd, "CLAUDE.md")) ?? tryReadFile(join8(cwd, "AGENTS.md"));
 }
 var AUTONOMY = `
 
@@ -3986,7 +4286,7 @@ var FINAL_MESSAGE = `
 - If verification could not be run, say so clearly.`;
 var SUBAGENT_DELEGATION = `You are running as a subagent. Complete the task you have been given directly using your tools. Do not spawn further subagents unless the subtask is unambiguously separable and self-contained.`;
 function buildSystemPrompt(sessionTimeAnchor, cwd, extraSystemPrompt, isSubagent, homeDir) {
-  const globalContext = loadGlobalContextFile(homeDir ?? homedir7());
+  const globalContext = loadGlobalContextFile(homeDir ?? homedir8());
   const localContext = loadLocalContextFile(cwd);
   const cwdDisplay = tildePath(cwd);
   let prompt = `You are mini-coder, a small and fast CLI coding agent.
@@ -4024,6 +4324,17 @@ ${globalContext}`;
 ${localContext}`;
     }
   }
+  const skills = Array.from(loadSkillsIndex(cwd, homeDir).values());
+  if (skills.length > 0) {
+    prompt += `
+
+# Available skills (metadata only)`;
+    prompt += "\nUse `listSkills` to browse and `readSkill` to load one SKILL.md on demand.\n";
+    for (const skill of skills) {
+      prompt += `
+- ${skill.name}: ${skill.description} (${skill.source})`;
+    }
+  }
   if (isSubagent) {
     prompt += `
 
@@ -4038,8 +4349,8 @@ ${extraSystemPrompt}`;
 }
 
 // src/tools/create.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4 } from "fs";
-import { dirname } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4 } from "fs";
+import { dirname as dirname2 } from "path";
 import { z } from "zod";
 
 // src/tools/diff.ts
@@ -4169,10 +4480,10 @@ ${lines.join(`
 }
 
 // src/tools/shared.ts
-import { join as join8, relative as relative3 } from "path";
+import { join as join9, relative as relative3 } from "path";
 function resolvePath(cwdInput, pathInput) {
   const cwd = cwdInput ?? process.cwd();
-  const filePath = pathInput.startsWith("/") ? pathInput : join8(cwd, pathInput);
+  const filePath = pathInput.startsWith("/") ? pathInput : join9(cwd, pathInput);
   const relPath = relative3(cwd, filePath);
   return { cwd, filePath, relPath };
 }
@@ -4222,8 +4533,8 @@ var createTool = {
   schema: CreateSchema,
   execute: async (input) => {
     const { filePath, relPath } = resolvePath(input.cwd, input.path);
-    const dir = dirname(filePath);
-    if (!existsSync4(dir))
+    const dir = dirname2(filePath);
+    if (!existsSync5(dir))
       mkdirSync4(dir, { recursive: true });
     const file = Bun.file(filePath);
     const created = !await file.exists();
@@ -4294,15 +4605,15 @@ var webContentTool = {
 };
 
 // src/tools/glob.ts
-import { resolve as resolve2 } from "path";
+import { resolve as resolve3 } from "path";
 import { z as z3 } from "zod";
 
 // src/tools/ignore.ts
-import { join as join9 } from "path";
+import { join as join10 } from "path";
 import ignore from "ignore";
 async function loadGitignore(cwd) {
   try {
-    const gitignore = await Bun.file(join9(cwd, ".gitignore")).text();
+    const gitignore = await Bun.file(join10(cwd, ".gitignore")).text();
     return ignore().add(gitignore);
   } catch {
     return null;
@@ -4310,11 +4621,11 @@ async function loadGitignore(cwd) {
 }
 
 // src/tools/scan-path.ts
-import { relative as relative4, resolve, sep } from "path";
+import { relative as relative4, resolve as resolve2, sep } from "path";
 var LEADING_PARENT_SEGMENTS = /^(?:\.\.\/)+/;
 function getScannedPathInfo(cwd, scanPath) {
-  const cwdAbsolute = resolve(cwd);
-  const absolute = resolve(cwdAbsolute, scanPath);
+  const cwdAbsolute = resolve2(cwd);
+  const absolute = resolve2(cwdAbsolute, scanPath);
   const relativePath = relative4(cwdAbsolute, absolute).replaceAll("\\", "/");
   const inCwd = absolute === cwdAbsolute || absolute.startsWith(cwdAbsolute === sep ? sep : `${cwdAbsolute}${sep}`);
   const ignoreTargets = getIgnoreTargets(relativePath, inCwd);
@@ -4366,7 +4677,7 @@ var globTool = {
       if (ignored)
         continue;
       try {
-        const fullPath = resolve2(cwd, relativePath);
+        const fullPath = resolve3(cwd, relativePath);
         const stat = await Bun.file(fullPath).stat?.() ?? null;
         matches.push({
           path: relativePath,
@@ -4530,8 +4841,8 @@ var grepTool = {
 
 // src/tools/hooks.ts
 import { accessSync, constants } from "fs";
-import { homedir as homedir8 } from "os";
-import { join as join10 } from "path";
+import { homedir as homedir9 } from "os";
+import { join as join11 } from "path";
 function isExecutable(filePath) {
   try {
     accessSync(filePath, constants.X_OK);
@@ -4543,8 +4854,8 @@ function isExecutable(filePath) {
 function findHook(toolName, cwd) {
   const scriptName = `post-${toolName}`;
   const candidates = [
-    join10(cwd, ".agents", "hooks", scriptName),
-    join10(homedir8(), ".agents", "hooks", scriptName)
+    join11(cwd, ".agents", "hooks", scriptName),
+    join11(homedir9(), ".agents", "hooks", scriptName)
   ];
   for (const p of candidates) {
     if (isExecutable(p))
@@ -4863,11 +5174,41 @@ var shellTool = {
   }
 };
 
-// src/tools/subagent.ts
+// src/tools/skills.ts
 import { z as z9 } from "zod";
-var SubagentInput = z9.object({
-  prompt: z9.string().describe("The task or question to give the subagent"),
-  agentName: z9.string().optional().describe("Name of a custom agent to use (from .agents/agents/). Omit to use a generic subagent.")
+var ListSkillsSchema = z9.object({});
+var listSkillsTool = {
+  name: "listSkills",
+  description: "List available skills metadata (name, description, source) without loading SKILL.md bodies.",
+  schema: ListSkillsSchema,
+  execute: async (input) => {
+    const cwd = input.cwd ?? process.cwd();
+    const skills = Array.from(loadSkillsIndex(cwd).values()).map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      source: skill.source
+    }));
+    return { skills };
+  }
+};
+var ReadSkillSchema = z9.object({
+  name: z9.string().describe("Skill name to load")
+});
+var readSkillTool = {
+  name: "readSkill",
+  description: "Load full SKILL.md content for one skill by name.",
+  schema: ReadSkillSchema,
+  execute: async (input) => {
+    const cwd = input.cwd ?? process.cwd();
+    return { skill: loadSkillContent(input.name, cwd) };
+  }
+};
+
+// src/tools/subagent.ts
+import { z as z10 } from "zod";
+var SubagentInput = z10.object({
+  prompt: z10.string().describe("The task or question to give the subagent"),
+  agentName: z10.string().optional().describe("Name of a custom agent to use (from .agents/agents/). Omit to use a generic subagent.")
 });
 function createSubagentTool(runSubagent, availableAgents) {
   const agentSection = availableAgents.size > 0 ? `
@@ -4950,6 +5291,8 @@ function buildToolSet(opts) {
     withHooks(withCwdDefault(globTool, cwd), lookupHook, cwd, (_, input) => hookEnvForGlob(input, cwd), onHook),
     withHooks(withCwdDefault(grepTool, cwd), lookupHook, cwd, (_, input) => hookEnvForGrep(input, cwd), onHook),
     withHooks(withCwdDefault(readTool, cwd), lookupHook, cwd, (_, input) => hookEnvForRead(input, cwd), onHook),
+    withCwdDefault(listSkillsTool, cwd),
+    withCwdDefault(readSkillTool, cwd),
     withHooks(withCwdDefault(createTool, cwd, opts.snapshotCallback), lookupHook, cwd, (result) => hookEnvForCreate(result, cwd), onHook, finalizeWriteResult),
     withHooks(withCwdDefault(replaceTool, cwd, opts.snapshotCallback), lookupHook, cwd, (result) => hookEnvForReplace(result, cwd), onHook, finalizeWriteResult),
     withHooks(withCwdDefault(insertTool, cwd, opts.snapshotCallback), lookupHook, cwd, (result) => hookEnvForInsert(result, cwd), onHook, finalizeWriteResult),
@@ -4969,7 +5312,9 @@ function buildReadOnlyToolSet(opts) {
   const tools = [
     withCwdDefault(globTool, cwd),
     withCwdDefault(grepTool, cwd),
-    withCwdDefault(readTool, cwd)
+    withCwdDefault(readTool, cwd),
+    withCwdDefault(listSkillsTool, cwd),
+    withCwdDefault(readSkillTool, cwd)
   ];
   if (process.env.EXA_API_KEY) {
     tools.push(webSearchTool, webContentTool);
@@ -5182,10 +5527,13 @@ function formatSubagentDiagnostics(stdout, stderr) {
 function createSubagentRunner(cwd, getCurrentModel) {
   const activeProcs = new Set;
   const subagentDepth = Number.parseInt(process.env.MC_SUBAGENT_DEPTH ?? "0", 10);
-  const runSubagent = async (prompt, agentName, modelOverride) => {
+  const runSubagent = async (prompt, agentName, modelOverride, abortSignal) => {
     if (subagentDepth >= MAX_SUBAGENT_DEPTH) {
       throw new Error(`Subagent recursion limit reached (depth ${subagentDepth}). ` + `Cannot spawn another subagent.`);
     }
+    if (abortSignal?.aborted) {
+      throw new DOMException("Subagent execution was interrupted", "AbortError");
+    }
     const model = modelOverride ?? getCurrentModel();
     const cmd = [
       ...getMcCommand(),
@@ -5208,6 +5556,16 @@ function createSubagentRunner(cwd, getCurrentModel) {
       stdio: ["ignore", "pipe", "pipe", "pipe"]
     });
     activeProcs.add(proc);
+    let aborted = false;
+    const onAbort = () => {
+      aborted = true;
+      try {
+        proc.kill("SIGTERM");
+      } catch {}
+    };
+    if (abortSignal) {
+      abortSignal.addEventListener("abort", onAbort);
+    }
     try {
       const [text, stdout, stderr] = await Promise.all([
         Bun.file(proc.stdio[3]).text(),
@@ -5215,6 +5573,9 @@ function createSubagentRunner(cwd, getCurrentModel) {
         consumeTail(proc.stderr),
         proc.exited
       ]);
+      if (aborted || abortSignal?.aborted) {
+        throw new DOMException("Subagent execution was interrupted", "AbortError");
+      }
       const diagnostics = formatSubagentDiagnostics(stdout, stderr);
       const trimmed = text.trim();
       if (!trimmed) {
@@ -5240,7 +5601,15 @@ function createSubagentRunner(cwd, getCurrentModel) {
       if (agentName)
         output.agentName = agentName;
       return output;
+    } catch (error) {
+      if (aborted || abortSignal?.aborted) {
+        throw new DOMException("Subagent execution was interrupted", "AbortError");
+      }
+      throw error;
     } finally {
+      if (abortSignal) {
+        abortSignal.removeEventListener("abort", onAbort);
+      }
       activeProcs.delete(proc);
     }
   };
@@ -5437,7 +5806,7 @@ async function initAgent(opts) {
       runner.planMode = v;
     },
     cwd,
-    runSubagent: (prompt, agentName, model) => runSubagent(prompt, agentName, model),
+    runSubagent: (prompt, agentName, model, abortSignal) => runSubagent(prompt, agentName, model, abortSignal),
     get activeAgent() {
       return activeAgentName;
     },
@@ -5570,9 +5939,9 @@ ${c13.bold("Examples:")}`);
 }
 
 // src/cli/bootstrap.ts
-import { existsSync as existsSync5, mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
-import { homedir as homedir9 } from "os";
-import { join as join11 } from "path";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, writeFileSync as writeFileSync3 } from "fs";
+import { homedir as homedir10 } from "os";
+import { join as join12 } from "path";
 import * as c14 from "yoctocolors";
 var REVIEW_COMMAND_CONTENT = `---
 description: Review recent changes for correctness, code quality, and performance
@@ -5592,9 +5961,9 @@ Perform a sensible code review:
 Output a small summary with only the issues found. If nothing is wrong, say so.
 `;
 function bootstrapGlobalDefaults() {
-  const commandsDir = join11(homedir9(), ".agents", "commands");
-  const reviewPath = join11(commandsDir, "review.md");
-  if (!existsSync5(reviewPath)) {
+  const commandsDir = join12(homedir10(), ".agents", "commands");
+  const reviewPath = join12(commandsDir, "review.md");
+  if (!existsSync6(reviewPath)) {
     mkdirSync5(commandsDir, { recursive: true });
     writeFileSync3(reviewPath, REVIEW_COMMAND_CONTENT, "utf-8");
     writeln(`${c14.green("\u2713")} created ${c14.dim("~/.agents/commands/review.md")} ${c14.dim("(edit it to customise your reviews)")}`);
@@ -5602,26 +5971,35 @@ function bootstrapGlobalDefaults() {
 }
 
 // src/cli/file-refs.ts
-import { join as join12 } from "path";
+import { join as join13 } from "path";
 async function resolveFileRefs(text, cwd) {
   const atPattern = /@([\w./\-_]+)/g;
   let result = text;
   const matches = [...text.matchAll(atPattern)];
   const images = [];
-  const skills = loadSkills(cwd);
+  const skills = loadSkillsIndex(cwd);
+  const loadedSkills = new Map;
   for (const match of [...matches].reverse()) {
     const ref = match[1];
     if (!ref)
       continue;
-    const skill = skills.get(ref);
-    if (skill) {
-      const replacement = `<skill name="${skill.name}">
-${skill.content}
+    const skillMeta = skills.get(ref);
+    if (skillMeta) {
+      let content = loadedSkills.get(skillMeta.name);
+      if (!content) {
+        const loaded2 = loadSkillContentFromMeta(skillMeta);
+        if (!loaded2)
+          continue;
+        content = loaded2.content;
+        loadedSkills.set(skillMeta.name, content);
+      }
+      const replacement = `<skill name="${skillMeta.name}">
+${content}
 </skill>`;
       result = result.slice(0, match.index) + replacement + result.slice((match.index ?? 0) + match[0].length);
       continue;
     }
-    const filePath = ref.startsWith("/") ? ref : join12(cwd, ref);
+    const filePath = ref.startsWith("/") ? ref : join13(cwd, ref);
     if (isImageFilename(ref)) {
       const attachment = await loadImageFile(filePath);
       if (attachment) {
@@ -5668,7 +6046,9 @@ class HeadlessReporter {
           accumulatedText += event.delta;
           break;
         case "reasoning-delta":
-          reasoningText += event.delta;
+          reasoningText += normalizeReasoningDelta(event.delta);
+          break;
+        case "context-pruned":
           break;
         case "turn-complete":
           inputTokens = event.inputTokens;
@@ -5692,7 +6072,7 @@ class HeadlessReporter {
       outputTokens,
       contextTokens,
       newMessages,
-      reasoningText
+      reasoningText: normalizeReasoningText(reasoningText)
     };
   }
   renderStatusBar(_data) {}
@@ -5747,8 +6127,8 @@ async function runShellPassthrough(command, cwd, reporter) {
 import * as c16 from "yoctocolors";
 
 // src/cli/custom-commands.ts
-import { existsSync as existsSync6, readFileSync as readFileSync3 } from "fs";
-import { join as join13 } from "path";
+import { existsSync as existsSync7, readFileSync as readFileSync4 } from "fs";
+import { join as join14 } from "path";
 function loadCustomCommands(cwd, homeDir) {
   return loadMarkdownConfigs({
     type: "commands",
@@ -5805,12 +6185,12 @@ async function expandTemplate(template, args, cwd) {
   const fileMatches = [...result.matchAll(FILE_REF_RE)];
   for (const match of fileMatches) {
     const filePath = match[1] ?? "";
-    const fullPath = join13(cwd, filePath);
-    if (!existsSync6(fullPath))
+    const fullPath = join14(cwd, filePath);
+    if (!existsSync7(fullPath))
       continue;
     let content = "";
     try {
-      content = readFileSync3(fullPath, "utf-8");
+      content = readFileSync4(fullPath, "utf-8");
     } catch {
       continue;
     }
@@ -5870,10 +6250,10 @@ async function handleModel(ctx, args) {
     }
     return;
   }
-  writeln(`${c16.dim("  fetching models\u2026")}`);
+  ctx.startSpinner("fetching models");
   const snapshot = await fetchAvailableModels();
   const models = snapshot.models;
-  process.stdout.write("\x1B[1A\r\x1B[2K");
+  ctx.stopSpinner();
   if (models.length === 0) {
     writeln(`${PREFIX.error} No models found. Check your API keys or Ollama connection.`);
     writeln(c16.dim("  Set OPENCODE_API_KEY for Zen, or start Ollama for local models."));
@@ -6063,14 +6443,14 @@ async function handleMcp(ctx, args) {
     case "add": {
       const [, name, transport, ...rest] = parts;
       if (!name || !transport || rest.length === 0) {
-        writeln(c16.red("  usage: /mcp add <name> http <url>"));
-        writeln(c16.red("         /mcp add <name> stdio <cmd> [args...]"));
+        writeln(`${PREFIX.error} usage: /mcp add <name> http <url>`);
+        writeln(`${PREFIX.error}        /mcp add <name> stdio <cmd> [args...]`);
         return;
       }
       if (transport === "http") {
         const url = rest[0];
         if (!url) {
-          writeln(c16.red("  usage: /mcp add <name> http <url>"));
+          writeln(`${PREFIX.error} usage: /mcp add <name> http <url>`);
           return;
         }
         upsertMcpServer({
@@ -6084,7 +6464,7 @@ async function handleMcp(ctx, args) {
       } else if (transport === "stdio") {
         const [command, ...cmdArgs] = rest;
         if (!command) {
-          writeln(c16.red("  usage: /mcp add <name> stdio <cmd> [args...]"));
+          writeln(`${PREFIX.error} usage: /mcp add <name> stdio <cmd> [args...]`);
           return;
         }
         upsertMcpServer({
@@ -6096,7 +6476,7 @@ async function handleMcp(ctx, args) {
           env: null
         });
       } else {
-        writeln(c16.red(`  unknown transport: ${transport}  (use http or stdio)`));
+        writeln(`${PREFIX.error} unknown transport: ${transport}  (use http or stdio)`);
         return;
       }
       try {
@@ -6111,7 +6491,7 @@ async function handleMcp(ctx, args) {
     case "rm": {
       const [, name] = parts;
       if (!name) {
-        writeln(c16.red("  usage: /mcp remove <name>"));
+        writeln(`${PREFIX.error} usage: /mcp remove <name>`);
         return;
       }
       deleteMcpServer(name);
@@ -6119,7 +6499,7 @@ async function handleMcp(ctx, args) {
       return;
     }
     default:
-      writeln(c16.red(`  unknown: /mcp ${sub}`));
+      writeln(`${PREFIX.error} unknown: /mcp ${sub}`);
       writeln(c16.dim("  subcommands: list \xB7 add \xB7 remove"));
   }
 }
@@ -6138,9 +6518,13 @@ async function handleCustomCommand(cmd, args, ctx) {
   if (!fork) {
     return { type: "inject-user-message", text: prompt };
   }
+  const abortController = new AbortController;
+  const stopWatcher = watchForCancel(abortController, {
+    allowSubagentEsc: true
+  });
   try {
     ctx.startSpinner("subagent");
-    const output = await ctx.runSubagent(prompt, cmd.agent, cmd.model);
+    const output = await ctx.runSubagent(prompt, cmd.agent, cmd.model, abortController.signal);
     write(renderMarkdown(output.result));
     writeln();
     return {
@@ -6152,9 +6536,13 @@ ${output.result}
 <system-message>Summarize the findings above to the user.</system-message>`
     };
   } catch (e) {
+    if (isAbortError(e)) {
+      return { type: "handled" };
+    }
     writeln(`${PREFIX.error} /${cmd.name} failed: ${String(e)}`);
     return { type: "handled" };
   } finally {
+    stopWatcher();
     ctx.stopSpinner();
   }
 }
@@ -6234,10 +6622,10 @@ function handleHelp(ctx, custom) {
       writeln(`  ${c16.magenta(`@${agent.name}`.padEnd(26))} ${c16.dim(agent.description)}${modeTag}${tag}`);
     }
   }
-  const skills = loadSkills(ctx.cwd);
+  const skills = loadSkillsIndex(ctx.cwd);
   if (skills.size > 0) {
     writeln();
-    writeln(c16.dim("  skills  (~/.agents/skills/ or .agents/skills/):"));
+    writeln(c16.dim("  skills  (walk-up local .agents/.claude/skills + global ~/.agents/skills ~/.claude/skills):"));
     for (const skill of skills.values()) {
       const tag = skill.source === "local" ? c16.dim(" (local)") : c16.dim(" (global)");
       writeln(`  ${c16.yellow(`@${skill.name}`.padEnd(26))} ${c16.dim(skill.description)}${tag}`);
@@ -6245,7 +6633,7 @@ function handleHelp(ctx, custom) {
   }
   writeln();
   writeln(`  ${c16.green("@agent".padEnd(26))} ${c16.dim("run prompt through a custom agent (Tab to complete)")}`);
-  writeln(`  ${c16.green("@skill".padEnd(26))} ${c16.dim("inject skill instructions into prompt (Tab to complete)")}`);
+  writeln(`  ${c16.green("@skill".padEnd(26))} ${c16.dim("load a skill body on demand into the prompt (Tab to complete)")}`);
   writeln(`  ${c16.green("@file".padEnd(26))} ${c16.dim("inject file contents into prompt (Tab to complete)")}`);
   writeln(`  ${c16.green("!cmd".padEnd(26))} ${c16.dim("run shell command, output added as context")}`);
   writeln();
@@ -6421,13 +6809,14 @@ ${out}
 }
 
 // src/cli/output-reporter.ts
-import * as c18 from "yoctocolors";
 class CliReporter {
   spinner = new Spinner;
   info(msg) {
+    this.spinner.stop();
     renderInfo(msg);
   }
   error(msg, hint) {
+    this.spinner.stop();
     if (typeof msg === "string") {
       renderError(msg, hint);
     } else {
@@ -6435,9 +6824,11 @@ class CliReporter {
     }
   }
   warn(msg) {
-    writeln(`! ${c18.yellow(msg)}`);
+    this.spinner.stop();
+    writeln(`${G.warn} ${msg}`);
   }
   writeText(text) {
+    this.spinner.stop();
     writeln(text);
   }
   startSpinner(label) {
@@ -6484,7 +6875,7 @@ async function main() {
     if (last) {
       sessionId = last.id;
     } else {
-      writeln(c19.dim("No previous session found, starting fresh."));
+      writeln(c18.dim("No previous session found, starting fresh."));
     }
   } else if (args.sessionId) {
     sessionId = args.sessionId;

package/docs/skills.md

@@ -1,28 +1,48 @@
 # Skills
 
-A skill is a reusable instruction file injected inline into your prompt.
-Use `@skill-name` to load it — the content is inserted into the message
-before it's sent to the LLM.
+Skills are reusable instruction files discovered automatically from local and global directories.
 
-> **Skills are never auto-loaded.** They must be explicitly referenced
-> with `@skill-name` in your prompt. Nothing is injected automatically.
+- The model sees **skill metadata only** by default (name, description, source).
+- Full `SKILL.md` content is loaded **on demand**:
+	- when explicitly requested with the runtime skill tools (`listSkills` / `readSkill`), or
+	- when you reference `@skill-name` in your prompt.
 
-## Where to put them
+## Discovery locations
 
-Each skill is a folder containing a `SKILL.md`:
+Skills live in folders containing `SKILL.md`:
 
 | Location | Scope |
 |---|---|
-| `.agents/skills/<name>/SKILL.md` | Current repo only |
-| `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
-| `.claude/skills/<name>/SKILL.md` | Current repo only (Claude-compatible) |
-| `~/.claude/skills/<name>/SKILL.md` | All projects (global, Claude-compatible) |
+| `.agents/skills/<name>/SKILL.md` | Local |
+| `.claude/skills/<name>/SKILL.md` | Local (Claude-compatible) |
+| `~/.agents/skills/<name>/SKILL.md` | Global |
+| `~/.claude/skills/<name>/SKILL.md` | Global (Claude-compatible) |
 
-Local skills override global ones with the same name. At the same scope, `.agents` wins over `.claude`.
+Local discovery walks up from the current working directory to the git worktree root.
 
-## Create a skill
+## Precedence rules
+
+If multiple skills share the same `name`, precedence is deterministic:
+
+1. Nearest local directory wins over farther ancestor directories.
+2. Any local skill wins over global.
+3. At the same scope/path level, `.agents` wins over `.claude`.
+
+## Frontmatter validation
+
+`SKILL.md` frontmatter must include:
 
-The folder name becomes the skill name (unless overridden by `name:` in frontmatter).
+- `name` (required)
+- `description` (required)
+
+`name` constraints:
+
+- lowercase alphanumeric and hyphen format (`^[a-z0-9]+(?:-[a-z0-9]+)*$`)
+- 1–64 characters
+
+Invalid skills are skipped with warnings. Unknown frontmatter fields are allowed.
+
+## Create a skill
 
 `.agents/skills/conventional-commits/SKILL.md`:
 
@@ -34,40 +54,25 @@ description: Conventional commit message format rules
 
 # Conventional Commits
 
-All commit messages must follow this format:
-
-  <type>(<scope>): <short summary>
-
-Types: feat, fix, docs, refactor, test, chore
-- Summary is lowercase, no period at the end
-- Breaking changes: add `!` after type, e.g. `feat!:`
-- Body is optional, wrapped at 72 chars
+Use:
+<type>(<scope>): <short summary>
 ```
 
-Then in the REPL:
+## Use a skill explicitly
 
-```
+```text
 @conventional-commits write a commit message for my staged changes
 ```
 
-The skill content is wrapped in `<skill name="…">…</skill>` tags and
-included in the message sent to the LLM.
-
-## Frontmatter fields
-
-| Field | Required | Description |
-|---|---|---|
-| `name` | No | Skill name for `@` reference. Defaults to folder name. |
-| `description` | No | Shown in `/help`. Defaults to name. |
-
-## Tab completion
-
-Type `@` and press `Tab` to autocomplete skill names alongside agents and files.
-
-## Listing skills
+`@skill-name` injects the raw skill body wrapped as:
 
+```xml
+<skill name="conventional-commits">
+...
+</skill>
 ```
-/help
-```
 
-Skills are listed in yellow, tagged `(local)` or `(global)`.
+## Tab completion and help
+
+- Type `@` then `Tab` to complete skill names.
+- Run `/help` to list discovered skills with `(local)` / `(global)` tags.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.19",
+	"version": "0.0.20",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",
@@ -19,12 +19,12 @@
 		"jscpd": "jscpd src"
 	},
 	"dependencies": {
-		"@ai-sdk/anthropic": "^3.0.58",
-		"@ai-sdk/google": "^3.0.43",
-		"@ai-sdk/openai": "^3.0.41",
-		"@ai-sdk/openai-compatible": "^2.0.35",
+		"@ai-sdk/anthropic": "^3.0.60",
+		"@ai-sdk/google": "^3.0.51",
+		"@ai-sdk/openai": "^3.0.45",
+		"@ai-sdk/openai-compatible": "^2.0.36",
 		"@modelcontextprotocol/sdk": "^1.27.1",
-		"ai": "^6.0.116",
+		"ai": "^6.0.127",
 		"ignore": "^7.0.5",
 		"yoctocolors": "^2.1.2",
 		"zod": "^4.3.6"