mini-coder 0.0.3 → 0.0.5

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sean Caetano Martin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

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.3",
+	"version": "0.0.5",
 	"description": "A small, fast CLI coding agent",
 	"module": "src/index.ts",
 	"type": "module",
@@ -30,5 +30,6 @@
 		"@biomejs/biome": "^1.9.4",
 		"@types/bun": "latest",
 		"typescript": "^5.8.3"
-	}
+	},
+	"license": "MIT"
 }