@matterailab/orbcode 0.2.1 → 0.2.3

package/dist/mcp/manager.js

@@ -0,0 +1,277 @@
+import { callMcpTool, connectMcpServer } from "./client.js";
+import { configPathForScope, loadMcpConfig } from "./config.js";
+import { hasStoredAuth, isOAuthConfig } from "./auth.js";
+/**
+ * Owns the lifecycle of all MCP server connections for a session.
+ *
+ * On `start()`, it loads the merged config, filters by the enabled/disabled
+ * lists, connects to each enabled server in parallel, and exposes the union of
+ * their tools as OpenAI-compatible tool definitions. The agent calls
+ * `callTool()` for any `mcp__*` tool name; unknown names return an error.
+ */
+export class McpManager {
+    cwd;
+    connections = new Map();
+    configs = new Map();
+    states = new Map();
+    /** server names the user has explicitly disabled (persisted in settings). */
+    disabled;
+    /** server names the user has explicitly enabled (for unapproved project servers). */
+    enabled;
+    /** project-scope server names that require user approval before connecting. */
+    pendingApproval = new Set();
+    started = false;
+    constructor(cwd, disabled, enabled) {
+        this.cwd = cwd;
+        this.disabled = new Set(disabled);
+        this.enabled = new Set(enabled);
+    }
+    /** Load config and connect to all approved, non-disabled servers. */
+    async start() {
+        if (this.started)
+            return this.snapshot();
+        this.started = true;
+        const { servers } = loadMcpConfig(this.cwd);
+        this.configs.clear();
+        this.states.clear();
+        for (const [name, cfg] of Object.entries(servers)) {
+            this.configs.set(name, cfg);
+            this.states.set(name, {
+                name,
+                scope: cfg.scope,
+                status: "disabled",
+                toolCount: 0,
+                disabled: this.disabled.has(name),
+                detail: undefined,
+            });
+        }
+        // Project-scope servers need explicit approval (they ship in the repo).
+        // User/local-scope servers are trusted (the user wrote them).
+        const toConnect = [];
+        for (const [name, cfg] of this.configs) {
+            if (this.disabled.has(name))
+                continue;
+            if (cfg.scope === "project" && !this.enabled.has(name)) {
+                this.pendingApproval.add(name);
+                this.states.get(name).status = "disabled";
+                this.states.get(name).detail = "awaiting approval";
+                continue;
+            }
+            toConnect.push(name);
+        }
+        // At startup, skip the OAuth browser flow for servers with no stored
+        // tokens — mark them needs-auth so the user can auth explicitly from /mcp.
+        await Promise.all(toConnect.map((name) => this.connectOne(name, { skipUnauthOAuth: true })));
+        return this.snapshot();
+    }
+    /** Connect (or reconnect) a single server by name.
+     *  When `skipUnauthOAuth` is set, OAuth servers with no stored tokens are
+     *  marked needs-auth instead of opening a browser (used at startup).
+     *  When `authIntercept` is provided, the caller controls the OAuth UI
+     *  (surfacing the auth URL, providing the code via callback or paste).
+     *  When `forceOAuth` is set, an http/sse server without an explicit `oauth`
+     *  config is treated as `oauth: true` (auto-detected OAuth — used when the
+     *  user triggers auth after a 401). */
+    async connectOne(name, options) {
+        const cfg = this.configs.get(name);
+        if (!cfg)
+            return;
+        const state = this.states.get(name);
+        const isRemote = cfg.type === "http" || cfg.type === "sse";
+        // At startup, don't open a browser for OAuth servers that haven't been
+        // authenticated yet — surface them as needs-auth so the user can trigger
+        // auth explicitly from the /mcp picker. This applies to both explicitly
+        // configured OAuth servers and any remote server (which may require OAuth
+        // we don't know about yet — we'll find out on the first connect attempt).
+        if (options?.skipUnauthOAuth && isOAuthConfig(cfg) && !hasStoredAuth(name)) {
+            state.status = "needs-auth";
+            state.detail = "not authenticated — press a to authenticate";
+            return;
+        }
+        state.status = "connecting";
+        state.detail = undefined;
+        try {
+            const { scope: _scope, ...serverConfig } = cfg;
+            // Auto-detect: if forceOAuth is set and this is a remote server without
+            // explicit oauth config, inject oauth: true so the auth transport is used.
+            if (options?.forceOAuth && isRemote && !isOAuthConfig(cfg)) {
+                ;
+                serverConfig.oauth = true;
+            }
+            const connection = await connectMcpServer(name, serverConfig, options?.authIntercept);
+            this.connections.set(name, connection);
+            state.status = "connected";
+            state.toolCount = connection.tools.length;
+            state.detail = `${connection.tools.length} tool${connection.tools.length === 1 ? "" : "s"}`;
+            this.pendingApproval.delete(name);
+        }
+        catch (error) {
+            const msg = error.message;
+            // Any remote server that returns 401/unauthorized/invalid_token needs
+            // auth — surface as needs-auth regardless of whether `oauth` was
+            // explicitly configured (auto-detection, like Claude Code).
+            if (isRemote && /unauthorized|auth|401|oauth|invalid_token/i.test(msg)) {
+                state.status = "needs-auth";
+                state.detail = "authentication required — press a to authenticate";
+            }
+            else {
+                state.status = "failed";
+                state.detail = msg;
+            }
+        }
+    }
+    /** Disconnect a single server (keeps config; marks it disabled). */
+    async disconnectOne(name) {
+        const connection = this.connections.get(name);
+        if (connection) {
+            await connection.close();
+            this.connections.delete(name);
+        }
+        const state = this.states.get(name);
+        if (state) {
+            state.status = "disabled";
+            state.toolCount = 0;
+            state.detail = undefined;
+        }
+    }
+    /** Enable a project server (approving it) and connect. Uses
+     *  skipUnauthOAuth so enabling doesn't open a browser — the user auths
+     *  explicitly from /mcp. */
+    async enableServer(name) {
+        this.enabled.add(name);
+        this.disabled.delete(name);
+        const state = this.states.get(name);
+        if (state)
+            state.disabled = false;
+        await this.connectOne(name, { skipUnauthOAuth: true });
+    }
+    /** Disable a server and disconnect it. */
+    async disableServer(name) {
+        this.disabled.add(name);
+        this.enabled.delete(name);
+        const state = this.states.get(name);
+        if (state)
+            state.disabled = true;
+        await this.disconnectOne(name);
+    }
+    /** Re-authenticate a server in the needs-auth state: disconnect, clear
+     *  persisted OAuth tokens, then reconnect with `forceOAuth` so even servers
+     *  without an explicit `oauth` config use the OAuth flow (auto-detect).
+     *  The `authIntercept` lets the TUI surface the auth URL and provide the
+     *  code via callback or paste. */
+    async reauthServer(name, authIntercept) {
+        await this.disconnectOne(name);
+        try {
+            const fs = await import("node:fs");
+            const path = await import("node:path");
+            const { getConfigDir } = await import("../config/settings.js");
+            fs.unlinkSync(path.join(getConfigDir(), "mcp-auth", `${name}.json`));
+        }
+        catch {
+            // best-effort; no stored tokens to clear
+        }
+        this.disabled.delete(name);
+        await this.connectOne(name, { authIntercept, forceOAuth: true });
+    }
+    /** Close every connection. Call on session end / exit. */
+    async stop() {
+        await Promise.all([...this.connections.values()].map((c) => c.close().catch(() => { })));
+        this.connections.clear();
+        this.started = false;
+    }
+    /** All tools from all connected servers, as OpenAI tool definitions. */
+    getTools() {
+        const tools = [];
+        for (const connection of this.connections.values()) {
+            for (const tool of connection.tools) {
+                tools.push({
+                    type: "function",
+                    function: {
+                        name: tool.name,
+                        description: tool.description ?? `MCP tool ${tool.originalName} from server ${tool.server}`,
+                        parameters: tool.inputSchema ?? {
+                            type: "object",
+                            properties: {},
+                        },
+                    },
+                });
+            }
+        }
+        return tools;
+    }
+    /** Route an `mcp__<server>__<tool>` call to the right connection. */
+    async callTool(toolName, args) {
+        const match = /^mcp__([^_]+)__(.+)$/.exec(toolName);
+        if (!match) {
+            return { text: `Invalid MCP tool name: ${toolName}`, isError: true };
+        }
+        const [, server, originalName] = match;
+        const connection = this.connections.get(server);
+        if (!connection) {
+            return { text: `MCP server "${server}" is not connected.`, isError: true };
+        }
+        try {
+            return await callMcpTool(connection, originalName, args);
+        }
+        catch (error) {
+            return { text: `MCP tool ${toolName} failed: ${error.message}`, isError: true };
+        }
+    }
+    /** True if `toolName` is an MCP tool managed by this manager. */
+    hasTool(toolName) {
+        return /^mcp__[^_]+__/.test(toolName);
+    }
+    /** Current snapshot for the TUI / status display. */
+    snapshot() {
+        return {
+            servers: [...this.states.values()],
+            tools: [...this.connections.values()].flatMap((c) => c.tools),
+        };
+    }
+    /** Project-scope server names awaiting the user's approval. */
+    getPendingApproval() {
+        return [...this.pendingApproval];
+    }
+    /** Persisted enabled list (for saving to settings). */
+    getEnabled() {
+        return [...this.enabled];
+    }
+    /** Persisted disabled list (for saving to settings). */
+    getDisabled() {
+        return [...this.disabled];
+    }
+    /** All configured server names. */
+    getServerNames() {
+        return [...this.configs.keys()];
+    }
+    /** A config by name (for the TUI detail view). */
+    getConfig(name) {
+        return this.configs.get(name);
+    }
+    /** The file path where a server's config lives (for the TUI detail view). */
+    getConfigPath(name) {
+        const cfg = this.configs.get(name);
+        if (!cfg)
+            return undefined;
+        return configPathForScope(this.cwd, cfg.scope);
+    }
+    /** True if a server uses OAuth (explicitly configured or auto-detected from
+     *  a 401/needs-auth state). Remote servers in needs-auth state are treated
+     *  as OAuth so the detail panel shows "not authenticated". */
+    isOAuthServer(name) {
+        const cfg = this.configs.get(name);
+        if (!cfg)
+            return false;
+        if (isOAuthConfig(cfg))
+            return true;
+        // Auto-detect: a remote server in needs-auth state requires OAuth.
+        const state = this.states.get(name);
+        if (state?.status === "needs-auth" && (cfg.type === "http" || cfg.type === "sse"))
+            return true;
+        return false;
+    }
+    /** True if a server has persisted OAuth tokens (already authenticated). */
+    isAuthenticated(name) {
+        return hasStoredAuth(name);
+    }
+}

package/dist/mcp/types.js

@@ -0,0 +1,8 @@
+/**
+ * MCP server configuration and connection types.
+ *
+ * These are OrbCode's own types (not re-exported from the SDK) so the config
+ * layer stays decoupled from the SDK's internal schema shape. The connection
+ * manager converts these into SDK transports/clients.
+ */
+export {};

package/dist/memory/loader.js

@@ -0,0 +1,167 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * AGENTS.md memory loader.
+ *
+ * OrbCode's memory system mirrors Claude Code's CLAUDE.md discovery, but uses
+ * the open `AGENTS.md` filename (the cross-tool standard) instead of a
+ * vendor-specific name. Files are loaded in this order (lowest precedence
+ * first), with closer-to-cwd and higher-precedence types winning:
+ *
+ *   1. User memory:   ~/.orbcode/AGENTS.md
+ *   2. Project memory: AGENTS.md and .orbcode/AGENTS.md in cwd and every
+ *      parent directory (closer-to-cwd wins)
+ *   3. Local memory:   AGENTS.local.md in cwd and parents (highest precedence)
+ *
+ * Memory files support `@path` include directives (relative, `~/`, or
+ * absolute) to pull in other files. Includes are resolved recursively up to a
+ * small depth limit, with cycle detection.
+ */
+const MAX_INCLUDE_DEPTH = 5;
+const MAX_TOTAL_CHARS = 200_000;
+/** Read a file as UTF-8, returning undefined if it's missing or unreadable. */
+function readText(filePath) {
+    try {
+        return fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Resolve an @include path relative to the including file's directory. */
+function resolveInclude(ref, baseDir) {
+    if (ref.startsWith("~/"))
+        return path.join(os.homedir(), ref.slice(2));
+    if (path.isAbsolute(ref))
+        return ref;
+    return path.resolve(baseDir, ref);
+}
+/**
+ * Extract `@path` references from leaf text (not inside code spans/blocks).
+ * A simple, conservative parser: skips fenced code blocks and inline code.
+ */
+function extractIncludes(content, baseDir) {
+    const refs = [];
+    let inFence = false;
+    for (const line of content.split(/\r?\n/)) {
+        if (/^```/.test(line.trim())) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        // Strip inline code spans before scanning for @refs.
+        const stripped = line.replace(/`[^`]*`/g, "");
+        const regex = /(?:^|\s)@((?:\.\/|~\/|\/)?[^\s]+)/g;
+        let match;
+        while ((match = regex.exec(stripped)) !== null) {
+            const ref = match[1].replace(/\\ /g, " ");
+            // Avoid matching emails, @mentions, etc.
+            if (!/^[A-Za-z0-9._~/-]/.test(ref))
+                continue;
+            refs.push(resolveInclude(ref, baseDir));
+        }
+    }
+    return refs;
+}
+/** Recursively load a memory file and all its @includes. */
+function loadWithIncludes(filePath, type, processed, depth) {
+    const real = safeRealpath(filePath);
+    if (processed.has(real) || depth >= MAX_INCLUDE_DEPTH)
+        return [];
+    const raw = readText(filePath);
+    if (raw === undefined)
+        return [];
+    processed.add(real);
+    const baseDir = path.dirname(filePath);
+    const includePaths = extractIncludes(raw, baseDir);
+    const results = [];
+    // Includes come first (so they appear before the including file's content).
+    for (const includePath of includePaths) {
+        results.push(...loadWithIncludes(includePath, type, processed, depth + 1));
+    }
+    results.push({ path: filePath, content: raw, type });
+    return results;
+}
+/** realpathSync that never throws (falls back to the input path). */
+function safeRealpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+/** Walk from cwd up to root, collecting directories (root last). */
+function ancestorDirs(cwd) {
+    const dirs = [];
+    let current = path.resolve(cwd);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        dirs.push(current);
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Load all AGENTS.md memory files, in precedence order (lowest first). The
+ * caller concatenates them in order so higher-precedence files appear last
+ * (and thus get more weight from the model).
+ */
+export function loadMemoryFiles(cwd = process.cwd()) {
+    const processed = new Set();
+    const files = [];
+    // 1. User memory (~/.orbcode/AGENTS.md)
+    files.push(...loadWithIncludes(path.join(getConfigDir(), "AGENTS.md"), "user", processed, 0));
+    // 2. Project memory (AGENTS.md + .orbcode/AGENTS.md), root -> cwd
+    for (const dir of ancestorDirs(cwd).reverse()) {
+        files.push(...loadWithIncludes(path.join(dir, "AGENTS.md"), "project", processed, 0));
+        files.push(...loadWithIncludes(path.join(dir, ".orbcode", "AGENTS.md"), "project", processed, 0));
+    }
+    // 3. Local memory (AGENTS.local.md), root -> cwd — highest precedence
+    for (const dir of ancestorDirs(cwd).reverse()) {
+        files.push(...loadWithIncludes(path.join(dir, "AGENTS.local.md"), "local", processed, 0));
+    }
+    return files;
+}
+/** Render the memory files into a single system-prompt section. */
+export function renderMemorySection(files) {
+    const valid = files.filter((f) => f.content.trim());
+    if (valid.length === 0)
+        return "";
+    const parts = [
+        "# Project & User Instructions (AGENTS.md)",
+        "",
+        "Instructions from AGENTS.md files are shown below. Adhere to these instructions; they override default behavior. Treat them as authoritative guidance from the user about this codebase.",
+        "",
+    ];
+    let total = 0;
+    for (const file of valid) {
+        if (total >= MAX_TOTAL_CHARS) {
+            parts.push("… (remaining memory files truncated to stay within context budget)");
+            break;
+        }
+        const label = labelFor(file);
+        parts.push(`## ${label}: \`${file.path}\``);
+        parts.push("");
+        parts.push(file.content.trim());
+        parts.push("");
+        total += file.content.length;
+    }
+    return parts.join("\n");
+}
+function labelFor(file) {
+    switch (file.type) {
+        case "user":
+            return "User memory";
+        case "project":
+            return "Project memory";
+        case "local":
+            return "Local memory";
+    }
+}

package/dist/memory/types.js

@@ -0,0 +1 @@
+export {};

package/dist/prompts/system.js

@@ -1,5 +1,7 @@
 import * as os from "node:os";
 import { getShell } from "../utils/shell.js";
+import { renderMemorySection } from "../memory/loader.js";
+import { renderSkillCatalog } from "../skills/loader.js";
 // Role definition and tool guide ported verbatim from the Orbital extension
 // (agent mode roleDefinition + applyDiffToolDescription). Only the system
 // information section is adapted from the IDE to the CLI environment.
@@ -51,6 +53,18 @@ Bias towards not asking the user for help if you can find the answer yourself.
 
 Code chunks that you receive (via tool calls or from user) may include inline line numbers in the form LINE_NUMBER|LINE_CONTENT. Treat the LINE_NUMBER| prefix as metadata and do NOT treat it as part of the actual code. LINE_NUMBER is right-aligned number padded with spaces to 6 characters.
 
+# Project & User Instructions (AGENTS.md)
+
+Your system prompt may include an "Project & User Instructions (AGENTS.md)" section. These are instructions from AGENTS.md files in the user's home directory, the project root, and parent directories. They contain project-specific guidance: build commands, code style, architecture notes, conventions. Treat them as authoritative instructions from the user about this codebase and follow them exactly. They override default behavior.
+
+# Skills
+
+Your system prompt may include an "Available Skills" section listing skills by name with a description and when-to-use hint. Skills are reusable instruction sets stored in ~/.orbcode/skills/ and .orbcode/skills/. When a task matches a skill's when-to-use condition, invoke the \`use_skill\` tool with the skill's name to load its full instructions, then follow them for the current task.
+
+# MCP Tools
+
+Tools whose names start with \`mcp__\` are provided by external MCP servers the user has configured. They work exactly like native tools — call them with the standard tool call format when the task requires their capabilities. Their descriptions and parameter schemas come from the MCP servers.
+
 CRITICAL: For any task, small or big, you will always and always use the update_todo_list tool to create the TODO list, always keep is upto date with updates to the status and updating/editing the list as needed.`;
 const toolGuide = `
 Common tool calls and explanations
@@ -373,11 +387,16 @@ function getSystemInfoSection(cwd) {
 
 The Current Workspace Directory is the directory the user launched OrbCode CLI from, and is therefore the default directory for all tool operations. Commands run in the current workspace directory unless a different cwd is passed; changing directories inside a command does not modify the workspace directory. When the user initially gives you a task, a listing of filepaths in the current workspace directory will be included in the Environment Details section. This provides an overview of the project's file structure, offering key insights into the project from directory/file names (how developers conceptualize and organize their code) and file extensions (the language used). This can also guide decision-making on which files to explore further. If you need to further explore directories such as outside the current workspace directory, you can use the list_files tool. If you pass 'true' for the recursive parameter, it will list files recursively. Otherwise, it will list files at the top level, which is better suited for generic directories where you don't necessarily need the nested structure, like the Desktop.`;
 }
-export function buildSystemPrompt(cwd) {
-    return `${roleDefinition}
-
-${toolGuide}
-
-${getSystemInfoSection(cwd)}
-`;
+export function buildSystemPrompt(cwd, options = {}) {
+    const memorySection = options.memoryFiles ? renderMemorySection(options.memoryFiles) : "";
+    const skillSection = options.skills ? renderSkillCatalog(options.skills) : "";
+    return [
+        roleDefinition,
+        toolGuide,
+        getSystemInfoSection(cwd),
+        memorySection,
+        skillSection,
+    ]
+        .filter(Boolean)
+        .join("\n\n");
 }

package/dist/skills/loader.js

@@ -0,0 +1,132 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * Skill loader.
+ *
+ * Skills are markdown files that inject specialized instructions when the model
+ * invokes the `use_skill` tool. Discovery mirrors Claude Code's layout:
+ *
+ *   - User skills:   ~/.orbcode/skills/<name>/SKILL.md
+ *   - Project skills: .orbcode/skills/<name>/SKILL.md (in cwd and parents)
+ *
+ * Only the directory format (`<name>/SKILL.md`) is supported, matching Claude
+ * Code's current skills/ convention. Project skills override user skills on
+ * name collisions (closer-to-cwd wins).
+ */
+/** Parse a leading `---\n...---\n` YAML frontmatter block. */
+export function parseFrontmatter(raw) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    if (!match)
+        return { frontmatter: {}, content: raw };
+    const [, yamlBlock, body] = match;
+    const frontmatter = {};
+    for (const line of yamlBlock.split(/\r?\n/)) {
+        const idx = line.indexOf(":");
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        const value = line.slice(idx + 1).trim().replace(/^["']|["']$/g, "");
+        if (key)
+            frontmatter[key] = value;
+    }
+    return { frontmatter, content: body.trimStart() };
+}
+/** Extract a description from the first markdown paragraph if frontmatter lacks one. */
+function descriptionFromBody(content) {
+    const text = content
+        .replace(/^#+\s.*$/gm, "")
+        .replace(/```[\s\S]*?```/g, "")
+        .trim();
+    const firstPara = text.split(/\n\s*\n/)[0] ?? "";
+    return firstPara.replace(/\s+/g, " ").trim().slice(0, 160);
+}
+/** Load a single skill from a `<dir>/SKILL.md` path. */
+function loadSkill(skillDir, source) {
+    const skillFile = path.join(skillDir, "SKILL.md");
+    let raw;
+    try {
+        raw = fs.readFileSync(skillFile, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    const name = path.basename(skillDir);
+    const { frontmatter, content } = parseFrontmatter(raw);
+    return {
+        name,
+        description: frontmatter.description || descriptionFromBody(content),
+        whenToUse: frontmatter.when_to_use,
+        content,
+        source,
+        dir: skillDir,
+    };
+}
+/** Load all skills from a `skills/` directory (each subdirectory is one skill). */
+function loadSkillsDir(skillsDir, source) {
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const skill = loadSkill(path.join(skillsDir, entry.name), source);
+        if (skill)
+            skills.push(skill);
+    }
+    return skills;
+}
+/** Walk from cwd up to root, collecting `.orbcode/skills` dirs (root last). */
+function projectSkillsDirs(cwd) {
+    const dirs = [];
+    let current = path.resolve(cwd);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        dirs.push(path.join(current, ".orbcode", "skills"));
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return dirs;
+}
+/**
+ * Load all skills. Project skills (closer-to-cwd) override user skills on name
+ * collisions. Returns a map keyed by skill name.
+ */
+export function loadSkills(cwd = process.cwd()) {
+    const skills = new Map();
+    // User skills first (lowest precedence).
+    for (const skill of loadSkillsDir(path.join(getConfigDir(), "skills"), "user")) {
+        skills.set(skill.name, skill);
+    }
+    // Project skills, root -> cwd so cwd wins.
+    for (const dir of projectSkillsDirs(cwd).reverse()) {
+        for (const skill of loadSkillsDir(dir, "project")) {
+            skills.set(skill.name, skill);
+        }
+    }
+    return skills;
+}
+/** Render the skill catalog for the system prompt (names + when_to_use). */
+export function renderSkillCatalog(skills) {
+    if (skills.size === 0)
+        return "";
+    const lines = ["# Available Skills", ""];
+    for (const skill of skills.values()) {
+        const when = skill.whenToUse ? ` — use when: ${skill.whenToUse}` : "";
+        lines.push(`- \`${skill.name}\`: ${skill.description}${when}`);
+    }
+    lines.push("");
+    lines.push("Use the `use_skill` tool with a `skill_name` to load a skill's full instructions.");
+    return lines.join("\n");
+}
+/** Substitute ${SKILL_DIR} in a skill's content with its directory path. */
+export function renderSkillContent(skill) {
+    return skill.content.replace(/\$\{SKILL_DIR\}/g, skill.dir);
+}

package/dist/skills/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/executors/skills.js

@@ -0,0 +1,28 @@
+import { loadSkills, renderSkillContent } from "../../skills/loader.js";
+/**
+ * `use_skill` executor: loads a skill's full markdown instructions and returns
+ * them to the model so it can follow the skill's guidance for the current task.
+ *
+ * Skills are discovered from ~/.orbcode/skills/ and .orbcode/skills/ (see the
+ * skills loader). The model sees the catalog in the system prompt and invokes
+ * this tool with a `skill_name`.
+ */
+export async function useSkill(args, context) {
+    const skillName = String(args.skill_name ?? "").trim();
+    if (!skillName) {
+        return { text: "No skill_name provided.", isError: true };
+    }
+    const skills = loadSkills(context.cwd);
+    const skill = skills.get(skillName);
+    if (!skill) {
+        const available = [...skills.keys()].join(", ") || "(none)";
+        return {
+            text: `Skill "${skillName}" not found. Available skills: ${available}`,
+            isError: true,
+        };
+    }
+    const content = renderSkillContent(skill);
+    return {
+        text: `# Skill: ${skill.name}\n\n${content}\n\n---\nFollow this skill's instructions for the current task.`,
+    };
+}