@gabeosx/skx 1.0.0

package/README.md

@@ -0,0 +1,73 @@
+# skx
+
+![Build Status](https://img.shields.io/github/actions/workflow/status/gabeosx/skx/ci.yml?branch=main)
+![License](https://img.shields.io/npm/l/skx)
+
+**Agent Skills Manager** - The CLI tool for managing Agent Skills from the [Agent Skills Directory](https://skillindex.dev).
+
+## Overview
+
+`skx` simplifies the discovery, installation, and management of skills for AI agents like Gemini CLI, Claude Code, and Codex. It provides a unified interface to extend your AI agents with new capabilities from the AgentSkills registry.
+
+## Features
+
+- **Unified Management:** Manage skills across multiple agent utilities (Gemini, Claude, Codex).
+- **Interactive Wizard:** Step-by-step guidance for installation and configuration.
+- **Skill Discovery:** Easily search and list skills from the [Agent Skills Directory](https://skillindex.dev).
+- **Automated Detection:** Automatically detects your active agent environment.
+- **Scoped Installation:** Install skills globally (User) or locally (Workspace).
+
+## Installation
+
+### NPM
+```bash
+npm install -g skx
+```
+
+### Homebrew (macOS)
+```bash
+brew tap gabeosx/tap
+brew install skx
+```
+
+## Usage
+
+### Interactive Mode
+Simply run the command without arguments to start the interactive wizard:
+```bash
+skx
+```
+
+### CLI Commands
+
+**List installed skills:**
+```bash
+skx list
+```
+
+**Search for skills:**
+```bash
+skx search <query>
+```
+
+**Install a skill:**
+```bash
+skx install <package-name>
+```
+
+**Flags:**
+- `-a, --agent <agent>`: Explicitly specify the AI agent (e.g., `gemini`, `claude`, `codex`).
+- `-s, --scope <scope>`: Specify the installation scope (`workspace` or `user`).
+
+**Uninstall a skill:**
+```bash
+skx uninstall <package-name>
+```
+
+## Contributing
+
+Contributions are welcome! Please see the [Contributing Guidelines](CONTRIBUTING.md) for more details.
+
+## License
+
+ISC

package/dist/adapters/claude.js

@@ -0,0 +1,74 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { Scope } from '../types/adapter.js';
+import os from 'os';
+export class ClaudeAdapter {
+    name = 'claude';
+    async detect(cwd) {
+        const claudeExists = await fs.pathExists(path.join(cwd, '.claude'));
+        const githubExists = await fs.pathExists(path.join(cwd, '.github'));
+        return claudeExists || githubExists;
+    }
+    async getInstallationPath(scope, cwd) {
+        if (scope === Scope.Workspace) {
+            const claudePath = path.join(cwd, '.claude');
+            const githubPath = path.join(cwd, '.github');
+            // If .claude exists, prefer it.
+            if (await fs.pathExists(claudePath)) {
+                return path.join(claudePath, 'skills');
+            }
+            // If .github exists, use it.
+            if (await fs.pathExists(githubPath)) {
+                return path.join(githubPath, 'skills');
+            }
+            // Default to .claude if neither exists (creation will handle parent dir)
+            return path.join(claudePath, 'skills');
+        }
+        else {
+            // User scope
+            return path.join(os.homedir(), '.claude', 'skills');
+        }
+    }
+    getPostInstallInstructions() {
+        return `
+To use the installed skill with Claude Code:
+1. Ensure your Claude Code configuration includes the skills directory.
+2. Restart Claude Code if necessary.
+`.trim();
+    }
+    async listSkills(scope, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        if (!await fs.pathExists(installPath)) {
+            return [];
+        }
+        const entries = await fs.readdir(installPath, { withFileTypes: true });
+        const skills = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('@')) {
+                    // Handle scoped packages
+                    const scopePath = path.join(installPath, entry.name);
+                    const scopeEntries = await fs.readdir(scopePath, { withFileTypes: true });
+                    for (const scopeEntry of scopeEntries) {
+                        if (scopeEntry.isDirectory()) {
+                            skills.push(`${entry.name}/${scopeEntry.name}`);
+                        }
+                    }
+                }
+                else if (!entry.name.startsWith('.')) {
+                    skills.push(entry.name);
+                }
+            }
+        }
+        return skills.sort();
+    }
+    async uninstallSkill(scope, packageName, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        const skillPath = path.join(installPath, packageName);
+        // Safety check: Ensure we are deleting something inside the installPath
+        if (!skillPath.startsWith(installPath)) {
+            throw new Error('Invalid skill path');
+        }
+        await fs.remove(skillPath);
+    }
+}

package/dist/adapters/codex.js

@@ -0,0 +1,64 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { Scope } from '../types/adapter.js';
+import os from 'os';
+export class CodexAdapter {
+    name = 'codex';
+    async detect(cwd) {
+        const copilotExists = await fs.pathExists(path.join(cwd, '.copilot'));
+        const githubExists = await fs.pathExists(path.join(cwd, '.github'));
+        return copilotExists || githubExists;
+    }
+    async getInstallationPath(scope, cwd) {
+        if (scope === Scope.Workspace) {
+            // Codex/Copilot typically uses .github/skills for workspace
+            return path.join(cwd, '.github', 'skills');
+        }
+        else {
+            // User scope typically in ~/.copilot/skills
+            return path.join(os.homedir(), '.copilot', 'skills');
+        }
+    }
+    getPostInstallInstructions() {
+        return `
+To use the installed skill with GitHub Copilot/Codex:
+1. Ensure your Copilot configuration includes the skills directory.
+2. Restart your editor or Copilot agent if necessary.
+`.trim();
+    }
+    async listSkills(scope, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        if (!await fs.pathExists(installPath)) {
+            return [];
+        }
+        const entries = await fs.readdir(installPath, { withFileTypes: true });
+        const skills = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('@')) {
+                    // Handle scoped packages
+                    const scopePath = path.join(installPath, entry.name);
+                    const scopeEntries = await fs.readdir(scopePath, { withFileTypes: true });
+                    for (const scopeEntry of scopeEntries) {
+                        if (scopeEntry.isDirectory()) {
+                            skills.push(`${entry.name}/${scopeEntry.name}`);
+                        }
+                    }
+                }
+                else if (!entry.name.startsWith('.')) {
+                    skills.push(entry.name);
+                }
+            }
+        }
+        return skills.sort();
+    }
+    async uninstallSkill(scope, packageName, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        const skillPath = path.join(installPath, packageName);
+        // Safety check: Ensure we are deleting something inside the installPath
+        if (!skillPath.startsWith(installPath)) {
+            throw new Error('Invalid skill path');
+        }
+        await fs.remove(skillPath);
+    }
+}

package/dist/adapters/gemini.js

@@ -0,0 +1,61 @@
+import path from 'path';
+import fs from 'fs-extra';
+import { Scope } from '../types/adapter.js';
+import os from 'os';
+export class GeminiAdapter {
+    name = 'gemini';
+    async detect(cwd) {
+        return fs.pathExists(path.join(cwd, '.gemini'));
+    }
+    async getInstallationPath(scope, cwd) {
+        if (scope === Scope.Workspace) {
+            return path.join(cwd, '.gemini', 'skills');
+        }
+        else {
+            // User scope
+            return path.join(os.homedir(), '.gemini', 'skills');
+        }
+    }
+    getPostInstallInstructions() {
+        return `
+To use the installed skill with Gemini CLI:
+1. Ensure your Gemini CLI configuration is set to load skills from the installation directory.
+2. You may need to restart the Gemini CLI or the current session for the changes to take effect.
+`.trim();
+    }
+    async listSkills(scope, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        if (!await fs.pathExists(installPath)) {
+            return [];
+        }
+        const entries = await fs.readdir(installPath, { withFileTypes: true });
+        const skills = [];
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (entry.name.startsWith('@')) {
+                    // Handle scoped packages
+                    const scopePath = path.join(installPath, entry.name);
+                    const scopeEntries = await fs.readdir(scopePath, { withFileTypes: true });
+                    for (const scopeEntry of scopeEntries) {
+                        if (scopeEntry.isDirectory()) {
+                            skills.push(`${entry.name}/${scopeEntry.name}`);
+                        }
+                    }
+                }
+                else if (!entry.name.startsWith('.')) {
+                    skills.push(entry.name);
+                }
+            }
+        }
+        return skills.sort();
+    }
+    async uninstallSkill(scope, packageName, cwd) {
+        const installPath = await this.getInstallationPath(scope, cwd);
+        const skillPath = path.join(installPath, packageName);
+        // Safety check: Ensure we are deleting something inside the installPath
+        if (!skillPath.startsWith(installPath)) {
+            throw new Error('Invalid skill path');
+        }
+        await fs.remove(skillPath);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,183 @@
+import { Command, Option } from 'commander';
+import chalk from 'chalk';
+import { fetchRegistry } from './utils/registry.js';
+import { searchSkills } from './utils/search.js';
+import { FrameworkResolver } from './utils/framework-resolver.js';
+import { SkillInstaller } from './utils/skill-installer.js';
+import { SkillManager } from './utils/skill-manager.js';
+import { Scope } from './types/adapter.js';
+import { spinner, select, isCancel } from '@clack/prompts';
+import path from 'path';
+export function createProgram() {
+    const program = new Command();
+    program
+        .name('skx')
+        .description('A CLI tool to discover and install skills')
+        .version('1.0.0');
+    program
+        .command('list')
+        .description('List installed skills')
+        .addOption(new Option('-a, --agent <agent>', 'Filter by agent (e.g., gemini, claude, codex)'))
+        .addOption(new Option('-s, --scope <type>', 'Filter by scope').choices(['workspace', 'user']))
+        .action(async (options) => {
+        try {
+            const manager = new SkillManager();
+            const skillsMap = await manager.detectInstalledSkills({
+                agent: options.agent,
+                scope: options.scope
+            });
+            if (skillsMap.size === 0) {
+                console.log(chalk.yellow('No installed skills found.'));
+                return;
+            }
+            console.log(chalk.bold('Installed Skills:'));
+            for (const [key, skills] of skillsMap.entries()) {
+                console.log(`\n${chalk.blue.bold(key)}`);
+                skills.forEach(skill => {
+                    console.log(`  ${skill}`);
+                });
+            }
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error(chalk.red(`Error: ${error.message}`));
+            }
+            else {
+                console.error(chalk.red('An unknown error occurred.'));
+            }
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('search')
+        .description('Search for skills')
+        .argument('[query]', 'Search query')
+        .action(async (query) => {
+        try {
+            const skills = await fetchRegistry();
+            const results = searchSkills(skills, query || '');
+            if (results.length === 0) {
+                console.log(chalk.yellow('No skills found.'));
+                return;
+            }
+            console.log(chalk.green(`Found ${results.length} skills:`));
+            results.forEach((skill) => {
+                console.log(chalk.bold(skill.name));
+                console.log(`  ${skill.description}`);
+                console.log(chalk.dim(`  Package: ${skill.packageName}`));
+                console.log(chalk.blue(`  URL: ${skill.githubRepoUrl}`));
+                console.log();
+            });
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                console.error(chalk.red(`Error: ${error.message}`));
+            }
+            else {
+                console.error(chalk.red('An unknown error occurred.'));
+            }
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('install')
+        .description('Install a skill for your AI agent')
+        .argument('<skill-name>', 'Name of the skill to install')
+        .addOption(new Option('-a, --agent <name>', 'Explicitly specify the agent (e.g., gemini, claude, codex)'))
+        .addOption(new Option('-s, --scope <type>', 'Installation scope').choices(['workspace', 'user']))
+        .action(async (skillName, options) => {
+        const s = spinner();
+        let spinnerStarted = false;
+        try {
+            // 1. Determine Scope (Interactive if not provided)
+            let scopeType = options.scope;
+            if (!scopeType) {
+                const selectedScope = await select({
+                    message: 'Where should this skill be installed?',
+                    options: [
+                        { value: 'workspace', label: 'Workspace (Current Project)', hint: 'Installs to ./.gemini/skills' }, // Note: Hint path depends on framework, simplified here
+                        { value: 'user', label: 'User (Global)', hint: 'Installs to ~/.gemini/skills' },
+                    ],
+                });
+                if (isCancel(selectedScope)) {
+                    console.log(chalk.yellow('Installation cancelled.'));
+                    return;
+                }
+                scopeType = selectedScope;
+            }
+            // 2. Fetch Skill Info
+            s.start(`Searching for skill: ${skillName}`);
+            spinnerStarted = true;
+            const skills = await fetchRegistry();
+            const skill = skills.find(s => s.name === skillName || s.packageName === skillName);
+            if (!skill) {
+                s.stop(`Skill "${skillName}" not found in registry.`, 1);
+                process.exitCode = 1;
+                return;
+            }
+            s.stop(`Found skill: ${skill.name}`);
+            spinnerStarted = false;
+            // 3. Resolve Framework
+            const resolver = new FrameworkResolver();
+            const adapter = await resolver.resolve(process.cwd(), options.agent);
+            // 4. Determine Paths
+            const scope = scopeType === 'user' ? Scope.User : Scope.Workspace;
+            const basePath = await adapter.getInstallationPath(scope, process.cwd());
+            const skillDirName = skill.packageName || skill.name;
+            const targetPath = path.join(basePath, skillDirName);
+            s.start(`Downloading and installing to ${targetPath}...`);
+            spinnerStarted = true;
+            const installer = new SkillInstaller();
+            await installer.installFromUrl(skill.githubRepoUrl, targetPath);
+            s.stop(`Successfully installed ${skill.name}!`);
+            spinnerStarted = false;
+            console.log('\n' + chalk.bold('Post-Installation Instructions:'));
+            console.log(adapter.getPostInstallInstructions());
+        }
+        catch (error) {
+            if (spinnerStarted) {
+                s.stop('Installation failed.', 1);
+            }
+            if (error instanceof Error) {
+                console.error(chalk.red(`Error: ${error.message}`));
+            }
+            else {
+                console.error(chalk.red('An unknown error occurred.'));
+            }
+            process.exitCode = 1;
+        }
+    });
+    program
+        .command('uninstall')
+        .description('Uninstall a skill')
+        .argument('<skill-name>', 'Name of the skill to uninstall')
+        .requiredOption('-a, --agent <agent>', 'Agent name (required)')
+        .requiredOption('-s, --scope <type>', 'Scope (workspace/user) (required)')
+        .action(async (skillName, options) => {
+        const s = spinner();
+        let spinnerStarted = false;
+        try {
+            const resolver = new FrameworkResolver();
+            const adapter = await resolver.resolve(process.cwd(), options.agent);
+            const scope = options.scope === 'user' ? Scope.User : Scope.Workspace;
+            s.start(`Uninstalling ${skillName}...`);
+            spinnerStarted = true;
+            await adapter.uninstallSkill(scope, skillName, process.cwd());
+            s.stop(`Successfully uninstalled ${skillName}`);
+            spinnerStarted = false;
+        }
+        catch (error) {
+            if (spinnerStarted) {
+                s.stop('Uninstallation failed.', 1);
+            }
+            if (error instanceof Error) {
+                console.error(chalk.red(`Error: ${error.message}`));
+            }
+            else {
+                console.error(chalk.red('An unknown error occurred.'));
+            }
+            process.exitCode = 1;
+        }
+    });
+    return program;
+}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import { createProgram } from './cli.js';
+import { startInteractiveMode } from './ui.js';
+import { AdapterRegistry } from './utils/adapters.js';
+import { GeminiAdapter } from './adapters/gemini.js';
+import { ClaudeAdapter } from './adapters/claude.js';
+import { CodexAdapter } from './adapters/codex.js';
+// Register Adapters
+AdapterRegistry.register(new GeminiAdapter());
+AdapterRegistry.register(new ClaudeAdapter());
+AdapterRegistry.register(new CodexAdapter());
+if (process.argv.length === 2) {
+    startInteractiveMode();
+}
+else {
+    const program = createProgram();
+    program.parse(process.argv);
+}

package/dist/types/adapter.js

@@ -0,0 +1,6 @@
+export var Scope;
+(function (Scope) {
+    Scope["Workspace"] = "workspace";
+    Scope["User"] = "user";
+    Scope["System"] = "system";
+})(Scope || (Scope = {}));

package/dist/ui.js

@@ -0,0 +1,36 @@
+import { intro, outro, cancel, spinner } from '@clack/prompts';
+import { runWizard } from './wizard.js';
+import { SkillInstaller } from './utils/skill-installer.js';
+import chalk from 'chalk';
+export async function startInteractiveMode() {
+    intro(chalk.inverse(' skx '));
+    try {
+        const result = await runWizard();
+        if (!result) {
+            cancel('Installation cancelled.');
+            process.exit(0);
+        }
+        const { skill, agent, scope } = result;
+        const s = spinner();
+        s.start(`Installing ${skill.name} for ${agent.name}...`);
+        // In a real implementation, we would download the skill first.
+        // For now, we simulate the installation using the installer.
+        // The installer expects sourceDir and targetDir.
+        // We need to resolve the target directory using the adapter.
+        const targetDir = await agent.getInstallationPath(scope, process.cwd());
+        const installer = new SkillInstaller();
+        // TODO: Implement skill downloading logic. 
+        // For now, we assume the skill is already available or simulate it.
+        const dummySource = '/tmp/skx-dummy-source'; // Placeholder
+        await installer.install(dummySource, targetDir);
+        s.stop(`Successfully installed ${skill.name}!`);
+        console.log(chalk.bold('\nPost-Installation Instructions:'));
+        console.log(agent.getPostInstallInstructions());
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            console.error(chalk.red(`\nError: ${error.message}`));
+        }
+    }
+    outro('Done!');
+}

package/dist/utils/adapters.js

@@ -0,0 +1,15 @@
+export class AdapterRegistry {
+    static adapters = new Map();
+    static register(adapter) {
+        this.adapters.set(adapter.name, adapter);
+    }
+    static get(name) {
+        return this.adapters.get(name);
+    }
+    static getAll() {
+        return Array.from(this.adapters.values());
+    }
+    static clear() {
+        this.adapters.clear();
+    }
+}

package/dist/utils/downloader.js

@@ -0,0 +1,30 @@
+import tiged from 'tiged';
+export class Downloader {
+    static async download(url, targetDir) {
+        const source = this.parseUrl(url);
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        const emitter = tiged(source, {
+            cache: false,
+            force: true,
+            verbose: false,
+        });
+        await emitter.clone(targetDir);
+    }
+    static parseUrl(url) {
+        const cleanUrl = url.replace('https://github.com/', '');
+        if (cleanUrl.includes('/tree/')) {
+            const [repoPart, rest] = cleanUrl.split('/tree/');
+            if (rest) {
+                const parts = rest.split('/');
+                const branch = parts[0];
+                const subdir = parts.slice(1).join('/');
+                if (subdir) {
+                    return `${repoPart}/${subdir}#${branch}`;
+                }
+                return `${repoPart}#${branch}`;
+            }
+        }
+        return cleanUrl;
+    }
+}

package/dist/utils/framework-resolver.js

@@ -0,0 +1,53 @@
+import { AdapterRegistry } from './adapters.js';
+import { select, isCancel, cancel } from '@clack/prompts';
+export class FrameworkResolver {
+    async detect(cwd) {
+        const adapters = AdapterRegistry.getAll();
+        const detectedAdapters = [];
+        for (const adapter of adapters) {
+            if (await adapter.detect(cwd)) {
+                detectedAdapters.push(adapter);
+            }
+        }
+        return detectedAdapters;
+    }
+    async resolve(cwd, explicitName) {
+        // 1. Explicit Selection
+        if (explicitName) {
+            const adapter = AdapterRegistry.get(explicitName);
+            if (!adapter) {
+                throw new Error(`Framework '${explicitName}' is not supported or registered.`);
+            }
+            return adapter;
+        }
+        // 2. Automatic Discovery
+        const detectedAdapters = await this.detect(cwd);
+        // 3. Handle Results
+        if (detectedAdapters.length === 0) {
+            throw new Error('No AI agent framework detected in the current directory.');
+        }
+        if (detectedAdapters.length === 1) {
+            return detectedAdapters[0];
+        }
+        // 4. Conflict Resolution
+        const selection = await select({
+            message: 'Multiple AI agent frameworks detected. Please select one:',
+            options: detectedAdapters.map((adapter) => ({
+                value: adapter,
+                label: adapter.name,
+            })),
+        });
+        if (isCancel(selection)) {
+            cancel('Operation cancelled.');
+            // In a real CLI app, we might exit. 
+            // But for the resolver function, throwing an error is cleaner so the caller can handle it.
+            // However, the test expects 'Operation cancelled' error or behavior.
+            // The `cancel` function from clack prints a message. It does NOT exit the process (unless configured?).
+            // Wait, checking clack docs or source is hard. 
+            // Usually `cancel` just prints. 
+            // I should throw an error to stop execution.
+            throw new Error('Operation cancelled');
+        }
+        return selection;
+    }
+}

package/dist/utils/registry.js

@@ -0,0 +1,30 @@
+import axios from 'axios';
+import { z } from 'zod';
+export const SkillSchema = z.object({
+    name: z.string(),
+    packageName: z.string(),
+    description: z.string(),
+    githubRepoUrl: z.string(),
+    tags: z.array(z.string()),
+    command: z.string().optional(),
+    author: z.string().optional(),
+    version: z.string().optional(),
+});
+export const RegistrySchema = z.array(SkillSchema);
+const REGISTRY_URL = 'https://raw.githubusercontent.com/gabeosx/agentskillsdir/main/public/skills.json';
+export async function fetchRegistry() {
+    try {
+        const response = await axios.get(REGISTRY_URL);
+        const result = RegistrySchema.safeParse(response.data);
+        if (!result.success) {
+            throw new Error('Invalid registry format');
+        }
+        return result.data;
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'Invalid registry format') {
+            throw error;
+        }
+        throw new Error('Failed to fetch registry');
+    }
+}

package/dist/utils/scope-resolver.js

@@ -0,0 +1,14 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { Scope } from '../types/adapter.js';
+export class ScopeResolver {
+    async resolve(cwd) {
+        const indicators = ['.git', 'package.json', 'go.mod', 'Cargo.toml', 'requirements.txt', '.gemini', '.claudecode'];
+        for (const indicator of indicators) {
+            if (await fs.pathExists(path.join(cwd, indicator))) {
+                return Scope.Workspace;
+            }
+        }
+        return Scope.User;
+    }
+}

package/dist/utils/search.js

@@ -0,0 +1,10 @@
+export function searchSkills(skills, query) {
+    if (!query) {
+        return skills;
+    }
+    const lowerQuery = query.toLowerCase();
+    return skills.filter((skill) => {
+        return (skill.name.toLowerCase().includes(lowerQuery) ||
+            skill.description.toLowerCase().includes(lowerQuery));
+    });
+}

package/dist/utils/skill-installer.js

@@ -0,0 +1,45 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { Downloader } from './downloader.js';
+export class SkillInstaller {
+    /**
+     * Installs a skill by copying its files to the target directory.
+     * Ensures the parent directory of the target exists.
+     *
+     * @param sourceDir The directory containing the skill's files.
+     * @param targetDir The destination directory for the skill.
+     */
+    async install(sourceDir, targetDir) {
+        try {
+            // Ensure the parent directory (e.g., .gemini/skills/) exists
+            const parentDir = path.dirname(targetDir);
+            await fs.ensureDir(parentDir);
+            // Copy the skill directory
+            await fs.copy(sourceDir, targetDir);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to install skill: ${error.message}`);
+            }
+            throw new Error('An unknown error occurred during skill installation.');
+        }
+    }
+    /**
+     * Downloads a skill from a URL and installs it.
+     *
+     * @param url The GitHub URL or other source URL.
+     * @param targetDir The destination directory.
+     */
+    async installFromUrl(url, targetDir) {
+        const tempDir = path.join(os.tmpdir(), `skx-skill-${Date.now()}`);
+        try {
+            await Downloader.download(url, tempDir);
+            await this.install(tempDir, targetDir);
+        }
+        finally {
+            // Cleanup temp directory
+            await fs.remove(tempDir);
+        }
+    }
+}

package/dist/utils/skill-manager.js

@@ -0,0 +1,35 @@
+import { AdapterRegistry } from './adapters.js';
+import { Scope } from '../types/adapter.js';
+export class SkillManager {
+    async detectInstalledSkills(filter) {
+        const results = new Map(); // Key: "AgentName - Scope", Value: Skill[]
+        const adapters = filter?.agent
+            ? AdapterRegistry.getAll().filter(a => a.name === filter.agent)
+            : AdapterRegistry.getAll();
+        for (const adapter of adapters) {
+            // If scope is specified, check only that scope
+            // Else check both Workspace and User
+            let scopesToCheck = [Scope.Workspace, Scope.User];
+            if (filter?.scope) {
+                // Simple string matching to enum
+                const s = filter.scope;
+                if (Object.values(Scope).includes(s)) {
+                    scopesToCheck = [s];
+                }
+            }
+            for (const scope of scopesToCheck) {
+                try {
+                    const skills = await adapter.listSkills(scope, process.cwd());
+                    if (skills.length > 0) {
+                        const key = `${adapter.name} - ${scope}`;
+                        results.set(key, skills);
+                    }
+                }
+                catch (e) {
+                    // Ignore errors (e.g. if detection fails or directory doesn't exist)
+                }
+            }
+        }
+        return results;
+    }
+}

package/dist/utils/skill-search.js

@@ -0,0 +1,59 @@
+import { text, select, isCancel } from '@clack/prompts';
+import { fetchRegistry } from './registry.js';
+import { searchSkills } from './search.js';
+/**
+ * Interactive skill discovery function.
+ * Prompts user for a search query and then presents a list of results to select from.
+ */
+export async function searchAndSelectSkill() {
+    let skills;
+    try {
+        skills = await fetchRegistry();
+    }
+    catch (error) {
+        throw new Error('Failed to fetch skill registry.');
+    }
+    let query = '';
+    while (true) {
+        const userInput = await text({
+            message: 'Search for a skill:',
+            placeholder: 'e.g. react',
+            defaultValue: query,
+        });
+        if (isCancel(userInput))
+            return undefined;
+        query = userInput;
+        const results = searchSkills(skills, query);
+        if (results.length === 0) {
+            const retry = await select({
+                message: 'No skills found. Try again?',
+                options: [
+                    { value: 'retry', label: 'Yes, search again' },
+                    { value: 'cancel', label: 'No, cancel' },
+                ],
+            });
+            if (isCancel(retry) || retry === 'cancel')
+                return undefined;
+            continue;
+        }
+        const selection = await select({
+            message: `Found ${results.length} skills. Select one:`,
+            options: [
+                ...results.map((skill) => ({
+                    value: skill,
+                    label: skill.name,
+                    hint: skill.description,
+                })),
+                { value: 'search_again', label: '-- Search again --' },
+            ],
+        });
+        if (isCancel(selection))
+            return undefined;
+        if (selection === 'search_again') {
+            // Clear query for new search if they select search again?
+            // Or keep it? The test expects it to loop.
+            continue;
+        }
+        return selection;
+    }
+}

package/dist/wizard.js

@@ -0,0 +1,69 @@
+import { select, confirm, isCancel, note } from '@clack/prompts';
+import { searchAndSelectSkill } from './utils/skill-search.js';
+import { FrameworkResolver } from './utils/framework-resolver.js';
+import { ScopeResolver } from './utils/scope-resolver.js';
+import { AdapterRegistry } from './utils/adapters.js';
+import { Scope } from './types/adapter.js';
+import chalk from 'chalk';
+/**
+ * Runs the interactive installation wizard.
+ *
+ * Flow:
+ * 1. Search and select a skill.
+ * 2. Detect environment (Agent and Scope).
+ * 3. Confirm/Select Agent.
+ * 4. Confirm/Select Scope.
+ * 5. Display summary and confirm installation.
+ */
+export async function runWizard() {
+    // 1. Skill Selection
+    const skill = await searchAndSelectSkill();
+    if (!skill)
+        return undefined;
+    const cwd = process.cwd();
+    const frameworkResolver = new FrameworkResolver();
+    const scopeResolver = new ScopeResolver();
+    // 2. Detection
+    const detectedAgents = await frameworkResolver.detect(cwd);
+    const detectedScope = await scopeResolver.resolve(cwd);
+    // 3. Agent Selection
+    const allAgents = AdapterRegistry.getAll();
+    const agentSelection = await select({
+        message: 'Select target AI agent:',
+        options: allAgents.map((a) => ({
+            value: a,
+            label: a.name,
+            hint: detectedAgents.some(da => da.name === a.name) ? '(detected)' : undefined,
+        })),
+        initialValue: detectedAgents.length > 0 ? detectedAgents[0] : undefined,
+    });
+    if (isCancel(agentSelection))
+        return undefined;
+    const agent = agentSelection;
+    // 4. Scope Selection
+    const scopeSelection = await select({
+        message: 'Select installation scope:',
+        options: [
+            { value: Scope.Workspace, label: 'Workspace', hint: 'Local to this project' },
+            { value: Scope.User, label: 'User', hint: 'Global for your user (~/)' },
+        ],
+        initialValue: detectedScope,
+    });
+    if (isCancel(scopeSelection))
+        return undefined;
+    const scope = scopeSelection;
+    // 5. Confirmation Summary
+    note(`Skill:  ${chalk.cyan(skill.name)}
+` +
+        `Agent:  ${chalk.cyan(agent.name)}
+` +
+        `Scope:  ${chalk.cyan(scope)}
+` +
+        `Path:   ${chalk.dim('Determined by agent adapter')}`, 'Installation Summary');
+    const confirmed = await confirm({
+        message: 'Proceed with installation?',
+    });
+    if (isCancel(confirmed) || !confirmed)
+        return undefined;
+    return { skill, agent, scope };
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@gabeosx/skx",
+  "version": "1.0.0",
+  "description": "The CLI tool for managing Agent Skills",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "skx": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "format": "prettier --write ."
+  },
+  "keywords": [
+    "agent",
+    "skills",
+    "ai",
+    "cli",
+    "gemini",
+    "claude",
+    "codex"
+  ],
+  "author": "Gabe",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gabeosx/skx.git"
+  },
+  "license": "ISC",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "axios": "^1.13.2",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "conf": "^15.0.2",
+    "fs-extra": "^11.3.3",
+    "tiged": "^2.12.7",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^12.0.2",
+    "@semantic-release/npm": "^13.1.3",
+    "@types/fs-extra": "^11.0.4",
+    "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "^4.0.17",
+    "eslint": "^9.39.2",
+    "prettier": "^3.8.0",
+    "semantic-release": "^25.0.2",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.53.0",
+    "vitest": "^4.0.17"
+  }
+}