mini-coder 0.0.4 → 0.0.5

package/README.md

@@ -53,7 +53,10 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
 - **Multi-provider** — set `OPENCODE_API_KEY` for Zen, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GOOGLE_API_KEY`, or just run Ollama locally. I auto-discover whatever's available.
 - **Session memory** — conversations are saved in a local SQLite database. Resume where you left off with `-c` or pick a specific session with `-r <id>`.
 - **Shell integration** — prefix with `!` to run shell commands inline. Use `@` to reference files in your prompt (with Tab completion).
-- **Slash commands** — `/model` to switch models, `/plan` for read-only thinking mode, `/ralph` for autonomous looping (agent re-runs your goal with fresh context each iteration until it signals done), `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp` to manage MCP servers.
+- **Slash commands** — `/model` to switch models, `/plan` for read-only thinking mode, `/ralph` for autonomous looping, `/review` for a code review, `/undo` to roll back a turn, `/new` for a clean session, `/mcp` to manage MCP servers. See all with `/help`.
+- **Custom commands** — drop a `.md` file in `.agents/commands/` and it becomes a `/command`. Supports argument placeholders (`$ARGUMENTS`, `$1`…`$9`) and shell interpolation (`` !`cmd` ``). Global commands live in `~/.agents/commands/`. Custom commands take precedence over built-ins. → [docs/custom-commands.md](docs/custom-commands.md)
+- **Custom agents** — drop a `.md` file in `.agents/agents/` (or `~/.agents/agents/` globally) and reference it with `@agent-name` in your prompt. The agent runs in its own context window with a custom system prompt and optional model override. → [docs/custom-agents.md](docs/custom-agents.md)
+- **Skills** — place a `SKILL.md` in `.agents/skills/<name>/` and inject it into any prompt with `@skill-name`. Skills are *never* auto-loaded — always explicit. → [docs/skills.md](docs/skills.md)
 - **Post-tool hooks** — drop an executable at `.agents/hooks/post-<tool>` and I'll run it after every matching tool call.
 - **Beautiful, minimal output** — diffs for edits, formatted trees for file searches, a live status bar with model, git branch, and token counts.
 - **16 ANSI colors only** — my output inherits *your* terminal theme. Dark mode, light mode, Solarized, Gruvbox — I fit right in.
@@ -64,17 +67,35 @@ I can also connect to **MCP servers** (like Exa for web search), giving you supe
 
 - **I eat my own dog food.** I was built *by* a mini-coder agent. It's agents all the way down. 🐢
 - **I'm tiny but mighty.** The whole runtime is [Bun.js](https://bun.com) — fast startup, native TypeScript, and a built-in SQLite driver.
-- **I respect existing conventions.** Hook scripts live in `.agents/hooks/`, context in `AGENTS.md` or `CLAUDE.md` — I follow the ecosystem instead of inventing new standards.
+- **I respect existing conventions.** Hook scripts live in `.agents/hooks/`, context in `AGENTS.md` or `CLAUDE.md`, commands in `.agents/commands/`, agents in `.agents/agents/`, skills in `.agents/skills/` — I follow the ecosystem instead of inventing new standards.
 - **I spin while I think.** ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏ (It's the little things.)
 - **I can clone myself.** The `subagent` tool lets me spin up parallel instances of myself to tackle independent subtasks simultaneously. Divide and conquer! (Up to 3 levels deep.)
 
 ---
 
+## 📁 The `.agents` folder
+
+mini-coder follows the [`.agents` convention](https://github.com/agentsmd/agents) used across the AI coding tool ecosystem. Drop files in `.agents/` to extend behaviour for the current repo, or `~/.agents/` to apply them globally.
+
+| Path | What it does |
+|---|---|
+| `.agents/commands/*.md` | Custom slash commands (`/name`) |
+| `.agents/agents/*.md` | Custom agents (`@name`) |
+| `.agents/skills/<name>/SKILL.md` | Reusable skill instructions (`@name`) |
+| `.agents/hooks/post-<tool>` | Scripts run after a tool call |
+| `AGENTS.md` | Project context injected into every system prompt |
+
+Local always overrides global. The same `~/.agents/` folder is shared with Claude Code, Opencode, and other compatible tools — skills and agents you write once work everywhere.
+
+---
+
+
 ## 🚀 Getting Started
 
 ```bash
-# Install globally
-bun run build && bun add -g mini-coder@file:$(pwd)
+# Install from npm
+bun add -g mini-coder
+# or: npm install -g mini-coder
 
 # Set your provider key (pick one — or run Ollama locally)
 export OPENCODE_API_KEY=your-zen-key    # recommended

package/code-quality-issues.md

@@ -0,0 +1,135 @@
+# Code Quality Issues
+
+## 1. 🔴 Duplicate Code — `parseFrontmatter` tripled across modules
+
+`parseFrontmatter` (including its `Frontmatter` interface, `FM_RE` regex and YAML key-parsing loop) is **copy-pasted verbatim** in three files:
+
+- `src/cli/agents.ts` (lines 20–45)
+- `src/cli/custom-commands.ts` (lines 20–45)
+- `src/cli/skills.ts` has a partial version `parseSkillMeta` that reads `name` and `description` from the same format.
+
+The agents and custom-commands versions are byte-for-byte identical — same regex, same loop, same trim/strip-quotes, same `description`/`model` key handling. The only difference is the struct they populate. Fix: extract into a shared `src/cli/frontmatter.ts` utility and import it in all three.
+
+---
+
+## 2. 🔴 Duplicate Code — `loadFromDir` pattern tripled
+
+The `loadFromDir` function in `agents.ts` and `custom-commands.ts` is essentially the same skeleton: `existsSync` check → `readdirSync` → `.endsWith(".md")` filter → `readFileSync` → `parseFrontmatter` → `Map.set`. The `loadSkills` version differs only in that it looks for `SKILL.md` inside subdirectories instead of `.md` flat files, but the rest of the structure is the same. Same for the public `loadXxx(cwd)` function: three identical "merge global + local, local wins" patterns.
+
+---
+
+## 3. 🔴 Duplicate Code — `homedir()`-based `cwdDisplay` computed in two places in `agent.ts`
+
+```ts
+// buildSystemPrompt (line 98-100)
+const cwdDisplay = cwd.startsWith(homedir())
+    ? `~${cwd.slice(homedir().length)}`
+    : cwd;
+
+// renderStatusBarForSession (line 646-648)
+const cwdDisplay = cwd.startsWith(homedir())
+    ? `~${cwd.slice(homedir().length)}`
+    : cwd;
+```
+
+Also duplicated in `session/manager.ts` (line 53–55) and `cli/output.ts` already has `HOME = homedir()` cached at the top. This pattern should be a small helper function, e.g. `tildePath(p: string): string`.
+
+---
+
+## 4. 🔴 Inlined `import()` calls — violates project rule
+
+The rule says **"Do not inline `import` calls"**. There are 12 occurrences of dynamic inline type imports:
+
+- `src/agent/agent.ts` lines 197, 224, 673 — `import("../tools/subagent.ts").SubagentOutput`, `SubagentToolEntry`, `CoreMessage`
+- `src/agent/tools.ts` line 104 — `import("../tools/subagent.ts").SubagentOutput`
+- `src/cli/commands.ts` line 44 — `import("../tools/subagent.ts").SubagentOutput`
+- `src/cli/output.ts` lines 332, 342, 512, 579, 597 — `SubagentToolEntry`, `SubagentOutput`, `CoreMessage`
+- `src/llm-api/types.ts` line 81 — `import("../llm-api/turn.ts").CoreMessage`
+- `src/llm-api/turn.ts` line 32 — `import("ai").FlexibleSchema<unknown>`
+
+All of these should be top-level `import type` statements.
+
+---
+
+## 5. 🟡 Dead code — `userMessage` in `turn.ts` is never called
+
+`src/llm-api/turn.ts` line 185 exports `userMessage(text: string): CoreMessage`. It is never imported or called anywhere in the codebase. It should be removed.
+
+---
+
+## 6. 🟡 Dead code — `availableProviders` imported but never used
+
+`src/cli/commands.ts` imports `availableProviders` from `providers.ts` (line 3) but it is never referenced anywhere in that file (only `fetchAvailableModels` is used). This is an unused import.
+
+---
+
+## 7. 🟡 Dead code — `saveMessage` (singular) exported but never used
+
+`src/session/db.ts` exports `saveMessage` (single-message variant, line 191). The entire codebase always calls `saveMessages` (plural). `saveMessage` has no callers and should be removed.
+
+---
+
+## 8. 🟡 Dead code — `updateSessionTitle` and `deleteSession` exported but never called
+
+`src/session/db.ts` exports `updateSessionTitle` (line 161) and `deleteSession` (line 185). Neither appears in any other file. They may be future API surface, but currently they are dead exports.
+
+---
+
+## 9. 🟡 Dead code — most of `src/llm-api/types.ts` is orphaned
+
+`ProviderConfig`, `MessageRole`, `TextContent`, `ToolCallContent`, `ToolResultContent`, `MessageContent`, and `Message` are all defined and exported in `types.ts` but **never imported anywhere**. The codebase uses `CoreMessage` from `turn.ts` directly for all message handling. The only things from `types.ts` that are actually used are `ToolDef` and the `TurnEvent` family. The unused types should be removed.
+
+---
+
+## 10. 🟡 Unused import — `relative` in `session/manager.ts`
+
+`src/session/manager.ts` line 2 imports `relative` from `"node:path"` but it is never used anywhere in the file.
+
+---
+
+## 11. 🟡 Unused import — `PREFIX` in `session/manager.ts`
+
+`src/session/manager.ts` line 4 imports `PREFIX` from `"../cli/output.ts"` but it is not used anywhere in the file (only `writeln` and `c` from `yoctocolors` are used in `printSessionList`).
+
+---
+
+## 12. 🟡 Bug-prone — `zenGoogle` ignores its parameter and recreates provider on each call
+
+`providers.ts` line 78: `zenGoogle(modelId: string)` takes `modelId` but only uses it to pass to `createGoogleGenerativeAI` (which doesn't use it — the model ID is passed to the returned function). Also unlike the other zen providers, `zenGoogle` doesn't memoize — it creates a new `createGoogleGenerativeAI` instance on every call. This is inconsistent and wasteful.
+
+---
+
+## 13. 🟡 Minor — double `homedir()` call per `cwdDisplay` computation
+
+In `buildSystemPrompt` and `renderStatusBarForSession` (agent.ts), `homedir()` is called twice inline:
+```ts
+cwd.startsWith(homedir()) ? `~${cwd.slice(homedir().length)}` : cwd
+```
+`homedir()` is cheap but its result is constant — it should be captured once (as `output.ts` already does with `const HOME = homedir()`).
+
+---
+
+## 14. 🟢 Style — `eslint-disable` comments in `mcp/client.ts`
+
+Lines 81 and 88 in `mcp/client.ts` contain `// eslint-disable-next-line @typescript-eslint/no-explicit-any` comments. The project uses Biome, not ESLint — these comments are dead noise and have no effect. They should be removed.
+
+---
+
+## Summary
+
+| # | Severity | File(s) | Issue |
+|---|---|---|---|
+| 1 | 🔴 | `agents.ts`, `custom-commands.ts`, `skills.ts` | `parseFrontmatter` duplicated 3× |
+| 2 | 🔴 | same 3 files | `loadFromDir` + merge pattern duplicated 3× |
+| 3 | 🔴 | `agent.ts` (×2), `manager.ts` | `cwdDisplay` tilde logic duplicated |
+| 4 | 🔴 | 6 files (12 occurrences) | Inlined `import()` type calls — project rule violation |
+| 5 | 🟡 | `turn.ts` | `userMessage` exported but never used |
+| 6 | 🟡 | `commands.ts` | `availableProviders` imported but never used |
+| 7 | 🟡 | `db.ts` | `saveMessage` (singular) exported but never called |
+| 8 | 🟡 | `db.ts` | `updateSessionTitle`, `deleteSession` — dead exports |
+| 9 | 🟡 | `types.ts` | `ProviderConfig`, `Message`, `MessageRole`, etc. — never imported |
+| 10 | 🟡 | `manager.ts` | `relative` imported but not used |
+| 11 | 🟡 | `manager.ts` | `PREFIX` imported but not used |
+| 12 | 🟡 | `providers.ts` | `zenGoogle` doesn't memoize, ignores its parameter |
+| 13 | 🟡 | `agent.ts` | `homedir()` called twice per expression |
+| 14 | 🟢 | `mcp/client.ts` | Dead `eslint-disable` comments (project uses Biome) |

package/dist/mc.js

@@ -5,11 +5,81 @@
 import * as c7 from "yoctocolors";
 
 // src/agent/agent.ts
-import { existsSync as existsSync3, readFileSync as readFileSync2 } from "fs";
-import { homedir as homedir5 } from "os";
-import { join as join11 } from "path";
+import { existsSync as existsSync6, readFileSync as readFileSync5 } from "fs";
+import { join as join14 } from "path";
 import * as c6 from "yoctocolors";
 
+// src/cli/agents.ts
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { homedir } from "os";
+import { basename, join } from "path";
+
+// src/cli/frontmatter.ts
+var FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+function parseFrontmatter(raw) {
+  const m = raw.match(FM_RE);
+  if (!m)
+    return { meta: {}, body: raw };
+  const meta = {};
+  const yamlBlock = m[1] ?? "";
+  for (const line of yamlBlock.split(`
+`)) {
+    const colon = line.indexOf(":");
+    if (colon === -1)
+      continue;
+    const key = line.slice(0, colon).trim();
+    const val = line.slice(colon + 1).trim().replace(/^["']|["']$/g, "");
+    if (key === "name")
+      meta.name = val;
+    if (key === "description")
+      meta.description = val;
+    if (key === "model")
+      meta.model = val;
+  }
+  return { meta, body: (m[2] ?? "").trim() };
+}
+
+// src/cli/agents.ts
+function loadFromDir(dir, source) {
+  const agents = new Map;
+  if (!existsSync(dir))
+    return agents;
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return agents;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const name = basename(entry, ".md");
+    const filePath = join(dir, entry);
+    let raw;
+    try {
+      raw = readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const { meta, body } = parseFrontmatter(raw);
+    agents.set(name, {
+      name,
+      description: meta.description ?? name,
+      ...meta.model ? { model: meta.model } : {},
+      systemPrompt: body,
+      source
+    });
+  }
+  return agents;
+}
+function loadAgents(cwd) {
+  const globalDir = join(homedir(), ".agents", "agents");
+  const localDir = join(cwd, ".agents", "agents");
+  const global = loadFromDir(globalDir, "global");
+  const local = loadFromDir(localDir, "local");
+  return new Map([...global, ...local]);
+}
+
 // src/cli/commands.ts
 import * as c3 from "yoctocolors";
 
@@ -48,6 +118,7 @@ var ZEN_GOOGLE_MODELS = new Set([
 ]);
 var _zenAnthropic = null;
 var _zenOpenAI = null;
+var _zenGoogle = null;
 var _zenCompat = null;
 function getZenApiKey() {
   const key = process.env.OPENCODE_API_KEY;
@@ -73,11 +144,14 @@ function zenOpenAI() {
   }
   return _zenOpenAI;
 }
-function zenGoogle(modelId) {
-  return createGoogleGenerativeAI({
-    apiKey: getZenApiKey(),
-    baseURL: ZEN_BASE
-  });
+function zenGoogle() {
+  if (!_zenGoogle) {
+    _zenGoogle = createGoogleGenerativeAI({
+      apiKey: getZenApiKey(),
+      baseURL: ZEN_BASE
+    });
+  }
+  return _zenGoogle;
 }
 function zenCompat() {
   if (!_zenCompat) {
@@ -153,7 +227,7 @@ function resolveModel(modelString) {
         return zenOpenAI()(modelId);
       }
       if (ZEN_GOOGLE_MODELS.has(modelId)) {
-        return zenGoogle(modelId)(modelId);
+        return zenGoogle()(modelId);
       }
       return zenCompat()(modelId);
     }
@@ -235,17 +309,17 @@ async function fetchAvailableModels() {
 
 // src/session/db.ts
 import { Database } from "bun:sqlite";
-import { existsSync, mkdirSync, unlinkSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
+import { existsSync as existsSync2, mkdirSync, unlinkSync } from "fs";
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
 function getConfigDir() {
-  return join(homedir(), ".config", "mini-coder");
+  return join2(homedir2(), ".config", "mini-coder");
 }
 function getDbPath() {
   const dir = getConfigDir();
-  if (!existsSync(dir))
+  if (!existsSync2(dir))
     mkdirSync(dir, { recursive: true });
-  return join(dir, "sessions.db");
+  return join2(dir, "sessions.db");
 }
 var DB_VERSION = 3;
 var SCHEMA = `
@@ -321,7 +395,7 @@ function getDb() {
         db.close();
       } catch {}
       for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
-        if (existsSync(path))
+        if (existsSync2(path))
           unlinkSync(path);
       }
       db = new Database(dbPath, { create: true });
@@ -471,6 +545,88 @@ function generateSessionId() {
   return `${ts}-${rand}`;
 }
 
+// src/cli/custom-commands.ts
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync as readdirSync2 } from "fs";
+import { homedir as homedir3 } from "os";
+import { basename as basename2, join as join3 } from "path";
+function loadFromDir2(dir, source) {
+  const commands = new Map;
+  if (!existsSync3(dir))
+    return commands;
+  let entries;
+  try {
+    entries = readdirSync2(dir);
+  } catch {
+    return commands;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith(".md"))
+      continue;
+    const name = basename2(entry, ".md");
+    const filePath = join3(dir, entry);
+    let raw;
+    try {
+      raw = readFileSync2(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const { meta, body } = parseFrontmatter(raw);
+    commands.set(name, {
+      name,
+      description: meta.description ?? name,
+      ...meta.model ? { model: meta.model } : {},
+      template: body,
+      source
+    });
+  }
+  return commands;
+}
+function loadCustomCommands(cwd) {
+  const globalDir = join3(homedir3(), ".agents", "commands");
+  const localDir = join3(cwd, ".agents", "commands");
+  const global = loadFromDir2(globalDir, "global");
+  const local = loadFromDir2(localDir, "local");
+  return new Map([...global, ...local]);
+}
+async function expandTemplate(template, args, cwd) {
+  const tokens = args.match(/("([^"]*)")|('([^']*)')|(\S+)/g)?.map((t) => t.replace(/^["']|["']$/g, "")) ?? [];
+  let result = template;
+  for (let i = 9;i >= 1; i--) {
+    result = result.replaceAll(`$${i}`, tokens[i - 1] ?? "");
+  }
+  result = result.replaceAll("$ARGUMENTS", args);
+  const SHELL_RE = /!`([^`]+)`/g;
+  const shellMatches = [...result.matchAll(SHELL_RE)];
+  for (const match of shellMatches) {
+    const cmd = match[1] ?? "";
+    let output = "";
+    try {
+      const signal = AbortSignal.timeout(1e4);
+      const proc = Bun.spawn(["bash", "-c", cmd], {
+        cwd,
+        stdout: "pipe",
+        stderr: "pipe"
+      });
+      await Promise.race([
+        proc.exited,
+        new Promise((_, reject) => signal.addEventListener("abort", () => {
+          proc.kill();
+          reject(new Error("timeout"));
+        }))
+      ]);
+      const [stdout, stderr] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text()
+      ]);
+      const exitCode = proc.exitCode ?? 0;
+      output = exitCode === 0 ? [stdout, stderr].filter(Boolean).join(`
+`).trim() : stdout.trim();
+    } catch {}
+    result = result.replaceAll(match[0], output);
+  }
+  return result;
+}
+
 // src/cli/markdown.ts
 import * as c from "yoctocolors";
 function renderInline(text) {
@@ -584,10 +740,13 @@ function renderChunk(text, inFence) {
 }
 
 // src/cli/output.ts
-import { homedir as homedir2 } from "os";
+import { homedir as homedir4 } from "os";
 import * as c2 from "yoctocolors";
-var HOME = homedir2();
-var PACKAGE_VERSION = "0.0.3";
+var HOME = homedir4();
+var PACKAGE_VERSION = "0.0.4";
+function tildePath(p) {
+  return p.startsWith(HOME) ? `~${p.slice(HOME.length)}` : p;
+}
 function restoreTerminal() {
   try {
     process.stderr.write("\x1B[?25h");
@@ -1209,6 +1368,48 @@ var PREFIX = {
   success: G.ok
 };
 
+// src/cli/skills.ts
+import { existsSync as existsSync4, readFileSync as readFileSync3, readdirSync as readdirSync3, statSync } from "fs";
+import { homedir as homedir5 } from "os";
+import { join as join4 } from "path";
+function loadFromDir3(dir, source) {
+  const skills = new Map;
+  if (!existsSync4(dir))
+    return skills;
+  let entries;
+  try {
+    entries = readdirSync3(dir);
+  } catch {
+    return skills;
+  }
+  for (const entry of entries) {
+    const skillFile = join4(dir, entry, "SKILL.md");
+    try {
+      if (!statSync(join4(dir, entry)).isDirectory())
+        continue;
+      if (!existsSync4(skillFile))
+        continue;
+      const content = readFileSync3(skillFile, "utf-8");
+      const { meta } = parseFrontmatter(content);
+      const name = meta.name ?? entry;
+      skills.set(name, {
+        name,
+        description: meta.description ?? name,
+        content,
+        source
+      });
+    } catch {}
+  }
+  return skills;
+}
+function loadSkills(cwd) {
+  const globalDir = join4(homedir5(), ".agents", "skills");
+  const localDir = join4(cwd, ".agents", "skills");
+  const global = loadFromDir3(globalDir, "global");
+  const local = loadFromDir3(localDir, "local");
+  return new Map([...global, ...local]);
+}
+
 // src/cli/commands.ts
 async function handleModel(ctx, args) {
   if (args) {
@@ -1426,7 +1627,35 @@ function handleNew(ctx) {
   ctx.startNewSession();
   writeln(`${PREFIX.success} ${c3.dim("new session started \u2014 context cleared")}`);
 }
-function handleHelp() {
+async function handleCustomCommand(cmd, args, ctx) {
+  const prompt = await expandTemplate(cmd.template, args, ctx.cwd);
+  const label = c3.cyan(cmd.name);
+  const srcPath = cmd.source === "local" ? `.agents/commands/${cmd.name}.md` : `~/.agents/commands/${cmd.name}.md`;
+  const src = c3.dim(`[${srcPath}]`);
+  writeln(`${PREFIX.info} ${label} ${src}`);
+  writeln();
+  try {
+    const output = await ctx.runSubagent(prompt, cmd.model);
+    if (output.activity.length) {
+      renderSubagentActivity(output.activity, "  ", 1);
+      writeln();
+    }
+    write(renderMarkdown(output.result));
+    writeln();
+    return {
+      type: "inject-user-message",
+      text: `/${cmd.name} output:
+
+${output.result}
+
+<system-message>Summarize the findings above to the user.</system-message>`
+    };
+  } catch (e) {
+    writeln(`${PREFIX.error} /${cmd.name} failed: ${String(e)}`);
+    return { type: "handled" };
+  }
+}
+function handleHelp(ctx, custom) {
   writeln();
   const cmds = [
     ["/model [id]", "list or switch models (fetches live list)"],
@@ -1447,7 +1676,35 @@ function handleHelp() {
   for (const [cmd, desc] of cmds) {
     writeln(`  ${c3.cyan(cmd.padEnd(26))} ${c3.dim(desc)}`);
   }
+  if (custom.size > 0) {
+    writeln();
+    writeln(c3.dim("  custom commands:"));
+    for (const cmd of custom.values()) {
+      const tag = cmd.source === "local" ? c3.dim(" (local)") : c3.dim(" (global)");
+      writeln(`  ${c3.green(`/${cmd.name}`.padEnd(26))} ${c3.dim(cmd.description)}${tag}`);
+    }
+  }
+  const agents = loadAgents(ctx.cwd);
+  if (agents.size > 0) {
+    writeln();
+    writeln(c3.dim("  agents  (~/.agents/agents/ or .agents/agents/):"));
+    for (const agent of agents.values()) {
+      const tag = agent.source === "local" ? c3.dim(" (local)") : c3.dim(" (global)");
+      writeln(`  ${c3.magenta(`@${agent.name}`.padEnd(26))} ${c3.dim(agent.description)}${tag}`);
+    }
+  }
+  const skills = loadSkills(ctx.cwd);
+  if (skills.size > 0) {
+    writeln();
+    writeln(c3.dim("  skills  (~/.agents/skills/ or .agents/skills/):"));
+    for (const skill of skills.values()) {
+      const tag = skill.source === "local" ? c3.dim(" (local)") : c3.dim(" (global)");
+      writeln(`  ${c3.yellow(`@${skill.name}`.padEnd(26))} ${c3.dim(skill.description)}${tag}`);
+    }
+  }
   writeln();
+  writeln(`  ${c3.green("@agent".padEnd(26))} ${c3.dim("run prompt through a custom agent (Tab to complete)")}`);
+  writeln(`  ${c3.green("@skill".padEnd(26))} ${c3.dim("inject skill instructions into prompt (Tab to complete)")}`);
   writeln(`  ${c3.green("@file".padEnd(26))} ${c3.dim("inject file contents into prompt (Tab to complete)")}`);
   writeln(`  ${c3.green("!cmd".padEnd(26))} ${c3.dim("run shell command, output added as context")}`);
   writeln();
@@ -1455,6 +1712,11 @@ function handleHelp() {
   writeln();
 }
 async function handleCommand(command, args, ctx) {
+  const custom = loadCustomCommands(ctx.cwd);
+  const customCmd = custom.get(command.toLowerCase());
+  if (customCmd) {
+    return await handleCustomCommand(customCmd, args, ctx);
+  }
   switch (command.toLowerCase()) {
     case "model":
     case "models":
@@ -1479,15 +1741,16 @@ async function handleCommand(command, args, ctx) {
       return await handleReview(ctx, args);
     case "help":
     case "?":
-      handleHelp();
+      handleHelp(ctx, custom);
       return { type: "handled" };
     case "exit":
     case "quit":
     case "q":
       return { type: "exit" };
-    default:
+    default: {
       writeln(`${PREFIX.error} unknown: /${command}  ${c3.dim("\u2014 /help for commands")}`);
       return { type: "unknown", command };
+    }
   }
 }
 
@@ -1527,7 +1790,7 @@ async function loadImageFile(filePath) {
 }
 
 // src/cli/input.ts
-import { join as join2, relative } from "path";
+import { join as join5, relative } from "path";
 import * as c4 from "yoctocolors";
 var ESC = "\x1B";
 var CSI = `${ESC}[`;
@@ -1556,16 +1819,33 @@ var CTRL_K = "\v";
 var CTRL_L = "\f";
 var CTRL_R = "\x12";
 var TAB = "\t";
-async function getFileCompletions(prefix, cwd) {
+async function getAtCompletions(prefix, cwd) {
   const query = prefix.startsWith("@") ? prefix.slice(1) : prefix;
-  const glob = new Bun.Glob(`**/*${query}*`);
   const results = [];
-  for await (const file of glob.scan({ cwd, onlyFiles: true })) {
-    if (file.includes("node_modules") || file.includes(".git"))
-      continue;
-    results.push(`@${relative(cwd, join2(cwd, file))}`);
-    if (results.length >= 10)
+  const MAX = 10;
+  const skills = loadSkills(cwd);
+  for (const [name] of skills) {
+    if (results.length >= MAX)
+      break;
+    if (name.includes(query))
+      results.push(`@${name}`);
+  }
+  const agents = loadAgents(cwd);
+  for (const [name] of agents) {
+    if (results.length >= MAX)
       break;
+    if (name.includes(query))
+      results.push(`@${name}`);
+  }
+  if (results.length < MAX) {
+    const glob = new Bun.Glob(`**/*${query}*`);
+    for await (const file of glob.scan({ cwd, onlyFiles: true })) {
+      if (file.includes("node_modules") || file.includes(".git"))
+        continue;
+      results.push(`@${relative(cwd, join5(cwd, file))}`);
+      if (results.length >= MAX)
+        break;
+    }
   }
   return results;
 }
@@ -1584,7 +1864,7 @@ async function tryExtractImageFromPaste(pasted, cwd) {
     }
   }
   if (!trimmed.includes(" ") && isImageFilename(trimmed)) {
-    const filePath = trimmed.startsWith("/") ? trimmed : join2(cwd, trimmed);
+    const filePath = trimmed.startsWith("/") ? trimmed : join5(cwd, trimmed);
     const attachment = await loadImageFile(filePath);
     if (attachment) {
       const name = filePath.split("/").pop() ?? trimmed;
@@ -1860,7 +2140,7 @@ async function readline(opts) {
         const beforeCursor = buf.slice(0, cursor);
         const atMatch = beforeCursor.match(/@(\S*)$/);
         if (atMatch) {
-          const completions = await getFileCompletions(atMatch[0], cwd);
+          const completions = await getAtCompletions(atMatch[0], cwd);
           if (completions.length === 1 && completions[0]) {
             const replacement = completions[0];
             buf = buf.slice(0, cursor - (atMatch[0] ?? "").length) + replacement + buf.slice(cursor);
@@ -2104,8 +2384,8 @@ async function connectMcpServer(config) {
 }
 
 // src/tools/snapshot.ts
-import { readFileSync, unlinkSync as unlinkSync2 } from "fs";
-import { join as join3 } from "path";
+import { readFileSync as readFileSync4, unlinkSync as unlinkSync2 } from "fs";
+import { join as join6 } from "path";
 async function gitBytes(args, cwd) {
   try {
     const proc = Bun.spawn(["git", ...args], {
@@ -2196,7 +2476,7 @@ async function takeSnapshot(cwd, sessionId, turnIndex) {
       return false;
     const files = [];
     for (const entry of entries) {
-      const absPath = join3(repoRoot, entry.path);
+      const absPath = join6(repoRoot, entry.path);
       if (!entry.existsOnDisk) {
         const { bytes, code } = await gitBytes(["show", `HEAD:${entry.path}`], repoRoot);
         if (code === 0) {
@@ -2210,7 +2490,7 @@ async function takeSnapshot(cwd, sessionId, turnIndex) {
       }
       if (entry.isNew) {
         try {
-          const content = readFileSync(absPath);
+          const content = readFileSync4(absPath);
           files.push({
             path: entry.path,
             content: new Uint8Array(content),
@@ -2220,7 +2500,7 @@ async function takeSnapshot(cwd, sessionId, turnIndex) {
         continue;
       }
       try {
-        const content = readFileSync(absPath);
+        const content = readFileSync4(absPath);
         files.push({
           path: entry.path,
           content: new Uint8Array(content),
@@ -2245,7 +2525,7 @@ async function restoreSnapshot(cwd, sessionId, turnIndex) {
     const root = repoRoot ?? cwd;
     let anyFailed = false;
     for (const file of files) {
-      const absPath = join3(root, file.path);
+      const absPath = join6(root, file.path);
       if (!file.existed) {
         try {
           if (await Bun.file(absPath).exists()) {
@@ -2274,7 +2554,6 @@ async function restoreSnapshot(cwd, sessionId, turnIndex) {
 }
 
 // src/session/manager.ts
-import { homedir as homedir3 } from "os";
 import * as c5 from "yoctocolors";
 function newSession(model, cwd) {
   const id = generateSessionId();
@@ -2301,7 +2580,7 @@ function printSessionList() {
 ${c5.bold("Recent sessions:")}`);
   for (const s of sessions) {
     const date = new Date(s.updated_at).toLocaleString();
-    const cwd = s.cwd.startsWith(homedir3()) ? `~${s.cwd.slice(homedir3().length)}` : s.cwd;
+    const cwd = tildePath(s.cwd);
     const title = s.title || c5.dim("(untitled)");
     writeln(`  ${c5.dim(s.id.padEnd(14))} ${title.padEnd(30)} ${c5.cyan(s.model.split("/").pop() ?? s.model).padEnd(20)} ${c5.dim(cwd)}  ${c5.dim(date)}`);
   }
@@ -2314,8 +2593,8 @@ function getMostRecentSession() {
 }
 
 // src/tools/create.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2 } from "fs";
-import { dirname, join as join4, relative as relative2 } from "path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync2 } from "fs";
+import { dirname, join as join7, relative as relative2 } from "path";
 import { z as z2 } from "zod";
 
 // src/tools/diff.ts
@@ -2455,10 +2734,10 @@ var createTool = {
   schema: CreateSchema,
   execute: async (input) => {
     const cwd = input.cwd ?? process.cwd();
-    const filePath = input.path.startsWith("/") ? input.path : join4(cwd, input.path);
+    const filePath = input.path.startsWith("/") ? input.path : join7(cwd, input.path);
     const relPath = relative2(cwd, filePath);
     const dir = dirname(filePath);
-    if (!existsSync2(dir))
+    if (!existsSync5(dir))
       mkdirSync2(dir, { recursive: true });
     const file = Bun.file(filePath);
     const created = !await file.exists();
@@ -2470,7 +2749,7 @@ var createTool = {
 };
 
 // src/tools/glob.ts
-import { join as join5, relative as relative3 } from "path";
+import { join as join8, relative as relative3 } from "path";
 import { z as z3 } from "zod";
 var GlobSchema = z3.object({
   pattern: z3.string().describe("Glob pattern to match files against, e.g. '**/*.ts'"),
@@ -2502,7 +2781,7 @@ var globTool = {
       if (ignored)
         continue;
       try {
-        const fullPath = join5(cwd, file);
+        const fullPath = join8(cwd, file);
         const stat = await Bun.file(fullPath).stat?.() ?? null;
         matches.push({ path: file, mtime: stat?.mtime?.getTime() ?? 0 });
       } catch {
@@ -2515,13 +2794,13 @@ var globTool = {
     if (truncated)
       matches.pop();
     matches.sort((a, b) => b.mtime - a.mtime);
-    const files = matches.map((m) => relative3(cwd, join5(cwd, m.path)));
+    const files = matches.map((m) => relative3(cwd, join8(cwd, m.path)));
     return { files, count: files.length, truncated };
   }
 };
 
 // src/tools/grep.ts
-import { join as join6 } from "path";
+import { join as join9 } from "path";
 import { z as z4 } from "zod";
 
 // src/tools/hashline.ts
@@ -2607,7 +2886,7 @@ var grepTool = {
         if (ignoreGlob.some((g) => g.match(relPath) || g.match(relPath.split("/")[0] ?? ""))) {
           continue;
         }
-        const fullPath = join6(cwd, relPath);
+        const fullPath = join9(cwd, relPath);
         let text;
         try {
           text = await Bun.file(fullPath).text();
@@ -2658,8 +2937,8 @@ var grepTool = {
 
 // src/tools/hooks.ts
 import { constants, accessSync } from "fs";
-import { homedir as homedir4 } from "os";
-import { join as join7 } from "path";
+import { homedir as homedir6 } from "os";
+import { join as join10 } from "path";
 function isExecutable(filePath) {
   try {
     accessSync(filePath, constants.X_OK);
@@ -2671,8 +2950,8 @@ function isExecutable(filePath) {
 function findHook(toolName, cwd) {
   const scriptName = `post-${toolName}`;
   const candidates = [
-    join7(cwd, ".agents", "hooks", scriptName),
-    join7(homedir4(), ".agents", "hooks", scriptName)
+    join10(cwd, ".agents", "hooks", scriptName),
+    join10(homedir6(), ".agents", "hooks", scriptName)
   ];
   for (const p of candidates) {
     if (isExecutable(p))
@@ -2761,7 +3040,7 @@ function hookEnvForRead(input, cwd) {
 }
 
 // src/tools/insert.ts
-import { join as join8, relative as relative4 } from "path";
+import { join as join11, relative as relative4 } from "path";
 import { z as z5 } from "zod";
 var InsertSchema = z5.object({
   path: z5.string().describe("File path to edit (absolute or relative to cwd)"),
@@ -2776,7 +3055,7 @@ var insertTool = {
   schema: InsertSchema,
   execute: async (input) => {
     const cwd = input.cwd ?? process.cwd();
-    const filePath = input.path.startsWith("/") ? input.path : join8(cwd, input.path);
+    const filePath = input.path.startsWith("/") ? input.path : join11(cwd, input.path);
     const relPath = relative4(cwd, filePath);
     const file = Bun.file(filePath);
     if (!await file.exists()) {
@@ -2821,7 +3100,7 @@ function parseAnchor(value) {
 }
 
 // src/tools/read.ts
-import { join as join9, relative as relative5 } from "path";
+import { join as join12, relative as relative5 } from "path";
 import { z as z6 } from "zod";
 var ReadSchema = z6.object({
   path: z6.string().describe("File path to read (absolute or relative to cwd)"),
@@ -2836,7 +3115,7 @@ var readTool = {
   schema: ReadSchema,
   execute: async (input) => {
     const cwd = input.cwd ?? process.cwd();
-    const filePath = input.path.startsWith("/") ? input.path : join9(cwd, input.path);
+    const filePath = input.path.startsWith("/") ? input.path : join12(cwd, input.path);
     const file = Bun.file(filePath);
     const exists = await file.exists();
     if (!exists) {
@@ -2869,7 +3148,7 @@ var readTool = {
 };
 
 // src/tools/replace.ts
-import { join as join10, relative as relative6 } from "path";
+import { join as join13, relative as relative6 } from "path";
 import { z as z7 } from "zod";
 var ReplaceSchema = z7.object({
   path: z7.string().describe("File path to edit (absolute or relative to cwd)"),
@@ -2884,7 +3163,7 @@ var replaceTool = {
   schema: ReplaceSchema,
   execute: async (input) => {
     const cwd = input.cwd ?? process.cwd();
-    const filePath = input.path.startsWith("/") ? input.path : join10(cwd, input.path);
+    const filePath = input.path.startsWith("/") ? input.path : join13(cwd, input.path);
     const relPath = relative6(cwd, filePath);
     const file = Bun.file(filePath);
     if (!await file.exists()) {
@@ -3025,15 +3304,19 @@ var shellTool = {
 // src/tools/subagent.ts
 import { z as z9 } from "zod";
 var SubagentInput = z9.object({
-  prompt: z9.string().describe("The task or question to give the subagent")
+  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.")
 });
-function createSubagentTool(runSubagent) {
+function createSubagentTool(runSubagent, availableAgents) {
+  const agentSection = availableAgents.size > 0 ? `
+
+When the user's message contains @<agent-name>, delegate to that agent by setting agentName to the exact agent name. Available custom agents: ${[...availableAgents.entries()].map(([name, cfg]) => `"${name}" (${cfg.description})`).join(", ")}.` : "";
   return {
     name: "subagent",
-    description: "Spawn a sub-agent to handle a focused subtask. " + "Use this for parallel exploration, specialised analysis, or tasks that benefit from " + "a fresh context window. The subagent has access to all the same tools.",
+    description: `Spawn a sub-agent to handle a focused subtask. Use this for parallel exploration, specialised analysis, or tasks that benefit from a fresh context window. The subagent has access to all the same tools.${agentSection}`,
     schema: SubagentInput,
     execute: async (input) => {
-      return runSubagent(input.prompt);
+      return runSubagent(input.prompt, input.agentName);
     }
   };
 }
@@ -3090,12 +3373,12 @@ function buildToolSet(opts) {
     withHooks(withCwdDefault(replaceTool, cwd), lookupHook, cwd, (result) => hookEnvForReplace(result, cwd), onHook),
     withHooks(withCwdDefault(insertTool, cwd), lookupHook, cwd, (result) => hookEnvForInsert(result, cwd), onHook),
     withHooks(withCwdDefault(shellTool, cwd), lookupHook, cwd, (result, input) => hookEnvForShell(result, input, cwd), onHook),
-    createSubagentTool(async (prompt) => {
+    createSubagentTool(async (prompt, agentName) => {
       if (depth >= MAX_SUBAGENT_DEPTH) {
         throw new Error(`Subagent depth limit reached (max ${MAX_SUBAGENT_DEPTH}). ` + `Cannot spawn another subagent from depth ${depth}.`);
       }
-      return opts.runSubagent(prompt, depth + 1);
-    })
+      return opts.runSubagent(prompt, depth + 1, agentName);
+    }, opts.availableAgents)
   ];
 }
 function buildReadOnlyToolSet(opts) {
@@ -3126,14 +3409,14 @@ async function getGitBranch(cwd) {
 }
 function loadContextFile(cwd) {
   const candidates = [
-    join11(cwd, "AGENTS.md"),
-    join11(cwd, "CLAUDE.md"),
-    join11(getConfigDir(), "AGENTS.md")
+    join14(cwd, "AGENTS.md"),
+    join14(cwd, "CLAUDE.md"),
+    join14(getConfigDir(), "AGENTS.md")
   ];
   for (const p of candidates) {
-    if (existsSync3(p)) {
+    if (existsSync6(p)) {
       try {
-        return readFileSync2(p, "utf-8");
+        return readFileSync5(p, "utf-8");
       } catch {}
     }
   }
@@ -3141,7 +3424,7 @@ function loadContextFile(cwd) {
 }
 function buildSystemPrompt(cwd) {
   const contextFile = loadContextFile(cwd);
-  const cwdDisplay = cwd.startsWith(homedir5()) ? `~${cwd.slice(homedir5().length)}` : cwd;
+  const cwdDisplay = tildePath(cwd);
   const now = new Date().toLocaleString(undefined, { hour12: false });
   let prompt = `You are mini-coder, a small and fast CLI coding agent.
 You have access to tools to read files, search code, make edits, run shell commands, and spawn subagents.
@@ -3205,16 +3488,23 @@ async function runAgent(opts) {
   }
   let turnIndex = getMaxTurnIndex(session.id) + 1;
   const coreHistory = [...session.messages];
-  const runSubagent = async (prompt, depth = 0) => {
+  const runSubagent = async (prompt, depth = 0, agentName, modelOverride) => {
+    const allAgents = loadAgents(cwd);
+    const agentConfig = agentName ? allAgents.get(agentName) : undefined;
+    if (agentName && !agentConfig) {
+      throw new Error(`Unknown agent "${agentName}". Available agents: ${[...allAgents.keys()].join(", ") || "(none)"}`);
+    }
+    const model = modelOverride ?? agentConfig?.model ?? currentModel;
+    const systemPrompt = agentConfig?.systemPrompt ?? buildSystemPrompt(cwd);
     const subMessages = [{ role: "user", content: prompt }];
     const subTools = buildToolSet({
       cwd,
       depth,
       runSubagent,
-      onHook: renderHook
+      onHook: renderHook,
+      availableAgents: allAgents
     });
-    const subLlm = resolveModel(currentModel);
-    const systemPrompt = buildSystemPrompt(cwd);
+    const subLlm = resolveModel(model);
     let result = "";
     let inputTokens = 0;
     let outputTokens = 0;
@@ -3254,11 +3544,13 @@ async function runAgent(opts) {
     }
     return { result, inputTokens, outputTokens, activity };
   };
+  const agents = loadAgents(cwd);
   const tools = buildToolSet({
     cwd,
     depth: 0,
     runSubagent,
-    onHook: renderHook
+    onHook: renderHook,
+    availableAgents: agents
   });
   const mcpTools = [];
   async function connectAndAddMcp(name) {
@@ -3310,7 +3602,7 @@ async function runAgent(opts) {
       planMode = v;
     },
     cwd,
-    runSubagent: (prompt) => runSubagent(prompt),
+    runSubagent: (prompt, model) => runSubagent(prompt, 0, undefined, model),
     undoLastTurn: async () => {
       if (session.messages.length === 0)
         return false;
@@ -3526,7 +3818,7 @@ ${out}
     const branch = await getGitBranch(cwd);
     const provider = currentModel.split("/")[0] ?? "";
     const modelShort = currentModel.split("/").slice(1).join("/");
-    const cwdDisplay = cwd.startsWith(homedir5()) ? `~${cwd.slice(homedir5().length)}` : cwd;
+    const cwdDisplay = tildePath(cwd);
     renderStatusBar({
       model: modelShort,
       provider,
@@ -3567,11 +3859,20 @@ async function resolveFileRefs(text, cwd) {
   let result = text;
   const matches = [...text.matchAll(atPattern)];
   const images = [];
-  for (const match of matches.reverse()) {
+  const skills = loadSkills(cwd);
+  for (const match of [...matches].reverse()) {
     const ref = match[1];
     if (!ref)
       continue;
-    const filePath = ref.startsWith("/") ? ref : join11(cwd, ref);
+    const skill = skills.get(ref);
+    if (skill) {
+      const replacement = `<skill name="${skill.name}">
+${skill.content}
+</skill>`;
+      result = result.slice(0, match.index) + replacement + result.slice((match.index ?? 0) + match[0].length);
+      continue;
+    }
+    const filePath = ref.startsWith("/") ? ref : join14(cwd, ref);
     if (isImageFilename(ref)) {
       const attachment = await loadImageFile(filePath);
       if (attachment) {

package/docs/custom-agents.md

@@ -0,0 +1,70 @@
+# Custom Agents
+
+An agent is a subagent with a custom system prompt and optional model override.
+Use `@agent-name` anywhere in your prompt to route the message through it.
+
+## Where to put them
+
+| Location | Scope |
+|---|---|
+| `.agents/agents/*.md` | Current repo only |
+| `~/.agents/agents/*.md` | All projects (global) |
+
+Local agents override global ones with the same name.
+
+## Create an agent
+
+The filename becomes the agent name.
+
+`~/.agents/agents/reviewer.md`:
+
+```md
+---
+description: Strict code reviewer focused on bugs and structure
+model: zen/claude-sonnet-4-6
+---
+
+You are a senior engineer doing a code review. Be direct and specific.
+Cite file and line number for every finding. Flag bugs first, then
+structure issues, then style — only if they violate project conventions.
+No flattery. End with a one-line verdict.
+```
+
+Then in the REPL:
+
+```
+@reviewer review the auth module for race conditions
+```
+
+The rest of the message (everything except the `@reviewer` token) becomes
+the prompt. The agent runs in its own context window and returns its output
+into the conversation.
+
+## Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `description` | No | Shown in `/help`. Defaults to filename. |
+| `model` | No | Override the active model for this agent. |
+
+The markdown body (after frontmatter) is the agent's system prompt.
+
+## Combining with files
+
+`@file` references are resolved before the agent fires:
+
+```
+@reviewer @src/auth/session.ts check this file for issues
+```
+
+## Tab completion
+
+Type `@` and press `Tab` to autocomplete agent names alongside files.
+
+## Listing agents
+
+```
+/help
+```
+
+Agents are listed in magenta, tagged `(local)` or `(global)`.

package/docs/custom-commands.md

@@ -0,0 +1,133 @@
+# Custom Commands
+
+Custom commands let you define reusable prompts that run as `/command` in the mini-coder REPL.
+
+## Where to put them
+
+| Location | Scope |
+|---|---|
+| `.agents/commands/*.md` | Current repo only |
+| `~/.agents/commands/*.md` | All projects (global) |
+
+Local commands override global ones with the same name.
+
+## Create a command
+
+Create a markdown file. The filename becomes the command name.
+
+`.agents/commands/standup.md`:
+
+```md
+---
+description: Summarise what changed since yesterday
+model: zen/claude-3-5-haiku
+---
+
+Run `!`git log --oneline --since=yesterday`` and summarise the changes
+as a short standup update. Group by theme, skip merge commits.
+```
+
+Then in the REPL:
+
+```
+/standup
+```
+
+## Frontmatter fields
+
+| Field | Required | Description |
+|---|---|---|
+| `description` | No | Shown in `/help`. Defaults to the command name. |
+| `model` | No | Override the active model for this command. |
+
+## Arguments
+
+Use `$ARGUMENTS` for the full argument string, or `$1`, `$2`, … `$9` for individual tokens.
+
+`.agents/commands/search.md`:
+
+```md
+---
+description: Search the codebase for a topic
+model: zen/claude-3-5-haiku
+---
+
+Search the codebase for: $ARGUMENTS
+
+Use glob, grep, and read tools to explore thoroughly. Report all
+relevant files, key code snippets with line numbers, and a short summary.
+Be exhaustive but concise. No edits — read only.
+```
+
+```
+/search session management
+/search error handling in providers
+```
+
+Positional tokens:
+
+```md
+---
+description: Create a new component
+---
+
+Create a React component named $1 in the $2 directory.
+Use TypeScript, include prop types and a default export.
+```
+
+```
+/component Button src/ui
+```
+
+## Shell interpolation
+
+Use `` !`cmd` `` to inject shell output into the prompt at expansion time.
+Commands time out after 10 seconds.
+
+```md
+---
+description: Review failing tests
+---
+
+The following tests are currently failing:
+
+!`bun test 2>&1 | grep "fail\|✗" | head -20`
+
+Investigate the failures and suggest fixes. Read the relevant source
+files before drawing conclusions.
+```
+
+```
+/fix-tests
+```
+
+## Model override
+
+Specify a model in frontmatter to use a faster or cheaper model for
+lightweight tasks regardless of what the session is currently set to.
+
+```md
+---
+description: Quick grep for a symbol
+model: zen/claude-3-5-haiku
+---
+
+Find all usages of $ARGUMENTS across the codebase using grep and glob.
+List each occurrence with file path and line number. No explanations needed.
+```
+
+Large models for deep analysis, small models for search and lookup.
+
+## Precedence
+
+Custom commands shadow built-ins. If you create `.agents/commands/review.md`
+it will replace the built-in `/review` for that project.
+
+## Listing commands
+
+```
+/help
+```
+
+Custom commands are listed at the bottom under **custom commands**, tagged
+with `(local)` or `(global)`.

package/docs/skills.md

@@ -0,0 +1,71 @@
+# 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 never auto-loaded.** They must be explicitly referenced
+> with `@skill-name` in your prompt. Nothing is injected automatically.
+
+## Where to put them
+
+Each skill is a folder containing a `SKILL.md`:
+
+| Location | Scope |
+|---|---|
+| `.agents/skills/<name>/SKILL.md` | Current repo only |
+| `~/.agents/skills/<name>/SKILL.md` | All projects (global) |
+
+Local skills override global ones with the same name.
+
+## Create a skill
+
+The folder name becomes the skill name (unless overridden by `name:` in frontmatter).
+
+`.agents/skills/conventional-commits/SKILL.md`:
+
+```md
+---
+name: conventional-commits
+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
+```
+
+Then in the REPL:
+
+```
+@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 files.
+
+## Listing skills
+
+```
+/help
+```
+
+Skills are listed in yellow, tagged `(local)` or `(global)`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mini-coder",
-	"version": "0.0.4",
+	"version": "0.0.5",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",