@dhruvwill/skills-cli 1.0.0 → 1.1.1

package/README.md

@@ -1,27 +1,28 @@
-# skills
+# Skills CLI
 
 > Sync AI skills across all your agent tools with one command
 
-Supports **Cursor**, **Claude Desktop**, **Gemini CLI**, **Codex**, **GitHub Copilot**, and any tool with a skills directory.
+Supports **Cursor**, **Claude Code**, **Gemini CLI**, **GitHub Copilot**, **OpenCode**, **Windsurf**, and more.
 
 [Installation](#installation) •
 [Quick Start](#quick-start) •
 [Commands](#commands) •
+[Supported Tools](#supported-tools) •
 [Configuration](#configuration) •
 [FAQ](#faq)
 
 ---
 
-## Why skills?
+## Why Skills CLI?
 
-**The problem**: You create a skill for Cursor, but need it in Claude Desktop and Gemini too. Manually copying? Tedious. What if you update it? Copy again to every tool.
+**The problem**: You create a skill for Cursor, but need it in Claude Code and Gemini too. Manually copying? Tedious. What if you update it? Copy again to every tool.
 
 **The solution**: One source of truth. Add once, sync everywhere.
 
 ```bash
-skills source add https://github.com/vercel/ai-skills --remote
-skills target add cursor ~/.cursor/skills
-skills target add claude ~/.claude/settings/skills
+skills source add https://github.com/user/repo/tree/main/skills/react --remote
+skills target add cursor
+skills target add claude
 skills sync  # Done! Skills synced to all targets
 ```
 
@@ -30,8 +31,9 @@ skills sync  # Done! Skills synced to all targets
 | Feature | Description |
 |---------|-------------|
 | 🔄 **Multi-source** | Pull from GitHub, GitLab, Bitbucket, or local folders |
-| 🎯 **Multi-target** | Sync to Cursor, Claude, Gemini, or any custom directory |
-| 📂 **Subdirectory support** | Install specific skills from large repos |
+| 🎯 **Multi-target** | Sync to Cursor, Claude, Gemini, Copilot, or any custom directory |
+| 📂 **Subdirectory support** | Install specific skills from large mono-repos |
+| 🏷️ **Rename skills** | Use `--name` to avoid conflicts |
 | 🔍 **Diagnostics** | `doctor` command checks your setup |
 | ⚡ **Fast** | Built with Bun for maximum performance |
 
@@ -41,14 +43,20 @@ skills sync  # Done! Skills synced to all targets
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) runtime
+- [Bun](https://bun.sh) runtime (required - uses Bun shell)
 - Git (for remote sources)
 
 ### Install via Bun
 
+```bash
+bun install -g @dhruvwill/skills-cli
+```
+
+### Install from Source
+
 ```bash
 # Clone the repository
-git clone https://github.com/yourusername/skills.git
+git clone https://github.com/dhruvwill/skills.git
 cd skills
 
 # Install dependencies
@@ -58,8 +66,6 @@ bun install
 bun link
 ```
 
-After linking, the `skills` command is available globally.
-
 ### Verify Installation
 
 ```bash
@@ -72,12 +78,12 @@ skills doctor
 ## Quick Start
 
 ```bash
-# 1. Add a skill source (from GitHub)
+# 1. Add a skill from GitHub
 skills source add https://github.com/vercel-labs/agent-skills/tree/main/skills/react-best-practices --remote
 
-# 2. Add your targets (where skills should be synced)
-skills target add cursor ~/.cursor/skills
-skills target add claude ~/.claude/settings/skills
+# 2. Add your targets (path auto-detected for known tools)
+skills target add cursor
+skills target add claude
 
 # 3. Sync!
 skills sync
@@ -86,7 +92,7 @@ skills sync
 Check your setup anytime:
 
 ```bash
-skills status   # Overview of sources & targets
+skills status   # Overview of skills & targets
 skills doctor   # Diagnose issues
 ```
 
@@ -104,8 +110,7 @@ skills doctor   # Diagnose issues
 ┌─────────────────────────────────────────────────────────────┐
 │                    ~/.skills/store/                         │
 │                                                             │
-│   vercel-labs/           anthropic/         local/          │
-│   └── react-best-...     └── cursor-...     └── my-skill/   │
+│   react-best-practices/    my-custom-skill/    local-skill/ │
 │                                                             │
 │                   ⬆ Single Source of Truth ⬆                │
 └─────────────────────────────────────────────────────────────┘
@@ -114,7 +119,7 @@ skills doctor   # Diagnose issues
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
 ┌───────────────┐     ┌───────────────┐     ┌───────────────┐
-│    Cursor     │     │ Claude Desktop│     │  Gemini CLI   │
+│    Cursor     │     │  Claude Code  │     │  Gemini CLI   │
 │ ~/.cursor/    │     │ ~/.claude/    │     │ ~/.gemini/    │
 │    skills/    │     │    skills/    │     │    skills/    │
 └───────────────┘     └───────────────┘     └───────────────┘
@@ -128,31 +133,66 @@ skills doctor   # Diagnose issues
 
 | Command | Description |
 |---------|-------------|
-| `skills status` | Show overview of sources, targets & sync state |
+| `skills status` | Show overview of skills, targets & sync state |
 | `skills doctor` | Diagnose configuration issues |
 | `skills sync` | Push skills from store to all targets |
-| `skills update` | Refresh all sources from origin |
+| `skills update` | Refresh all skills from origin |
 
-### Source Management
+### Skill Management
 
 | Command | Description |
 |---------|-------------|
-| `skills source list` | List all registered sources |
-| `skills source add <url> --remote` | Add a remote Git repository |
-| `skills source add <path> --local` | Add a local folder |
-| `skills source remove <namespace>` | Remove a source |
+| `skills source list` | List all registered skills |
+| `skills source add <url> --remote` | Add a skill from Git repository |
+| `skills source add <path> --local` | Add a skill from local folder |
+| `skills source add <url> --remote --name <name>` | Add with custom name |
+| `skills source remove <name>` | Remove a skill by name |
 
 ### Target Management
 
 | Command | Description |
 |---------|-------------|
 | `skills target list` | List all targets with sync status |
-| `skills target add <name> <path>` | Add a target directory |
+| `skills target available` | Show predefined targets with paths |
+| `skills target add <name>` | Add a predefined target (auto-detects path) |
+| `skills target add <name> <path>` | Add a custom target with specific path |
 | `skills target remove <name>` | Remove a target |
 
 ---
 
-## Adding Sources
+## Supported Tools
+
+Run `skills target available` to see all supported tools:
+
+| Tool | Path |
+|------|------|
+| **Cursor** | `~/.cursor/skills/` |
+| **Claude Code** | `~/.claude/skills/` |
+| **Gemini CLI** | `~/.gemini/skills/` |
+| **VS Code / Copilot** | `~/.copilot/skills/` |
+| **OpenCode** | `~/.config/opencode/skills/` |
+| **Windsurf** | `~/.windsurf/skills/` |
+| **Antigravity** | `~/.gemini/antigravity/skills/` |
+
+### Adding Predefined Targets
+
+```bash
+# Just use the name - path is auto-detected
+skills target add cursor
+skills target add claude
+skills target add gemini
+```
+
+### Adding Custom Targets
+
+```bash
+# For tools not in the list, specify the path
+skills target add mytool ~/path/to/mytool/skills
+```
+
+---
+
+## Adding Skills
 
 ### From GitHub
 
@@ -161,7 +201,10 @@ skills doctor   # Diagnose issues
 skills source add https://github.com/owner/repo --remote
 
 # Specific subdirectory (great for mono-repos)
-skills source add https://github.com/owner/repo/tree/main/skills/specific-skill --remote
+skills source add https://github.com/owner/repo/tree/main/skills/my-skill --remote
+
+# With custom name (to avoid conflicts)
+skills source add https://github.com/owner/repo --remote --name my-custom-name
 ```
 
 ### From GitLab
@@ -187,26 +230,6 @@ skills source add /absolute/path/to/skills --local
 
 ---
 
-## Adding Targets
-
-Add any directory where you want skills synced:
-
-```bash
-# Cursor
-skills target add cursor ~/.cursor/skills
-
-# Claude Desktop
-skills target add claude ~/.claude/settings/skills
-
-# Gemini CLI
-skills target add gemini ~/.gemini/skills
-
-# Custom location
-skills target add myapp ~/myapp/ai-skills
-```
-
----
-
 ## Configuration
 
 ### Directory Structure
@@ -214,11 +237,28 @@ skills target add myapp ~/myapp/ai-skills
 ```
 ~/.skills/
 ├── store/                    # Central repository for all skills
-│   ├── owner/skill-name/     # Remote sources (owner/skill format)
-│   └── local/folder-name/    # Local sources
+│   ├── react-best-practices/ # Each skill in its own folder
+│   │   ├── SKILL.md
+│   │   └── rules/
+│   └── my-custom-skill/
+│       └── SKILL.md
 └── config.json               # Registry of sources and targets
 ```
 
+### Skill Folder Structure
+
+Each skill should follow this structure:
+
+```
+skill-name/
+├── SKILL.md          # Main skill definition (required)
+├── AGENTS.md         # Agent behavior (optional)
+├── rules/            # Additional rules (optional)
+│   ├── rule-1.md
+│   └── rule-2.md
+└── metadata.json     # Skill metadata (optional)
+```
+
 ### Config File
 
 Located at `~/.skills/config.json`:
@@ -229,18 +269,22 @@ Located at `~/.skills/config.json`:
     {
       "type": "remote",
       "url": "https://github.com/owner/repo/tree/main/skills/my-skill",
-      "namespace": "owner/my-skill"
+      "name": "my-skill"
     },
     {
       "type": "local",
       "path": "/home/user/my-skills",
-      "namespace": "local/my-skills"
+      "name": "my-local-skill"
     }
   ],
   "targets": [
     {
       "name": "cursor",
       "path": "/home/user/.cursor/skills"
+    },
+    {
+      "name": "claude",
+      "path": "/home/user/.claude/skills"
     }
   ]
 }
@@ -257,14 +301,27 @@ Skills CLI provides:
 - **Git integration** - Pull updates from remote repos with `skills update`
 - **Subdirectory support** - Install specific skills from large mono-repos
 - **Status tracking** - Know which targets are synced or outdated
+- **Auto-detection** - No need to remember paths for common tools
 
-### Can I sync to a custom/uncommon tool?
+### What happens when I run `skills sync`?
 
-Yes! Use `skills target add <name> <path>` with any directory path.
+The contents of `~/.skills/store/` are copied to all registered target directories, maintaining the folder structure:
 
-### What happens when I run `skills sync`?
+```
+~/.skills/store/my-skill/  →  ~/.cursor/skills/my-skill/
+                           →  ~/.claude/skills/my-skill/
+                           →  ~/.gemini/skills/my-skill/
+```
+
+### How do I handle naming conflicts?
 
-The contents of `~/.skills/store/` are copied to all registered target directories.
+Use the `--name` flag when adding skills:
+
+```bash
+# Two different "utils" skills from different repos
+skills source add https://github.com/user1/repo --remote --name user1-utils
+skills source add https://github.com/user2/repo --remote --name user2-utils
+```
 
 ### How do I update skills from remote sources?
 
@@ -273,13 +330,12 @@ skills update  # Pulls latest from all remote sources
 skills sync    # Pushes to all targets
 ```
 
-### What if a source URL changes?
+### Can I add a tool that's not in the predefined list?
 
-Remove the old source and add the new one:
+Yes! Just specify the path:
 
 ```bash
-skills source remove owner/old-skill
-skills source add https://github.com/owner/new-skill --remote
+skills target add mytool ~/path/to/mytool/skills
 ```
 
 ---
@@ -290,25 +346,33 @@ skills source add https://github.com/owner/new-skill --remote
 
 Install Git from [git-scm.com](https://git-scm.com/) or via your package manager.
 
-### "Source already exists"
+### "Skill already exists"
 
-Remove it first, then re-add:
+Either remove it first or use `--name` to give it a different name:
 
 ```bash
-skills source remove owner/skill-name
+skills source remove old-skill
 skills source add <url> --remote
+
+# Or use a different name
+skills source add <url> --remote --name new-name
 ```
 
-### "Target directory missing"
+### "Unknown target"
+
+The target isn't in the predefined list. Specify the path:
 
-The directory will be created automatically when you run `skills sync`.
+```bash
+skills target add mytool ~/path/to/skills
+```
 
 ### Need help?
 
 ```bash
-skills doctor  # Run diagnostics
-skills status  # Check current state
-skills --help  # Show all commands
+skills doctor        # Run diagnostics
+skills status        # Check current state
+skills target available  # See predefined targets
+skills --help        # Show all commands
 ```
 
 ---
@@ -316,12 +380,17 @@ skills --help  # Show all commands
 ## Contributing
 
 ```bash
-git clone https://github.com/yourusername/skills.git
+git clone https://github.com/dhruvwill/skills.git
 cd skills
 bun install
 bun test
 ```
 
+## Links
+
+- **npm**: [npmjs.com/package/@dhruvwill/skills-cli](https://www.npmjs.com/package/@dhruvwill/skills-cli)
+- **GitHub**: [github.com/dhruvwill/skills](https://github.com/dhruvwill/skills)
+
 ---
 
 ## License

package/_config.yml

@@ -0,0 +1,9 @@
+title: Skills CLI
+description: Sync AI skills across all your agent tools
+remote_theme: pages-themes/cayman@v0.2.0
+plugins:
+  - jekyll-remote-theme
+
+# Show README.md as the index page
+index:
+  path: README.md

package/index.ts

@@ -1,2 +1,2 @@
-// Re-export CLI for programmatic use
+// Re-export CLI for programmatic use
 export * from "./src/cli.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhruvwill/skills-cli",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "A CLI tool for syncing AI skills across all your agent tools",
   "module": "src/cli.ts",
   "type": "module",

package/src/cli.ts

@@ -2,13 +2,13 @@
 
 import chalk from "chalk";
 import { sourceAdd, sourceRemove, sourceList } from "./commands/source.ts";
-import { targetAdd, targetRemove, targetList } from "./commands/target.ts";
+import { targetAdd, targetRemove, targetList, targetAvailable } from "./commands/target.ts";
 import { sync } from "./commands/sync.ts";
 import { update } from "./commands/update.ts";
 import { doctor } from "./commands/doctor.ts";
 import { status } from "./commands/status.ts";
 
-const VERSION = "1.0.0";
+const VERSION = "1.1.0";
 
 function printHelp() {
   console.log(`
@@ -18,47 +18,65 @@ ${chalk.bold("USAGE")}
   ${chalk.cyan("skills")} <command> [options]
 
 ${chalk.bold("COMMANDS")}
-  ${chalk.cyan("status")}                        Show overview of sources, targets & sync state
+  ${chalk.cyan("status")}                        Show overview of skills, targets & sync state
   ${chalk.cyan("doctor")}                        Diagnose configuration issues
 
-  ${chalk.bold("Source Management")}
-  ${chalk.cyan("source list")}                   List all registered sources
-  ${chalk.cyan("source add")} <url> ${chalk.dim("--remote")}     Add a remote Git repository
-  ${chalk.cyan("source add")} <path> ${chalk.dim("--local")}     Add a local folder
-  ${chalk.cyan("source remove")} <namespace>     Remove a source
+  ${chalk.bold("Skill Management")}
+  ${chalk.cyan("source list")}                   List all registered skills
+  ${chalk.cyan("source add")} <url> ${chalk.dim("--remote")}     Add a skill from Git repository
+  ${chalk.cyan("source add")} <path> ${chalk.dim("--local")}     Add a skill from local folder
+  ${chalk.cyan("source remove")} <name>          Remove a skill by name
 
   ${chalk.bold("Target Management")}
   ${chalk.cyan("target list")}                   List all targets with sync status
-  ${chalk.cyan("target add")} <name> <path>      Add a target directory
+  ${chalk.cyan("target available")}              Show predefined targets (cursor, claude, etc.)
+  ${chalk.cyan("target add")} <name>             Add a predefined target (auto-detects path)
+  ${chalk.cyan("target add")} <name> <path>      Add a custom target with specific path
   ${chalk.cyan("target remove")} <name>          Remove a target
 
   ${chalk.bold("Synchronization")}
   ${chalk.cyan("sync")}                          Push skills from store to all targets
-  ${chalk.cyan("update")}                        Refresh all sources from origin
+  ${chalk.cyan("update")}                        Refresh all skills from origin
 
 ${chalk.bold("OPTIONS")}
+  ${chalk.cyan("--name <name>")}                 Custom name for the skill (avoids conflicts)
+  ${chalk.cyan("--remote")}                      Source is a Git repository
+  ${chalk.cyan("--local")}                       Source is a local folder
   ${chalk.cyan("--help, -h")}                    Show this help message
   ${chalk.cyan("--version, -v")}                 Show version
 
 ${chalk.bold("EXAMPLES")}
-  ${chalk.dim("# Add skills from GitHub (supports subdirectories)")}
-  ${chalk.cyan("skills source add")} https://github.com/vercel/ai-skills --remote
-  ${chalk.cyan("skills source add")} https://github.com/user/repo/tree/main/skills/my-skill --remote
+  ${chalk.dim("# Add a skill from GitHub")}
+  ${chalk.cyan("skills source add")} https://github.com/user/repo/tree/main/skills/react --remote
 
-  ${chalk.dim("# Add skills from GitLab or Bitbucket")}
+  ${chalk.dim("# Add with custom name (to avoid conflicts)")}
+  ${chalk.cyan("skills source add")} https://github.com/user/repo --remote --name my-react-skill
+
+  ${chalk.dim("# Add from GitLab or Bitbucket")}
   ${chalk.cyan("skills source add")} https://gitlab.com/user/repo --remote
   ${chalk.cyan("skills source add")} https://bitbucket.org/user/repo --remote
 
   ${chalk.dim("# Add local skills folder")}
   ${chalk.cyan("skills source add")} ./my-local-skills --local
 
-  ${chalk.dim("# Add targets and sync")}
-  ${chalk.cyan("skills target add")} cursor ~/.cursor/skills
-  ${chalk.cyan("skills target add")} claude ~/.claude/settings/skills
+  ${chalk.dim("# Add predefined targets (path auto-detected)")}
+  ${chalk.cyan("skills target add")} cursor
+  ${chalk.cyan("skills target add")} claude
+  ${chalk.cyan("skills target add")} gemini
+
+  ${chalk.dim("# Add custom target with specific path")}
+  ${chalk.cyan("skills target add")} myapp ~/myapp/skills
+
+  ${chalk.dim("# Sync to all targets")}
   ${chalk.cyan("skills sync")}
 
+${chalk.bold("FOLDER STRUCTURE")}
+  ${chalk.dim("After sync, skills are stored as:")}
+  ~/.cursor/skills/skill-name/SKILL.md
+  ~/.claude/skills/skill-name/SKILL.md
+
 ${chalk.bold("DOCUMENTATION")}
-  ${chalk.dim("https://github.com/yourusername/skills")}
+  ${chalk.dim("https://github.com/dhruvwill/skills")}
 `);
 }
 
@@ -122,9 +140,15 @@ async function main() {
 async function handleSourceCommand(subcommand: string, args: string[]) {
   switch (subcommand) {
     case "add": {
-      const pathOrUrl = args[0];
+      // Filter out flags to get the path/URL
+      const nonFlagArgs = args.filter(a => !a.startsWith("--"));
+      const pathOrUrl = nonFlagArgs[0];
       const isRemote = args.includes("--remote");
       const isLocal = args.includes("--local");
+      
+      // Extract --name value
+      const nameIndex = args.findIndex(a => a === "--name");
+      const customName = nameIndex !== -1 ? args[nameIndex + 1] : undefined;
 
       if (!pathOrUrl) {
         console.error("Missing path or URL for source add");
@@ -141,17 +165,17 @@ async function handleSourceCommand(subcommand: string, args: string[]) {
         process.exit(1);
       }
 
-      await sourceAdd(pathOrUrl, isRemote ? "remote" : "local");
+      await sourceAdd(pathOrUrl, isRemote ? "remote" : "local", customName);
       break;
     }
 
     case "remove": {
-      const namespace = args[0];
-      if (!namespace) {
-        console.error("Missing namespace for source remove");
+      const name = args[0];
+      if (!name) {
+        console.error("Missing skill name for source remove");
         process.exit(1);
       }
-      await sourceRemove(namespace);
+      await sourceRemove(name);
       break;
     }
 
@@ -170,10 +194,11 @@ async function handleTargetCommand(subcommand: string, args: string[]) {
   switch (subcommand) {
     case "add": {
       const name = args[0];
-      const path = args[1];
+      const path = args[1]; // Optional - if not provided, uses known target
 
-      if (!name || !path) {
-        console.error("Usage: skills target add <name> <path>");
+      if (!name) {
+        console.error("Usage: skills target add <name> [path]");
+        console.log(`\nRun ${chalk.cyan("skills target available")} to see predefined targets.`);
         process.exit(1);
       }
 
@@ -195,9 +220,13 @@ async function handleTargetCommand(subcommand: string, args: string[]) {
       await targetList();
       break;
 
+    case "available":
+      await targetAvailable();
+      break;
+
     default:
       console.error(`Unknown target subcommand: ${subcommand}`);
-      console.log("Available: add, remove, list");
+      console.log("Available: add, remove, list, available");
       process.exit(1);
   }
 }

package/src/commands/doctor.ts

@@ -1,7 +1,7 @@
 import chalk from "chalk";
 import { $ } from "bun";
 import { getSources, getTargets } from "../lib/config.ts";
-import { getNamespacePath, SKILLS_ROOT, SKILLS_STORE, CONFIG_PATH } from "../lib/paths.ts";
+import { getSkillPath, SKILLS_ROOT, SKILLS_STORE, CONFIG_PATH } from "../lib/paths.ts";
 import { directoryExists } from "../lib/hash.ts";
 
 interface DiagnosticResult {
@@ -176,18 +176,18 @@ async function checkSources(): Promise<DiagnosticResult[]> {
     }
 
     for (const source of sources) {
-      const path = getNamespacePath(source.namespace);
+      const path = getSkillPath(source.name);
       const exists = await directoryExists(path);
       
       if (exists) {
         results.push({
-          name: `Source: ${source.namespace}`,
+          name: `Skill: ${source.name}`,
           status: "ok",
           message: `${source.type} → ${path}`,
         });
       } else {
         results.push({
-          name: `Source: ${source.namespace}`,
+          name: `Skill: ${source.name}`,
           status: "error",
           message: `Missing directory: ${path}. Run: skills update`,
         });