@dhruvwill/skills-cli 1.0.0 → 1.1.0

package/src/commands/source.ts

@@ -4,49 +4,53 @@ import { rm, cp, mkdir } from "fs/promises";
 import chalk from "chalk";
 import Table from "cli-table3";
 import { addSource, removeSource, getSources } from "../lib/config.ts";
-import { parseGitUrl, getRemoteNamespace, getLocalNamespace, getNamespacePath, SKILLS_STORE } from "../lib/paths.ts";
+import { parseGitUrl, getDefaultSkillName, getLocalSkillName, getSkillPath, SKILLS_STORE } from "../lib/paths.ts";
 import { directoryExists } from "../lib/hash.ts";
 
 /**
  * Add a source (remote or local)
+ * @param pathOrUrl - Git URL or local path
+ * @param type - "remote" or "local"
+ * @param customName - Optional custom name to override default
  */
-export async function sourceAdd(pathOrUrl: string, type: "remote" | "local"): Promise<void> {
+export async function sourceAdd(pathOrUrl: string, type: "remote" | "local", customName?: string): Promise<void> {
   if (type === "remote") {
-    await addRemoteSource(pathOrUrl);
+    await addRemoteSource(pathOrUrl, customName);
   } else {
-    await addLocalSource(pathOrUrl);
+    await addLocalSource(pathOrUrl, customName);
   }
 }
 
 /**
  * Add a remote Git repository as a source
  */
-async function addRemoteSource(url: string): Promise<void> {
+async function addRemoteSource(url: string, customName?: string): Promise<void> {
   const parsed = parseGitUrl(url);
   
   if (!parsed) {
     throw new Error(`Invalid Git URL: ${url}. Expected formats:\n  - https://github.com/owner/repo\n  - https://gitlab.com/owner/repo\n  - https://bitbucket.org/owner/repo\n  - https://any-host.com/owner/repo.git`);
   }
 
-  const namespace = getRemoteNamespace(parsed);
-  const targetPath = getNamespacePath(namespace);
+  const defaultName = getDefaultSkillName(parsed);
+  const skillName = customName || defaultName;
+  const targetPath = getSkillPath(skillName);
   const cloneUrl = parsed.cloneUrl;
   const branch = parsed.branch || "main";
 
   console.log(`Adding remote source: ${url}`);
-  console.log(`Namespace: ${namespace}`);
+  console.log(`Skill name: ${chalk.cyan(skillName)}`);
+  if (customName && customName !== defaultName) {
+    console.log(`  (renamed from: ${defaultName})`);
+  }
   if (parsed.subdir) {
     console.log(`Subdirectory: ${parsed.subdir}`);
   }
 
-  // Check if directory already exists
+  // Check if skill name already exists
   if (await directoryExists(targetPath)) {
-    throw new Error(`Source already exists at ${namespace}. Remove it first with 'skills source remove ${namespace}'`);
+    throw new Error(`Skill "${skillName}" already exists. Remove it first with 'skills source remove ${skillName}' or use --name to specify a different name.`);
   }
 
-  // Create parent directory if needed
-  await mkdir(getNamespacePath(parsed.owner), { recursive: true });
-
   // Clone the repository
   console.log("Cloning repository...");
   
@@ -87,36 +91,37 @@ async function addRemoteSource(url: string): Promise<void> {
   await addSource({
     type: "remote",
     url,
-    namespace,
+    name: skillName,
   });
 
-  console.log(`Successfully added remote source: ${namespace}`);
+  console.log(chalk.green(`Successfully added skill: ${skillName}`));
 }
 
 /**
  * Add a local folder as a source
  */
-async function addLocalSource(folderPath: string): Promise<void> {
+async function addLocalSource(folderPath: string, customName?: string): Promise<void> {
   const absolutePath = resolve(folderPath);
   
   if (!(await directoryExists(absolutePath))) {
     throw new Error(`Local folder does not exist: ${absolutePath}`);
   }
 
-  const namespace = getLocalNamespace(absolutePath);
-  const targetPath = getNamespacePath(namespace);
+  const defaultName = getLocalSkillName(absolutePath);
+  const skillName = customName || defaultName;
+  const targetPath = getSkillPath(skillName);
 
   console.log(`Adding local source: ${absolutePath}`);
-  console.log(`Namespace: ${namespace}`);
+  console.log(`Skill name: ${chalk.cyan(skillName)}`);
+  if (customName && customName !== defaultName) {
+    console.log(`  (renamed from: ${defaultName})`);
+  }
 
-  // Check if namespace already exists
+  // Check if skill name already exists
   if (await directoryExists(targetPath)) {
-    throw new Error(`Source already exists at ${namespace}. Remove it first with 'skills source remove ${namespace}'`);
+    throw new Error(`Skill "${skillName}" already exists. Remove it first with 'skills source remove ${skillName}' or use --name to specify a different name.`);
   }
 
-  // Create local directory
-  await mkdir(getNamespacePath("local"), { recursive: true });
-
   // Copy files
   console.log("Copying files...");
   await cp(absolutePath, targetPath, { recursive: true });
@@ -125,27 +130,27 @@ async function addLocalSource(folderPath: string): Promise<void> {
   await addSource({
     type: "local",
     path: absolutePath,
-    namespace,
+    name: skillName,
   });
 
-  console.log(`Successfully added local source: ${namespace}`);
+  console.log(chalk.green(`Successfully added skill: ${skillName}`));
 }
 
 /**
- * Remove a source by namespace
+ * Remove a source by name
  */
-export async function sourceRemove(namespace: string): Promise<void> {
-  const removed = await removeSource(namespace);
+export async function sourceRemove(name: string): Promise<void> {
+  const removed = await removeSource(name);
   
   if (!removed) {
-    throw new Error(`Source not found: ${namespace}`);
+    throw new Error(`Skill not found: ${name}`);
   }
 
   // Remove the files from store
-  const targetPath = getNamespacePath(namespace);
+  const targetPath = getSkillPath(name);
   await rm(targetPath, { recursive: true, force: true });
 
-  console.log(`Removed source: ${namespace}`);
+  console.log(chalk.green(`Removed skill: ${name}`));
 }
 
 /**
@@ -162,9 +167,9 @@ export async function sourceList(): Promise<void> {
 
   const table = new Table({
     head: [
-      chalk.bold("Namespace"),
+      chalk.bold("Skill"),
       chalk.bold("Type"),
-      chalk.bold("Location"),
+      chalk.bold("Source"),
       chalk.bold("Status"),
     ],
     style: {
@@ -174,11 +179,11 @@ export async function sourceList(): Promise<void> {
   });
 
   for (const source of sources) {
-    const exists = await directoryExists(getNamespacePath(source.namespace));
+    const exists = await directoryExists(getSkillPath(source.name));
     const status = exists ? chalk.green("OK") : chalk.red("MISSING");
     
     table.push([
-      source.namespace,
+      source.name,
       source.type,
       source.url || source.path || "",
       status,

package/src/commands/status.ts

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import Table from "cli-table3";
 import { getSources, getTargets } from "../lib/config.ts";
-import { SKILLS_ROOT, SKILLS_STORE, getNamespacePath } from "../lib/paths.ts";
+import { SKILLS_ROOT, SKILLS_STORE, getSkillPath } from "../lib/paths.ts";
 import { directoryExists, compareDirectories } from "../lib/hash.ts";
 
 /**
@@ -21,16 +21,16 @@ export async function status(): Promise<void> {
   // Sources summary
   const sources = await getSources();
   console.log();
-  console.log(chalk.bold(`Sources (${sources.length})`));
+  console.log(chalk.bold(`Skills (${sources.length})`));
   
   if (sources.length === 0) {
-    console.log(chalk.dim("  No sources registered"));
+    console.log(chalk.dim("  No skills registered"));
   } else {
     for (const source of sources) {
-      const exists = await directoryExists(getNamespacePath(source.namespace));
+      const exists = await directoryExists(getSkillPath(source.name));
       const icon = exists ? chalk.green("●") : chalk.red("●");
       const typeLabel = source.type === "remote" ? chalk.blue("remote") : chalk.magenta("local");
-      console.log(`  ${icon} ${source.namespace} ${chalk.dim(`(${typeLabel})`)}`);
+      console.log(`  ${icon} ${source.name} ${chalk.dim(`(${typeLabel})`)}`);
     }
   }
 

package/src/commands/target.ts

@@ -6,14 +6,32 @@ import { addTarget, removeTarget, getTargets } from "../lib/config.ts";
 import { SKILLS_STORE } from "../lib/paths.ts";
 import { compareDirectories, directoryExists } from "../lib/hash.ts";
 import { syncToTarget } from "./sync.ts";
+import { getKnownTarget, KNOWN_TARGETS } from "../lib/known-targets.ts";
 
 /**
  * Add a target directory
+ * If path is not provided, looks up known targets
  */
-export async function targetAdd(name: string, path: string): Promise<void> {
-  const absolutePath = resolve(path.replace(/^~/, process.env.HOME || process.env.USERPROFILE || ""));
+export async function targetAdd(name: string, path?: string): Promise<void> {
+  let absolutePath: string;
+  
+  if (path) {
+    // User provided a custom path
+    absolutePath = resolve(path.replace(/^~/, process.env.HOME || process.env.USERPROFILE || ""));
+  } else {
+    // Look up known target
+    const known = getKnownTarget(name);
+    if (!known) {
+      console.error(chalk.red(`Unknown target: ${name}`));
+      console.log(`\nRun ${chalk.cyan("skills target available")} to see predefined targets.`);
+      console.log(`Or specify a custom path: ${chalk.cyan(`skills target add ${name} <path>`)}`);
+      process.exit(1);
+    }
+    absolutePath = known.path;
+    console.log(`Using predefined path for ${chalk.cyan(known.description)}`);
+  }
 
-  console.log(`Adding target: ${name}`);
+  console.log(`Adding target: ${chalk.cyan(name)}`);
   console.log(`Path: ${absolutePath}`);
 
   // Create the target directory if it doesn't exist
@@ -25,13 +43,74 @@ export async function targetAdd(name: string, path: string): Promise<void> {
     path: absolutePath,
   });
 
-  console.log(`Successfully registered target: ${name}`);
+  console.log(chalk.green(`Successfully registered target: ${name}`));
 
   // Perform initial sync
   console.log("Performing initial sync...");
   await syncToTarget({ name, path: absolutePath });
   
-  console.log(`Target "${name}" is now synced.`);
+  console.log(chalk.green(`Target "${name}" is now synced.`));
+}
+
+/**
+ * Show available predefined targets
+ */
+export async function targetAvailable(): Promise<void> {
+  const existingTargets = await getTargets();
+  const existingNames = new Set(existingTargets.map(t => t.name.toLowerCase()));
+
+  console.log();
+  console.log(chalk.bold("Available Predefined Targets"));
+  console.log(chalk.dim("─".repeat(60)));
+  console.log();
+
+  const table = new Table({
+    head: [
+      chalk.bold("Name"),
+      chalk.bold("Description"),
+      chalk.bold("Path"),
+      chalk.bold("Tool Status"),
+      chalk.bold("Added"),
+    ],
+    style: {
+      head: [],
+      border: [],
+    },
+  });
+
+  for (const target of KNOWN_TARGETS) {
+    const isAdded = existingNames.has(target.name.toLowerCase());
+    const addedStatus = isAdded ? chalk.green("✓") : chalk.dim("-");
+    
+    // Color code the tool status
+    let toolStatus: string;
+    if (target.status === "GA") {
+      toolStatus = chalk.green(target.status);
+    } else if (target.status === "Beta") {
+      toolStatus = chalk.yellow(target.status);
+    } else {
+      toolStatus = chalk.dim(target.status);
+    }
+    
+    table.push([
+      target.name,
+      target.description,
+      target.path,
+      toolStatus,
+      addedStatus,
+    ]);
+  }
+
+  console.log(table.toString());
+  console.log();
+  console.log(chalk.bold("Usage:"));
+  console.log(`  ${chalk.cyan("skills target add <name>")}              Add a predefined target`);
+  console.log(`  ${chalk.cyan("skills target add <name> <path>")}       Add a custom target`);
+  console.log();
+  console.log(chalk.bold("Examples:"));
+  console.log(`  ${chalk.cyan("skills target add cursor")}              Uses predefined path`);
+  console.log(`  ${chalk.cyan("skills target add vscode ~/.vscode/skills")}  Custom path`);
+  console.log();
 }
 
 /**

package/src/commands/update.ts

@@ -1,7 +1,7 @@
 import { $ } from "bun";
 import { rm, cp } from "fs/promises";
 import { getSources } from "../lib/config.ts";
-import { getNamespacePath, parseGitUrl } from "../lib/paths.ts";
+import { getSkillPath, parseGitUrl } from "../lib/paths.ts";
 import { directoryExists } from "../lib/hash.ts";
 
 /**
@@ -21,12 +21,12 @@ export async function update(): Promise<void> {
   for (const source of sources) {
     try {
       if (source.type === "remote") {
-        await updateRemoteSource(source.namespace, source.url!);
+        await updateRemoteSource(source.name, source.url!);
       } else {
-        await updateLocalSource(source.namespace, source.path!);
+        await updateLocalSource(source.name, source.path!);
       }
     } catch (error) {
-      console.error(`  ${source.namespace}: Failed - ${error instanceof Error ? error.message : error}`);
+      console.error(`  ${source.name}: Failed - ${error instanceof Error ? error.message : error}`);
     }
   }
 
@@ -37,8 +37,8 @@ export async function update(): Promise<void> {
 /**
  * Update a remote source by re-cloning
  */
-async function updateRemoteSource(namespace: string, url: string): Promise<void> {
-  const targetPath = getNamespacePath(namespace);
+async function updateRemoteSource(name: string, url: string): Promise<void> {
+  const targetPath = getSkillPath(name);
   const parsed = parseGitUrl(url);
   
   if (!parsed) {
@@ -48,7 +48,7 @@ async function updateRemoteSource(namespace: string, url: string): Promise<void>
   const cloneUrl = parsed.cloneUrl;
   const branch = parsed.branch || "main";
   
-  console.log(`  ${namespace}: Updating from ${url}...`);
+  console.log(`  ${name}: Updating from ${url}...`);
 
   // Remove existing directory
   await rm(targetPath, { recursive: true, force: true });
@@ -77,7 +77,7 @@ async function updateRemoteSource(namespace: string, url: string): Promise<void>
       await rm(`${targetPath}/.git`, { recursive: true, force: true });
     }
     
-    console.log(`  ${namespace}: Updated`);
+    console.log(`  ${name}: Updated`);
   } catch (error) {
     // Clean up on failure
     await rm(`${targetPath}_temp`, { recursive: true, force: true });
@@ -88,10 +88,10 @@ async function updateRemoteSource(namespace: string, url: string): Promise<void>
 /**
  * Update a local source by re-copying
  */
-async function updateLocalSource(namespace: string, sourcePath: string): Promise<void> {
-  const targetPath = getNamespacePath(namespace);
+async function updateLocalSource(name: string, sourcePath: string): Promise<void> {
+  const targetPath = getSkillPath(name);
   
-  console.log(`  ${namespace}: Updating from ${sourcePath}...`);
+  console.log(`  ${name}: Updating from ${sourcePath}...`);
 
   // Check if source still exists
   if (!(await directoryExists(sourcePath))) {
@@ -104,5 +104,5 @@ async function updateLocalSource(namespace: string, sourcePath: string): Promise
   // Re-copy
   await cp(sourcePath, targetPath, { recursive: true });
   
-  console.log(`  ${namespace}: Updated`);
+  console.log(`  ${name}: Updated`);
 }

package/src/lib/config.ts

@@ -1,4 +1,5 @@
-import { mkdir } from "fs/promises";
+import { mkdir, rename, rm } from "fs/promises";
+import { join } from "path";
 import { SKILLS_ROOT, SKILLS_STORE, CONFIG_PATH } from "./paths.ts";
 import type { Config, Source, Target } from "../types.ts";
 
@@ -17,6 +18,7 @@ export async function ensureDirectories(): Promise<void> {
 
 /**
  * Read the config file, creating it if it doesn't exist
+ * Also handles migration from old config format (namespace -> name)
  */
 export async function readConfig(): Promise<Config> {
   await ensureDirectories();
@@ -30,6 +32,30 @@ export async function readConfig(): Promise<Config> {
 
   try {
     const content = await configFile.json();
+    
+    // Migrate old config format (namespace -> name)
+    let needsMigration = false;
+    if (content.sources) {
+      for (const source of content.sources) {
+        if (source.namespace && !source.name) {
+          // Extract skill name from old namespace (e.g., "owner/skill" -> "skill")
+          const oldNamespace = source.namespace;
+          const parts = oldNamespace.split("/");
+          const newName = parts[parts.length - 1];
+          source.name = newName;
+          delete source.namespace;
+          needsMigration = true;
+          
+          // Also migrate the folder structure
+          await migrateSkillFolder(oldNamespace, newName);
+        }
+      }
+    }
+    
+    if (needsMigration) {
+      await writeConfig(content as Config);
+    }
+    
     return content as Config;
   } catch {
     // If config is corrupted, reset it
@@ -38,6 +64,41 @@ export async function readConfig(): Promise<Config> {
   }
 }
 
+/**
+ * Migrate a skill folder from old nested structure to new flat structure
+ */
+async function migrateSkillFolder(oldNamespace: string, newName: string): Promise<void> {
+  const oldPath = join(SKILLS_STORE, oldNamespace);
+  const newPath = join(SKILLS_STORE, newName);
+  
+  try {
+    // Check if old path exists
+    const oldExists = await Bun.file(join(oldPath, "SKILL.md")).exists() || 
+                      await Bun.file(oldPath).exists();
+    
+    if (oldExists) {
+      // Check if new path already exists
+      const newExists = await Bun.file(newPath).exists();
+      
+      if (!newExists) {
+        // Move the folder
+        await rename(oldPath, newPath);
+        console.log(`Migrated skill folder: ${oldNamespace} -> ${newName}`);
+        
+        // Try to clean up empty parent directories
+        const parentDir = join(SKILLS_STORE, oldNamespace.split("/")[0]);
+        try {
+          await rm(parentDir, { recursive: false });
+        } catch {
+          // Parent dir not empty or doesn't exist, ignore
+        }
+      }
+    }
+  } catch {
+    // Migration failed, folder might not exist
+  }
+}
+
 /**
  * Write the config file
  */
@@ -52,10 +113,10 @@ export async function writeConfig(config: Config): Promise<void> {
 export async function addSource(source: Source): Promise<void> {
   const config = await readConfig();
   
-  // Check if namespace already exists
-  const existing = config.sources.find(s => s.namespace === source.namespace);
+  // Check if name already exists
+  const existing = config.sources.find(s => s.name === source.name);
   if (existing) {
-    throw new Error(`Source with namespace "${source.namespace}" already exists`);
+    throw new Error(`Skill with name "${source.name}" already exists`);
   }
 
   config.sources.push(source);
@@ -65,10 +126,10 @@ export async function addSource(source: Source): Promise<void> {
 /**
  * Remove a source from the config
  */
-export async function removeSource(namespace: string): Promise<Source | null> {
+export async function removeSource(name: string): Promise<Source | null> {
   const config = await readConfig();
   
-  const index = config.sources.findIndex(s => s.namespace === namespace);
+  const index = config.sources.findIndex(s => s.name === name);
   if (index === -1) {
     return null;
   }

package/src/lib/known-targets.ts

@@ -0,0 +1,106 @@
+import { homedir } from "os";
+import { join } from "path";
+
+export interface KnownTarget {
+  name: string;
+  description: string;
+  path: string;
+  status: "GA" | "Beta" | "Experimental";
+}
+
+const home = homedir();
+
+/**
+ * Predefined target paths for common AI tools
+ * Based on official documentation for each tool's global skills folder
+ * 
+ * Reference:
+ * | Tool         | Global Skills Folder              | Status |
+ * |--------------|-----------------------------------|--------|
+ * | Claude Code  | ~/.claude/skills/                 | GA     |
+ * | Gemini CLI   | ~/.gemini/skills/                 | Beta   |
+ * | Cursor       | ~/.cursor/skills/                 | GA     |
+ * | VS Code      | ~/.copilot/skills/                | GA     |
+ * | OpenCode     | ~/.config/opencode/skills/        | GA     |
+ * | Windsurf     | ~/.windsurf/skills/               | GA     |
+ * | Antigravity  | ~/.gemini/antigravity/            | Exp.   |
+ * | Aider        | ~/.aider/skills/                  | Beta   |
+ * | Goose        | ~/.config/goose/skills/           | Beta   |
+ * | Amp          | ~/.amp/skills/                    | Beta   |
+ */
+export const KNOWN_TARGETS: KnownTarget[] = [
+  {
+    name: "cursor",
+    description: "Cursor IDE",
+    path: join(home, ".cursor", "skills"),
+    status: "GA",
+  },
+  {
+    name: "claude",
+    description: "Claude Code / Claude Desktop",
+    path: join(home, ".claude", "skills"),
+    status: "GA",
+  },
+  {
+    name: "gemini",
+    description: "Gemini CLI",
+    path: join(home, ".gemini", "skills"),
+    status: "Beta",
+  },
+  {
+    name: "copilot",
+    description: "GitHub Copilot / VS Code",
+    path: join(home, ".copilot", "skills"),
+    status: "GA",
+  },
+  {
+    name: "opencode",
+    description: "OpenCode CLI",
+    path: join(home, ".config", "opencode", "skills"),
+    status: "GA",
+  },
+  {
+    name: "windsurf",
+    description: "Windsurf IDE",
+    path: join(home, ".windsurf", "skills"),
+    status: "GA",
+  },
+  {
+    name: "antigravity",
+    description: "Antigravity",
+    path: join(home, ".gemini", "antigravity"),
+    status: "Experimental",
+  },
+  {
+    name: "aider",
+    description: "Aider CLI",
+    path: join(home, ".aider", "skills"),
+    status: "Beta",
+  },
+  {
+    name: "goose",
+    description: "Goose AI",
+    path: join(home, ".config", "goose", "skills"),
+    status: "Beta",
+  },
+  {
+    name: "amp",
+    description: "Amp AI",
+    path: join(home, ".amp", "skills"),
+    status: "Beta",
+  },
+];
+
+/**
+ * Get a known target by name
+ */
+export function getKnownTarget(name: string): KnownTarget | undefined {
+  return KNOWN_TARGETS.find(t => t.name.toLowerCase() === name.toLowerCase());
+}
+
+/**
+ * Get all known target names
+ */
+export function getKnownTargetNames(): string[] {
+  return KNOWN_TARGETS.map(t => t.name);
+}

package/src/lib/paths.ts

@@ -11,10 +11,10 @@ export const SKILLS_STORE = join(SKILLS_ROOT, "store");
 export const CONFIG_PATH = join(SKILLS_ROOT, "config.json");
 
 /**
- * Get the store path for a given namespace
+ * Get the store path for a given skill name
  */
-export function getNamespacePath(namespace: string): string {
-  return join(SKILLS_STORE, namespace);
+export function getSkillPath(name: string): string {
+  return join(SKILLS_STORE, name);
 }
 
 export interface ParsedGitUrl {
@@ -214,23 +214,20 @@ function parseGenericGitUrl(url: string): ParsedGitUrl | null {
 }
 
 /**
- * Get the namespace for a parsed Git URL
- * For subdirectories, uses owner/skill-name
- * For full repos, uses owner/repo
+ * Get the default skill name from a parsed Git URL
+ * Uses the last folder name (skill folder name)
  */
-export function getRemoteNamespace(parsed: ParsedGitUrl): string {
+export function getDefaultSkillName(parsed: ParsedGitUrl): string {
   if (parsed.subdir) {
     // Use the last part of the subdir path as the skill name
-    const subdirName = parsed.subdir.split("/").pop() || parsed.subdir;
-    return `${parsed.owner}/${subdirName}`;
+    return parsed.subdir.split("/").pop() || parsed.subdir;
   }
-  return `${parsed.owner}/${parsed.repo}`;
+  return parsed.repo;
 }
 
 /**
- * Get the local namespace for a folder path
+ * Get the default skill name from a local folder path
  */
-export function getLocalNamespace(folderPath: string): string {
-  const folderName = folderPath.split(/[\/\\]/).filter(Boolean).pop() || "unnamed";
-  return `local/${folderName}`;
+export function getLocalSkillName(folderPath: string): string {
+  return folderPath.split(/[\/\\]/).filter(Boolean).pop() || "unnamed";
 }

package/src/types.ts

@@ -8,8 +8,8 @@ export interface Source {
   url?: string;
   /** Absolute path for local sources */
   path?: string;
-  /** Store subdirectory (e.g., "anthropic/skills" or "local/my-folder") */
-  namespace: string;
+  /** Skill name used in store and targets (e.g., "react-best-practices") */
+  name: string;
 }
 
 /**