ikie-cli 0.1.22 → 0.1.24

package/dist/agent.d.ts

@@ -76,5 +76,5 @@ export declare class Agent {
     private checkPermission;
 }
 export declare const SUBAGENT_FRAMING = "You are a focused sub-agent spawned by Ikie to autonomously complete ONE specific task.\nWork independently \u2014 do not ask the user questions. Use your tools to gather what you\nneed, do the work, and verify it. When finished, your FINAL message must be a concise\nsummary of what you did and any key results (paths changed, findings, answers). That\nsummary is the only thing returned to the main agent, so make it self-contained.";
-export declare const PLAN_MODE_ADDENDUM = "\n\n## PLAN MODE (read-only)\nYou are currently in **plan mode**. You have ONLY read-only tools (read_file,\nlist_dir, search_files, grep, fetch_url, web_search, spawn_agent, ask_user). You CANNOT write files, edit\nfiles, run shell commands, or change anything \u2014 those tools are unavailable and any\nattempt will be blocked.\n\nYour job is to investigate and produce a clear, actionable plan:\n- Explore the relevant files and understand the current state before proposing anything.\n- Do NOT describe changes as if you already made them. You haven't.\n- End your response with a concise plan: a short **## Plan** heading followed by\n  numbered steps. Name the specific files to change and what to change in each. Call\n  out risks, assumptions, or open questions.\n- Keep it tight \u2014 enough to execute from, not an essay.\n\nAfter you present the plan, the user will be asked whether to execute it. On approval,\nyou'll be switched to agent mode and asked to carry out exactly this plan.";
-export declare function buildSystemPrompt(projectContext: string, memoryContext: string): string;
+export declare const PLAN_MODE_ADDENDUM = "\n\n## PLAN MODE (read-only)\nYou are currently in **plan mode**. You have ONLY read-only tools (read_file,\nlist_dir, search_files, grep, fetch_url, web_search, use_skill, spawn_agent, ask_user). You CANNOT write files, edit\nfiles, run shell commands, or change anything \u2014 those tools are unavailable and any\nattempt will be blocked.\n\nYour job is to investigate and produce a clear, actionable plan:\n- Explore the relevant files and understand the current state before proposing anything.\n- Do NOT describe changes as if you already made them. You haven't.\n- End your response with a concise plan: a short **## Plan** heading followed by\n  numbered steps. Name the specific files to change and what to change in each. Call\n  out risks, assumptions, or open questions.\n- Keep it tight \u2014 enough to execute from, not an essay.\n\nAfter you present the plan, the user will be asked whether to execute it. On approval,\nyou'll be switched to agent mode and asked to carry out exactly this plan.";
+export declare function buildSystemPrompt(projectContext: string, memoryContext: string, skillsCatalog?: string): string;

package/dist/agent.js

@@ -68,6 +68,9 @@ function toolPhaseLabel(name) {
         case 'git_branch': return 'Git branch';
         case 'fetch_url': return 'Fetching';
         case 'web_search': return 'Searching web';
+        case 'use_skill': return 'Loading skill';
+        case 'install_skill': return 'Installing skill';
+        case 'remove_skill': return 'Removing skill';
         default: return `Preparing ${name}`;
     }
 }
@@ -807,7 +810,7 @@ export const PLAN_MODE_ADDENDUM = `
 
 ## PLAN MODE (read-only)
 You are currently in **plan mode**. You have ONLY read-only tools (read_file,
-list_dir, search_files, grep, fetch_url, web_search, spawn_agent, ask_user). You CANNOT write files, edit
+list_dir, search_files, grep, fetch_url, web_search, use_skill, spawn_agent, ask_user). You CANNOT write files, edit
 files, run shell commands, or change anything — those tools are unavailable and any
 attempt will be blocked.
 
@@ -821,7 +824,7 @@ Your job is to investigate and produce a clear, actionable plan:
 
 After you present the plan, the user will be asked whether to execute it. On approval,
 you'll be switched to agent mode and asked to carry out exactly this plan.`;
-export function buildSystemPrompt(projectContext, memoryContext) {
+export function buildSystemPrompt(projectContext, memoryContext, skillsCatalog = '') {
     const parts = [
         `You are Ikie, an elite agentic software engineer running in the terminal.
 
@@ -930,11 +933,31 @@ changes they didn't ask for.
   \`task\` and any needed \`context\`, since it does not see this conversation.
 - \`switch_mode\`: Request permission to switch between plan and agent mode. Use when the current
   mode is not sufficient for what you need to do next. The user must approve the switch.
+- \`use_skill\`: Load a **skill** — a curated pack of expert instructions (plus optional bundled
+  files/scripts) for a specific kind of task. The skills installed on this machine are listed
+  under "Available Skills" below by name + description. When a task matches one, call
+  \`use_skill\` with its exact name FIRST to pull in the full instructions, then follow them.
+  **Skill scripts are for your internal use only.** If a skill includes Python/bash scripts,
+  run them yourself with the bash tool and use the output. Never paste the raw commands or
+  tell the user to run them manually. Apply the skill's knowledge directly to the user's task.
+- \`install_skill\`: Install a skill from a git URL (GitHub, GitLab, Bitbucket) or local path.
+  Skills are instruction packs that give the agent specialized expertise. Example:
+  \`install_skill(source: "https://github.com/user/repo.git")\`.
+- \`remove_skill\`: Remove a previously installed skill by name. Call without a name to list
+  all installed skills.
 - \`ask_user\`: Ask the user a clarifying question when you need more info to proceed.
   The user's answer is returned as the tool result. Use sparingly — only when genuinely
   unsure. Don't ask for confirmation on safe operations.
 `,
     ];
+    if (skillsCatalog) {
+        parts.push(`## Available Skills\n` +
+            `These skills are installed and ready. Each is a specialized instruction pack. ` +
+            `When the user's task matches a skill's description, call \`use_skill\` with its exact ` +
+            `name BEFORE doing the work, then follow the loaded instructions. Only the name and ` +
+            `description are shown here — the full instructions load on demand.\n\n` +
+            skillsCatalog);
+    }
     if (projectContext)
         parts.push(`## Project Context\n${projectContext}`);
     if (memoryContext)

package/dist/index.js

@@ -5,6 +5,7 @@ import minimist from 'minimist';
 import { loadConfig, getApiKey, IKIE_API_BASE, IKIE_HOST, DEFAULT_MODEL, hasExplicitModel } from './config.js';
 import { detectProjectContext, formatContextForPrompt } from './context.js';
 import { loadAllMemory, formatMemoryForPrompt } from './memory.js';
+import { discoverSkills, formatSkillsForPrompt } from './skills.js';
 import { buildSystemPrompt, Agent } from './agent.js';
 import { startREPL } from './repl.js';
 import { login, logout } from './auth.js';
@@ -23,6 +24,9 @@ ${c.primary('Usage:')}
   ${c.accent('ikie')} ${c.muted('"<message>"')}        One-shot command
   ${c.accent('ikie login')}               Sign in to your ikie account
   ${c.accent('ikie logout')}              Sign out of your ikie account
+  ${c.accent('ikie skills')}              List installed skills
+  ${c.accent('ikie skills install')} ${c.muted('<src>')} Install a skill (git URL or path)
+  ${c.accent('ikie skills remove')} ${c.muted('<name>')}  Remove an installed skill
   ${c.accent('ikie')} ${c.muted('--model <id>')}       Use specific model
 
 ${c.primary('Options:')}
@@ -40,6 +44,63 @@ ${c.primary('In-session commands:')}
   ${c.muted('Ctrl+V  Paste image from clipboard')}
 `);
 }
+async function runSkillsCli(args, force) {
+    const { discoverSkills, installSkill, removeSkill, listSkillFiles } = await import('./skills.js');
+    const sub = (args[0] ?? 'list').toLowerCase();
+    if (sub === 'install' || sub === 'add') {
+        const src = args.slice(1).filter(a => a !== '--force').join(' ').trim();
+        if (!src) {
+            console.error(errorLine('Usage: ikie skills install <local-path|git-url> [--force]'));
+            return;
+        }
+        console.log(c.muted(`Installing skill from ${src}…`));
+        try {
+            const r = await installSkill(src, { force });
+            if (r.installed.length) {
+                console.log(`${c.success('✓')} Installed: ${c.white(r.installed.join(', '))}`);
+            }
+            for (const s of r.skipped)
+                console.log(`${c.muted('•')} Skipped ${s.name} — ${s.reason}`);
+            if (!r.installed.length && !r.skipped.length)
+                console.log(c.muted('Nothing installed.'));
+        }
+        catch (err) {
+            console.error(errorLine(err instanceof Error ? err.message : String(err)));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (sub === 'remove' || sub === 'rm' || sub === 'uninstall') {
+        const name = args.slice(1).join(' ').trim();
+        if (!name) {
+            console.error(errorLine('Usage: ikie skills remove <name>'));
+            return;
+        }
+        if (removeSkill(name))
+            console.log(`${c.success('✓')} Removed skill "${name}".`);
+        else {
+            console.error(errorLine(`No user-installed skill named "${name}".`));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // list
+    const skills = discoverSkills();
+    if (!skills.length) {
+        console.log('No skills installed.');
+        console.log(`\nInstall one with:\n  ${c.accent('ikie skills install <git-url|path>')}`);
+        console.log(`\nClaude Code skills (.claude/skills) are also picked up automatically.`);
+        return;
+    }
+    console.log(`\n${c.primary.bold('Installed Skills')} ${c.muted(`(${skills.length})`)}\n`);
+    for (const s of skills) {
+        const nFiles = listSkillFiles(s).length;
+        console.log(`  ${c.secondary('●')} ${c.white.bold(s.name)} ${c.muted(`[${s.source}·${s.origin}]`)}${nFiles ? c.muted(` · ${nFiles} files`) : ''}`);
+        if (s.description)
+            console.log(`    ${c.dim(s.description)}`);
+    }
+    console.log();
+}
 async function main() {
     if (argv.version) {
         try {
@@ -68,6 +129,10 @@ async function main() {
         logout();
         process.exit(0);
     }
+    if (cmd === 'skills') {
+        await runSkillsCli(argv._.slice(1).map(String), Boolean(argv.force));
+        process.exit(0);
+    }
     const config = loadConfig();
     if (argv.model)
         config.model = argv.model;
@@ -115,7 +180,9 @@ ${errorLine('Not signed in.')}
     const projectContextStr = formatContextForPrompt(projectCtx);
     const memory = loadAllMemory();
     const memoryStr = formatMemoryForPrompt(memory);
-    const systemPrompt = buildSystemPrompt(projectContextStr, memoryStr);
+    const skills = discoverSkills();
+    const skillsStr = formatSkillsForPrompt(skills);
+    const systemPrompt = buildSystemPrompt(projectContextStr, memoryStr, skillsStr);
     if (argv.verbose) {
         console.log(c.muted('─'.repeat(60)));
         console.log(c.muted('System prompt:'));

package/dist/repl.js

@@ -93,6 +93,16 @@ const SLASH_CMDS = [
     { name: 'rpm', desc: 'Set request limit', args: '[number]' },
     { name: 'tokens', desc: 'Token estimate' },
     { name: 'usage', desc: 'Show account usage & credit' },
+    {
+        name: 'skills',
+        desc: 'List/install skills',
+        subs: [
+            { name: 'list', desc: 'List installed skills' },
+            { name: 'show', desc: 'Show a skill\'s instructions' },
+            { name: 'install', desc: 'Install a skill from a path or git URL' },
+            { name: 'remove', desc: 'Remove an installed skill' },
+        ],
+    },
     { name: 'mode', desc: 'Show/set mode (plan|agent)', args: '[plan|agent]' },
     { name: 'plan', desc: 'Switch to plan mode (read-only)' },
     { name: 'agent', desc: 'Switch to agent mode (full)' },
@@ -165,6 +175,10 @@ ${c.primary.bold('Ikie Commands')}
   ${c.warning('/rpm [number]')}    Show or set request limit
   ${c.warning('/tokens')}          Show conversation token estimate
   ${c.warning('/usage')}           Show account usage & credit balance
+  ${c.warning('/skills')}          List installed skills
+  ${c.warning('/skills show <name>')} Show a skill's instructions
+  ${c.warning('/skills install <src>')} Install a skill (git URL or path)
+  ${c.warning('/skills remove <name>')} Remove an installed skill
   ${c.warning('/plan')}            Plan mode — research & propose, no changes
   ${c.warning('/agent')}           Agent mode — full execution (default)
   ${c.warning('/mode')}            Show or set mode  ${c.muted('(Shift+Tab toggles)')}
@@ -374,6 +388,87 @@ async function handleSlashCommand(input, agent, config, projectContext, rl, sess
             await login();
             return true;
         }
+        case 'skills': {
+            const sub = (args[0] ?? 'list').toLowerCase();
+            const { discoverSkills, getSkill, listSkillFiles, installSkill, removeSkill } = await import('./skills.js');
+            if (sub === 'install' || sub === 'add') {
+                const rest = args.slice(1).filter(a => a !== '--force');
+                const force = args.includes('--force');
+                const src = rest.join(' ').trim();
+                if (!src) {
+                    console.log(errorLine('Usage: /skills install <local-path|git-url> [--force]'));
+                    return true;
+                }
+                console.log(c.muted(`  Installing skill from ${src}…`));
+                try {
+                    const r = await installSkill(src, { force });
+                    if (r.installed.length) {
+                        console.log(successLine(`Installed ${r.installed.length} skill${r.installed.length === 1 ? '' : 's'}: ${r.installed.join(', ')}`));
+                        console.log(infoLine('Available now — the agent will use them automatically when relevant.'));
+                    }
+                    for (const s of r.skipped) {
+                        console.log(infoLine(`Skipped "${s.name}" — ${s.reason}`));
+                    }
+                    if (!r.installed.length && !r.skipped.length) {
+                        console.log(infoLine('Nothing installed.'));
+                    }
+                }
+                catch (err) {
+                    console.log(errorLine(err instanceof Error ? err.message : String(err)));
+                }
+                return true;
+            }
+            if (sub === 'remove' || sub === 'rm' || sub === 'uninstall') {
+                const nameArg = args.slice(1).join(' ').trim();
+                if (!nameArg) {
+                    console.log(errorLine('Usage: /skills remove <name>'));
+                    return true;
+                }
+                if (removeSkill(nameArg)) {
+                    console.log(successLine(`Removed skill "${nameArg}".`));
+                }
+                else {
+                    console.log(errorLine(`No user-installed skill named "${nameArg}".`));
+                }
+                return true;
+            }
+            if (sub === 'show' || sub === 'view') {
+                const nameArg = args.slice(1).join(' ').trim();
+                if (!nameArg) {
+                    console.log(errorLine('Usage: /skills show <name>'));
+                    return true;
+                }
+                const skill = getSkill(nameArg);
+                if (!skill) {
+                    console.log(errorLine(`No skill named "${nameArg}".`));
+                    return true;
+                }
+                console.log(`\n${c.primary.bold(skill.name)} ${c.muted(`(${skill.source} · ${skill.origin})`)}`);
+                if (skill.description)
+                    console.log(c.white(skill.description));
+                console.log(c.dim(skill.dir));
+                console.log(renderMarkdown(skill.body || '(no instructions)'));
+                return true;
+            }
+            const skills = discoverSkills();
+            if (!skills.length) {
+                console.log(infoLine('No skills installed.'));
+                console.log(`\n  ${c.muted('Install one with')} ${c.warning('/skills install <git-url|path>')}`);
+                console.log(`  ${c.muted('or drop a folder with a')} ${c.warning('SKILL.md')} ${c.muted('into')} ${c.dim('~/.ikie/skills/')}`);
+                console.log(`\n  ${c.muted('Claude Code skills (.claude/skills) work as-is.')}\n`);
+                return true;
+            }
+            console.log(`\n${c.primary.bold('Installed Skills')} ${c.muted(`(${skills.length})`)}\n`);
+            for (const s of skills) {
+                const nFiles = listSkillFiles(s).length;
+                const extras = nFiles ? c.muted(` · ${nFiles} file${nFiles === 1 ? '' : 's'}`) : '';
+                console.log(`  ${c.secondary('●')} ${c.white.bold(s.name)} ${c.muted(`[${s.source}·${s.origin}]`)}${extras}`);
+                if (s.description)
+                    console.log(`    ${c.dim(s.description)}`);
+            }
+            console.log(`\n  ${c.muted('Used automatically when relevant ·')} ${c.warning('/skills show <name>')} ${c.muted('·')} ${c.warning('/skills install <src>')}\n`);
+            return true;
+        }
         case 'logout': {
             if (!isLoggedIn(config)) {
                 console.log(infoLine('Not signed in.'));

package/dist/skills.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Skills — progressively-disclosed instruction packs, compatible with the
+ * Claude Code "Agent Skills" format (a folder containing a `SKILL.md` with
+ * YAML frontmatter `name` + `description`, and an optional body of
+ * instructions plus bundled resource files/scripts).
+ *
+ * The agent only ever sees each skill's name + description up front (cheap).
+ * When a skill looks relevant it calls the `use_skill` tool to load the full
+ * SKILL.md body on demand, along with the skill's directory so it can read any
+ * bundled files or run bundled scripts with its normal tools.
+ */
+export interface Skill {
+    name: string;
+    description: string;
+    /** Full markdown body of SKILL.md (everything after the frontmatter). */
+    body: string;
+    /** Absolute path to the skill's directory. */
+    dir: string;
+    /** Absolute path to the SKILL.md file. */
+    file: string;
+    /** Where it came from, for display: "project" or "user". */
+    source: 'project' | 'user';
+    /** The roots this skill was discovered under, e.g. ".ikie" or ".claude". */
+    origin: string;
+}
+/**
+ * Discover all available skills across project and user roots.
+ * The first occurrence of a given (lowercased) name wins, so a project skill
+ * shadows a user skill with the same name.
+ */
+export declare function discoverSkills(cwd?: string): Skill[];
+/** Look up a single skill by name (case-insensitive). */
+export declare function getSkill(name: string, cwd?: string): Skill | undefined;
+/** List the bundled files in a skill directory (excluding the SKILL.md itself). */
+export declare function listSkillFiles(skill: Skill): string[];
+/**
+ * Render the skill catalog for the system prompt: each skill's name +
+ * description, so the model knows what exists and when to reach for one.
+ * Returns '' when no skills are installed (so the section is omitted).
+ */
+export declare function formatSkillsForPrompt(skills: Skill[]): string;
+/**
+ * Build the full text returned to the model when it loads a skill via
+ * `use_skill`: the instructions plus a manifest of bundled files and the
+ * skill's directory, so the agent can read resources / run scripts itself.
+ */
+export declare function renderSkill(skill: Skill): string;
+/** Where user-installed skills live. */
+export declare function userSkillsDir(): string;
+export interface InstallResult {
+    installed: string[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+    from: 'local' | 'git';
+}
+/**
+ * Install one or more skills from a local path or a git repository URL into the
+ * user skills directory (~/.ikie/skills). A source may be a single skill folder
+ * (contains SKILL.md) or a collection that holds several skill folders.
+ */
+export declare function installSkill(source: string, opts?: {
+    force?: boolean;
+}): Promise<InstallResult>;
+/** Remove a user-installed skill by name. Returns true if it was removed. */
+export declare function removeSkill(name: string): boolean;

package/dist/skills.js

@@ -0,0 +1,349 @@
+import { homedir, tmpdir } from 'os';
+import { join, resolve, basename } from 'path';
+import { readFileSync, existsSync, readdirSync, statSync, mkdirSync, rmSync, cpSync } from 'fs';
+import { exec } from 'child_process';
+import { promisify } from 'util';
+const execAsync = promisify(exec);
+/** Parse minimal YAML frontmatter (--- delimited) into a flat string map + body. */
+function parseFrontmatter(raw) {
+    const text = raw.replace(/^/, '');
+    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+    if (!m)
+        return { meta: {}, body: text.trim() };
+    const meta = {};
+    for (const line of m[1].split(/\r?\n/)) {
+        const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+        if (!kv)
+            continue;
+        let value = kv[2].trim();
+        // Strip matching surrounding quotes.
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        meta[kv[1].toLowerCase()] = value;
+    }
+    return { meta, body: (m[2] ?? '').trim() };
+}
+function skillRoots(cwd = process.cwd()) {
+    const home = homedir();
+    return [
+        // Project skills win over user skills; .ikie wins over .claude within a tier.
+        { dir: join(cwd, '.ikie', 'skills'), source: 'project', origin: '.ikie' },
+        { dir: join(cwd, '.claude', 'skills'), source: 'project', origin: '.claude' },
+        { dir: join(home, '.ikie', 'skills'), source: 'user', origin: '.ikie' },
+        { dir: join(home, '.claude', 'skills'), source: 'user', origin: '.claude' },
+    ];
+}
+function findSkillFile(skillDir) {
+    // Standard layout: <skillDir>/SKILL.md (case-insensitive on the filename).
+    for (const entry of ['SKILL.md', 'Skill.md', 'skill.md']) {
+        const p = join(skillDir, entry);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Discover all available skills across project and user roots.
+ * The first occurrence of a given (lowercased) name wins, so a project skill
+ * shadows a user skill with the same name.
+ */
+export function discoverSkills(cwd = process.cwd()) {
+    const byName = new Map();
+    for (const root of skillRoots(cwd)) {
+        if (!existsSync(root.dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(root.dir);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const skillDir = join(root.dir, entry);
+            let isDir = false;
+            try {
+                isDir = statSync(skillDir).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (!isDir)
+                continue;
+            const file = findSkillFile(skillDir);
+            if (!file)
+                continue;
+            let raw;
+            try {
+                raw = readFileSync(file, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const { meta, body } = parseFrontmatter(raw);
+            const name = (meta.name || basename(skillDir)).trim();
+            const description = (meta.description || '').trim();
+            const key = name.toLowerCase();
+            if (!name || byName.has(key))
+                continue;
+            byName.set(key, {
+                name,
+                description,
+                body,
+                dir: skillDir,
+                file,
+                source: root.source,
+                origin: root.origin,
+            });
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Look up a single skill by name (case-insensitive). */
+export function getSkill(name, cwd = process.cwd()) {
+    const want = name.trim().toLowerCase();
+    return discoverSkills(cwd).find(s => s.name.toLowerCase() === want);
+}
+/** List the bundled files in a skill directory (excluding the SKILL.md itself). */
+export function listSkillFiles(skill) {
+    const out = [];
+    const walk = (dir, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === 'SKILL.md' && prefix === '')
+                continue;
+            if (entry === '.git' || entry === 'node_modules')
+                continue;
+            const abs = join(dir, entry);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            const rel = prefix ? `${prefix}/${entry}` : entry;
+            if (st.isDirectory()) {
+                walk(abs, rel);
+            }
+            else {
+                out.push(rel);
+            }
+        }
+    };
+    walk(skill.dir, '');
+    return out.sort();
+}
+/**
+ * Render the skill catalog for the system prompt: each skill's name +
+ * description, so the model knows what exists and when to reach for one.
+ * Returns '' when no skills are installed (so the section is omitted).
+ */
+export function formatSkillsForPrompt(skills) {
+    if (!skills.length)
+        return '';
+    const lines = skills.map(s => {
+        const desc = s.description || '(no description)';
+        return `- **${s.name}** — ${desc}`;
+    });
+    return lines.join('\n');
+}
+/**
+ * Build the full text returned to the model when it loads a skill via
+ * `use_skill`: the instructions plus a manifest of bundled files and the
+ * skill's directory, so the agent can read resources / run scripts itself.
+ */
+export function renderSkill(skill) {
+    const files = listSkillFiles(skill);
+    const parts = [];
+    parts.push(`# Skill: ${skill.name}`);
+    if (skill.description)
+        parts.push(skill.description);
+    parts.push(`Skill directory: ${skill.dir}`);
+    if (files.length) {
+        const shown = files.slice(0, 40);
+        const more = files.length - shown.length;
+        parts.push(`Bundled files (read with read_file or run with bash, relative to the skill directory):\n` +
+            shown.map(f => `  - ${f}`).join('\n') +
+            (more > 0 ? `\n  …and ${more} more` : ''));
+    }
+    parts.push('---');
+    parts.push(skill.body || '(This skill has no additional instructions.)');
+    parts.push('---');
+    parts.push('Follow these instructions for the current task. Use your normal tools to read any ' +
+        'bundled files or run any bundled scripts referenced above (resolve their paths against ' +
+        'the skill directory). ' +
+        'IMPORTANT: do NOT show the user raw python3 / bash commands or tell them to run scripts manually. ' +
+        'If a skill includes scripts, run them yourself with the bash tool and present the results. ' +
+        'Use the skill\'s knowledge directly to do the work.');
+    return parts.join('\n\n');
+}
+// ─── Install / remove ─────────────────────────────────────────────────────────
+/** Where user-installed skills live. */
+export function userSkillsDir() {
+    return join(homedir(), '.ikie', 'skills');
+}
+const SKILL_FILE_NAMES = ['SKILL.md', 'Skill.md', 'skill.md'];
+function hasSkillFile(dir) {
+    return SKILL_FILE_NAMES.some(n => existsSync(join(dir, n)));
+}
+/** Find every directory containing a SKILL.md within `root`, up to `maxDepth`. */
+function findSkillDirs(root, maxDepth = 3) {
+    const found = [];
+    const walk = (dir, depth) => {
+        if (depth > maxDepth)
+            return;
+        if (hasSkillFile(dir)) {
+            found.push(dir);
+            return; // don't descend into a skill's own subfolders
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry === '.git' || entry === 'node_modules')
+                continue;
+            const abs = join(dir, entry);
+            let st;
+            try {
+                st = statSync(abs);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory())
+                walk(abs, depth + 1);
+        }
+    };
+    walk(root, 0);
+    return found;
+}
+/** Read the declared `name:` from a skill dir's SKILL.md, falling back to the folder name. */
+function skillDirName(dir) {
+    const file = findSkillFile(dir);
+    if (file) {
+        try {
+            const { meta } = parseFrontmatter(readFileSync(file, 'utf-8'));
+            if (meta.name)
+                return meta.name.trim();
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    return basename(dir);
+}
+function looksLikeGitUrl(source) {
+    return (/^git@/.test(source) ||
+        /^https?:\/\/.+\.git$/.test(source) ||
+        /^(https?:\/\/)?(www\.)?(github|gitlab|bitbucket)\.com\//.test(source) ||
+        /^git\+/.test(source));
+}
+/**
+ * Install one or more skills from a local path or a git repository URL into the
+ * user skills directory (~/.ikie/skills). A source may be a single skill folder
+ * (contains SKILL.md) or a collection that holds several skill folders.
+ */
+export async function installSkill(source, opts = {}) {
+    const raw = source.trim();
+    if (!raw)
+        throw new Error('A skill source (local path or git URL) is required.');
+    const dest = userSkillsDir();
+    mkdirSync(dest, { recursive: true });
+    const localPath = resolve(raw);
+    const isLocal = existsSync(localPath);
+    let scanRoot;
+    let tempDir;
+    let from;
+    if (isLocal) {
+        scanRoot = localPath;
+        from = 'local';
+    }
+    else if (looksLikeGitUrl(raw)) {
+        const cloneUrl = raw.replace(/^git\+/, '');
+        tempDir = join(tmpdir(), `ikie-skill-${Date.now()}`);
+        try {
+            await execAsync(`git clone --depth 1 ${JSON.stringify(cloneUrl)} ${JSON.stringify(tempDir)}`, {
+                timeout: 120000,
+            });
+        }
+        catch (err) {
+            const e = err;
+            throw new Error(`git clone failed: ${(e.stderr ?? e.message ?? String(err)).trim()}`);
+        }
+        scanRoot = tempDir;
+        from = 'git';
+    }
+    else {
+        throw new Error(`Source not found: "${raw}". Provide an existing local path or a git URL.`);
+    }
+    try {
+        const skillDirs = findSkillDirs(scanRoot);
+        if (!skillDirs.length) {
+            throw new Error('No SKILL.md found in the source. A skill must contain a SKILL.md file.');
+        }
+        const installed = [];
+        const skipped = [];
+        for (const dir of skillDirs) {
+            const name = skillDirName(dir);
+            const target = join(dest, name);
+            if (existsSync(target) && !opts.force) {
+                skipped.push({ name, reason: 'already installed (use --force to overwrite)' });
+                continue;
+            }
+            if (existsSync(target))
+                rmSync(target, { recursive: true, force: true });
+            // Dereference symlinks so bundled files don't point back to a temp clone dir.
+            cpSync(dir, target, { recursive: true, dereference: true });
+            // Never carry version-control metadata into the skill store.
+            rmSync(join(target, '.git'), { recursive: true, force: true });
+            installed.push(name);
+        }
+        return { installed, skipped, from };
+    }
+    finally {
+        if (tempDir)
+            rmSync(tempDir, { recursive: true, force: true });
+    }
+}
+/** Remove a user-installed skill by name. Returns true if it was removed. */
+export function removeSkill(name) {
+    const want = name.trim();
+    if (!want)
+        return false;
+    const dest = userSkillsDir();
+    // Match by declared name first, then by folder name.
+    let entries;
+    try {
+        entries = readdirSync(dest);
+    }
+    catch {
+        return false;
+    }
+    for (const entry of entries) {
+        const dir = join(dest, entry);
+        try {
+            if (!statSync(dir).isDirectory())
+                continue;
+        }
+        catch {
+            continue;
+        }
+        if (entry === want || skillDirName(dir).toLowerCase() === want.toLowerCase()) {
+            rmSync(dir, { recursive: true, force: true });
+            return true;
+        }
+    }
+    return false;
+}

package/dist/theme.js

@@ -363,6 +363,7 @@ function toolMeta(rawName) {
         case 'git_log': return { verb: 'GitLog', tint: c.info };
         case 'git_commit': return { verb: 'Commit', tint: c.success };
         case 'git_branch': return { verb: 'GitBranch', tint: c.info };
+        case 'use_skill': return { verb: 'Skill', tint: c.secondary };
         default: return { verb: base, tint: c.primary };
     }
 }

package/dist/tools.js

@@ -270,6 +270,49 @@ export const TOOL_DEFS = [
             },
         },
     },
+    {
+        type: 'function',
+        function: {
+            name: 'use_skill',
+            description: 'Load a skill — a curated pack of expert instructions (and optional bundled files/scripts) for a specific kind of task. Skills are listed by name + description in your system prompt under "Available Skills". When a task matches a skill, call this FIRST with that skill\'s exact name to pull in its full instructions, then follow them. Returns the skill body plus the paths of any bundled resources you can read or run.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'The exact name of the skill to load (as shown in "Available Skills").' },
+                },
+                required: ['name'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'install_skill',
+            description: 'Install a skill from a local path or git repository URL (GitHub, GitLab, Bitbucket). Skills are instruction packs that give the agent specialized expertise. Provide a git URL (e.g. https://github.com/user/repo.git) or a local path. Use --force to overwrite existing skills.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    source: { type: 'string', description: 'Local path or git URL to install skill(s) from' },
+                    force: { type: 'boolean', description: 'Overwrite if already installed (default: false)' },
+                },
+                required: ['source'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'remove_skill',
+            description: 'Remove a previously installed skill by name. Lists installed skills if called without a name.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Name of the skill to remove (omit to list installed skills)' },
+                },
+                required: [],
+            },
+        },
+    },
     {
         type: 'function',
         function: {
@@ -289,11 +332,11 @@ export const TOOL_DEFS = [
 // ─── Safe tools (auto-approved) ───────────────────────────────────────────────
 // spawn_agent is "safe" at the dispatch layer — the tools the sub-agent itself
 // runs go through their own approval inside the sub-agent loop.
-export const SAFE_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'memory_write', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search', 'git_status', 'git_diff', 'git_log', 'git_branch']);
+export const SAFE_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'memory_write', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search', 'git_status', 'git_diff', 'git_log', 'git_branch', 'use_skill', 'install_skill', 'remove_skill']);
 // Tools available in PLAN mode — read-only exploration plus delegation/questions.
 // Everything that mutates the filesystem or runs commands (write_file, edit_file,
 // bash, memory_write) is intentionally excluded so plan mode can only research.
-export const PLAN_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search', 'git_status', 'git_diff', 'git_log', 'git_branch']);
+export const PLAN_TOOLS = new Set(['read_file', 'list_dir', 'search_files', 'grep', 'spawn_agent', 'ask_user', 'fetch_url', 'web_search', 'git_status', 'git_diff', 'git_log', 'git_branch', 'use_skill', 'install_skill', 'remove_skill']);
 // Paths that may contain secrets, credentials, or system configuration.
 // Reading these requires explicit user permission even though read_file is normally safe.
 const RESTRICTED_PATTERNS = [
@@ -371,6 +414,12 @@ export function formatToolArgs(name, input) {
             const q = String(input.query ?? '');
             return `"${q.length > 56 ? q.slice(0, 56) + '…' : q}"`;
         }
+        case 'use_skill':
+            return `"${p(input.name)}"`;
+        case 'install_skill':
+            return `"${p(input.source)}"${input.force ? ' --force' : ''}`;
+        case 'remove_skill':
+            return input.name ? `"${p(input.name)}"` : '(list installed)';
         default:
             return JSON.stringify(input).slice(0, 80);
     }
@@ -819,6 +868,56 @@ function formatSearchResults(query, results) {
     });
     return `Results for "${query}":\n\n${lines.join('\n\n')}`;
 }
+// ─── Skills ─────────────────────────────────────────────────────────────────
+async function useSkill(input) {
+    const name = (input.name ?? '').trim();
+    if (!name || name === 'undefined')
+        return 'Error: name is required for use_skill';
+    const { getSkill, discoverSkills, renderSkill } = await import('./skills.js');
+    const skill = getSkill(name);
+    if (!skill) {
+        const available = discoverSkills().map(s => s.name);
+        return available.length
+            ? `Error: no skill named "${name}". Available skills: ${available.join(', ')}.`
+            : `Error: no skill named "${name}", and no skills are installed.`;
+    }
+    return renderSkill(skill);
+}
+async function installSkill(input) {
+    const source = (input.source ?? '').trim();
+    if (!source || source === 'undefined')
+        return 'Error: source is required for install_skill';
+    const { installSkill: doInstall } = await import('./skills.js');
+    try {
+        const result = await doInstall(source, { force: input.force ?? false });
+        const lines = [];
+        if (result.installed.length) {
+            lines.push(`Installed ${result.installed.length} skill(s): ${result.installed.join(', ')}`);
+        }
+        if (result.skipped.length) {
+            for (const s of result.skipped)
+                lines.push(`Skipped "${s.name}": ${s.reason}`);
+        }
+        return lines.length ? lines.join('\n') : 'Nothing to install.';
+    }
+    catch (err) {
+        return `Error: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}
+async function removeSkill(input) {
+    const { removeSkill: doRemove, userSkillsDir, discoverSkills } = await import('./skills.js');
+    const name = (input.name ?? '').trim();
+    if (!name || name === 'undefined') {
+        // List installed skills
+        const skills = discoverSkills();
+        const userSkills = skills.filter(s => s.source === 'user');
+        if (!userSkills.length)
+            return 'No user-installed skills found.';
+        return 'Installed skills:\n' + userSkills.map(s => `  - ${s.name}: ${s.description || '(no description)'}`).join('\n');
+    }
+    const removed = doRemove(name);
+    return removed ? `Removed skill "${name}".` : `No skill named "${name}" found.`;
+}
 // ─── Dispatcher ───────────────────────────────────────────────────────────────
 export async function executeTool(name, input) {
     switch (name) {
@@ -838,6 +937,9 @@ export async function executeTool(name, input) {
         case 'git_branch': return gitBranch(input);
         case 'fetch_url': return fetchUrl(input);
         case 'web_search': return webSearch(input);
+        case 'use_skill': return useSkill(input);
+        case 'install_skill': return installSkill(input);
+        case 'remove_skill': return removeSkill(input);
         default: return `Unknown tool: ${name}`;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ikie-cli",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Agentic coding CLI — your terminal AI pair programmer",
   "type": "module",
   "bin": {