@skillsmanager/cli 0.0.4 → 0.0.5

package/LICENSE

@@ -1,21 +1,13 @@
-MIT License
+Copyright 2026 Ajay Prakash
 
-Copyright (c) 2026 Ajay Prakash
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+    http://www.apache.org/licenses/LICENSE-2.0
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -1,58 +1,107 @@
+[![npm](https://img.shields.io/npm/v/%40skillsmanager%2Fcli)](https://www.npmjs.com/package/@skillsmanager/cli)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![CI](https://github.com/talktoajayprakash/skillsmanager/actions/workflows/release.yml/badge.svg)](https://github.com/talktoajayprakash/skillsmanager/actions)
+[![Docs](https://img.shields.io/badge/docs-skillsmanager-blue)](https://talktoajayprakash.github.io/skillsmanager)
+
 # Skills Manager
 
-A CLI for AI agents to discover, fetch, and share agent skills stored in Google Drive.
+**One place to manage, sync, and share all your AI agent skills — across every agent you use.**
+
+You build skills for your AI agents, but keeping track of them is a mess. They're scattered across GitHub repos, local folders, and machines. Each agent has its own directory. Nothing is searchable. Nothing is shared.
+
+Skills Manager fixes this. It gives every skill a home — in Google Drive, GitHub, or any storage backend you choose — and makes them instantly available to any agent via a single CLI command. Your agents can search, fetch, and use any skill regardless of where it lives.
+
+Build skills confidently, store them where you want, and sync them across every device and agent you work with — Claude, Cursor, OpenAI Codex, OpenClaw, and beyond.
+
+## Why Skills Manager?
+
+- **Unified skill library** — one searchable index across all your skills, wherever they're stored
+- **Cross-agent** — install any skill into Claude, Cursor, Windsurf, Copilot, Gemini, and more
+- **Backend-agnostic** — store in Google Drive, GitHub, Dropbox, AWS S3, or local filesystem
+- **Sync across devices** — skills follow you, not your machine
+- **No duplication** — cached once locally, symlinked into each agent's directory
+- **Git-friendly** — plain Markdown files, easy to version-control and review
 
-## What is it?
+## Supported Agents
 
-Skills Manager lets you maintain a personal library of agent skills in Google Drive and install them into any supported AI agent (Claude, Cursor, Windsurf, Copilot, etc.) with a single command.
+`claude` · `codex` · `cursor` · `windsurf` · `copilot` · `gemini` · `roo` · `openclaw` · `agents`
 
-Skills are downloaded to a local cache (`~/.skillsmanager/cache/`) and symlinked into the agent's skills directory. No duplication — one copy, many agents.
+> **OpenClaw users:** OpenClaw's skill system uses the same `SKILL.md` format and directory-based loading that Skills Manager is built around. Your OpenClaw skills are first-class citizens — store them in any backend, search them, and sync them across devices just like any other skill.
+>
+> Any agent that reads from a skills directory works with Skills Manager. If your agent can read a file, it can use your skills.
 
-## Supported agents
+## Quick Start
 
-`claude`, `codex`, `cursor`, `windsurf`, `copilot`, `gemini`, `roo`, `agents`
+### 1. Install
 
-## Installation
+```bash
+npm install -g @skillsmanager/cli
+```
+
+### 2. Install the skillsmanager skill (lets your agent drive Skills Manager)
 
 ```bash
-npm install -g skillsmanager
+skillsmanager install
 ```
 
-## Google Drive setup
+This installs the bundled `skillsmanager` skill into all detected agents so your AI assistant can manage skills on your behalf.
 
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a project → enable the **Google Drive API**
-3. Create OAuth 2.0 credentials (Desktop app)
+### 3. One-time Google Drive setup
+
+Skills Manager uses Google Drive as a remote registry. To connect it:
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/) and create a project
+2. Enable the **Google Drive API** for that project
+3. Create **OAuth 2.0 credentials** (Desktop app type)
 4. Download `credentials.json` and save it to `~/.skillsmanager/credentials.json`
 
-## Usage
+Then authenticate and discover your registries:
 
 ```bash
-# Authenticate and discover registries
-skillsmanager init
+skillsmanager setup google   # walks you through OAuth
+skillsmanager refresh        # discovers collections in your Drive
+```
 
-# List all available skills
-skillsmanager list
+## Commands
 
-# Search skills by name or description
-skillsmanager search <query>
+| Command | Description |
+|---|---|
+| `skillsmanager install` | Install the skillsmanager skill to all agents |
+| `skillsmanager list` | List all available skills |
+| `skillsmanager search <query>` | Search skills by name or description |
+| `skillsmanager fetch <name> --agent <agent>` | Download and install a skill for an agent |
+| `skillsmanager add <path>` | Upload a local skill to a collection |
+| `skillsmanager update <path>` | Push local changes back to remote storage |
+| `skillsmanager refresh` | Re-discover collections from remote |
+| `skillsmanager collection create` | Create a new skill collection |
+| `skillsmanager registry push --backend gdrive` | Push local registry to Google Drive |
 
-# Download a skill and install it for an agent
-skillsmanager fetch <skill-name> --agent claude
+## Local Development
 
-# Add a local skill to your registry
-skillsmanager add ./my-skill
+```bash
+git clone https://github.com/talktoajayprakash/skillsmanager.git
+cd skillsmanager
+npm install
+npm run build       # compiles TypeScript to dist/
+npm link            # makes `skillsmanager` available globally from source
+```
 
-# Push local changes to an existing skill back to Drive
-skillsmanager update <skill-name>
+Run tests:
 
-# Re-scan Drive for new registries
-skillsmanager refresh
+```bash
+npm test
+```
+
+To run without installing globally:
+
+```bash
+node dist/index.js <command>
 ```
 
 ## Registry format
 
-Skills are indexed by a `SKILLS_SYNC.yaml` file inside any Google Drive folder you own:
+Skills are indexed by a `SKILLS_REGISTRY.yaml` file inside any Google Drive folder you own:
 
 ```yaml
 name: my-skills
@@ -61,12 +110,9 @@ skills:
   - name: code-review
     path: code-review/
     description: Reviews code for bugs, style, and security issues
-  - name: write-tests
-    path: write-tests/
-    description: Generates unit tests for a given function or module
 ```
 
-Each skill is a directory containing a `SKILL.md` file with YAML frontmatter:
+Each skill is a directory with a `SKILL.md` file:
 
 ```markdown
 ---
@@ -77,8 +123,16 @@ description: Reviews code for bugs, style, and security issues
 ... skill instructions ...
 ```
 
-Skills Manager auto-discovers any `SKILLS_SYNC.yaml` file owned by your Google account, so registries are found automatically on `skillsmanager init` or `skillsmanager refresh`.
+Skills Manager auto-discovers any `SKILLS_REGISTRY.yaml` in your Google account on `refresh`.
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) — PRs welcome.
+
+## Security
+
+See [SECURITY.md](./SECURITY.md) for how to report vulnerabilities.
 
-## Design doc
+## License
 
-See [WRITEUP.md](./WRITEUP.md) for the full design.
+[Apache 2.0](LICENSE)

package/dist/auth.d.ts

@@ -1,5 +1,6 @@
 import type { OAuth2Client } from "google-auth-library";
 export declare function runAuthFlow(): Promise<OAuth2Client>;
+export declare function getAuthedEmail(client: OAuth2Client): Promise<string | null>;
 export declare function getAuthClient(): OAuth2Client;
 export declare function hasToken(): boolean;
 export declare function ensureAuth(): Promise<OAuth2Client>;

package/dist/auth.js

@@ -2,7 +2,11 @@ import fs from "fs";
 import http from "http";
 import { google } from "googleapis";
 import { TOKEN_PATH, ensureConfigDir, readCredentials, credentialsExist } from "./config.js";
-const SCOPES = ["https://www.googleapis.com/auth/drive"];
+const SCOPES = [
+    "https://www.googleapis.com/auth/drive",
+    "openid",
+    "https://www.googleapis.com/auth/userinfo.email",
+];
 const LOOPBACK_PORT = 3847;
 const REDIRECT_URI = `http://localhost:${LOOPBACK_PORT}`;
 function createOAuth2Client() {
@@ -26,6 +30,8 @@ function waitForAuthCode() {
             if (error) {
                 res.writeHead(200, { "Content-Type": "text/html" });
                 res.end("<h2>Authorization failed.</h2><p>You can close this tab.</p>");
+                res.socket?.destroy();
+                server.closeAllConnections?.();
                 server.close();
                 reject(new Error(`OAuth error: ${error}`));
                 return;
@@ -33,6 +39,8 @@ function waitForAuthCode() {
             if (code) {
                 res.writeHead(200, { "Content-Type": "text/html" });
                 res.end("<h2>Authorization successful!</h2><p>You can close this tab and return to the terminal.</p>");
+                res.socket?.destroy();
+                server.closeAllConnections?.();
                 server.close();
                 resolve(code);
             }
@@ -59,9 +67,18 @@ export async function runAuthFlow() {
     const { tokens } = await client.getToken(code);
     client.setCredentials(tokens);
     saveToken(client);
-    console.log("Authorization successful.");
     return client;
 }
+export async function getAuthedEmail(client) {
+    try {
+        const oauth2 = google.oauth2({ version: "v2", auth: client });
+        const res = await oauth2.userinfo.get();
+        return res.data.email ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export function getAuthClient() {
     if (!fs.existsSync(TOKEN_PATH)) {
         throw new Error(`Not authenticated. Run "skillsmanager init" first.`);

package/dist/backends/gdrive.d.ts

@@ -13,6 +13,7 @@ export declare class GDriveBackend implements StorageBackend {
     private downloadFolder;
     createCollection(folderName: string): Promise<CollectionInfo>;
     deleteCollection(collection: CollectionInfo): Promise<void>;
+    deleteSkill(collection: CollectionInfo, skillName: string): Promise<void>;
     uploadSkill(collection: CollectionInfo, localPath: string, skillName: string): Promise<void>;
     discoverRegistries(): Promise<Omit<RegistryInfo, "id">[]>;
     readRegistry(registry: RegistryInfo): Promise<RegistryFile>;

package/dist/backends/gdrive.js

@@ -185,6 +185,12 @@ export class GDriveBackend {
             requestBody: { trashed: true },
         });
     }
+    async deleteSkill(collection, skillName) {
+        const folderId = await this.findFolder(skillName, collection.folderId);
+        if (folderId) {
+            await this.drive.files.update({ fileId: folderId, requestBody: { trashed: true } });
+        }
+    }
     async uploadSkill(collection, localPath, skillName) {
         let folderId = await this.findFolder(skillName, collection.folderId);
         if (!folderId) {

package/dist/backends/github.d.ts

@@ -12,12 +12,13 @@ export declare class GithubBackend implements StorageBackend {
     downloadSkill(collection: CollectionInfo, skillName: string, destDir: string): Promise<void>;
     uploadSkill(collection: CollectionInfo, localPath: string, skillName: string): Promise<void>;
     deleteCollection(collection: CollectionInfo): Promise<void>;
+    deleteSkill(collection: CollectionInfo, skillName: string): Promise<void>;
     discoverRegistries(): Promise<Omit<RegistryInfo, "id">[]>;
     readRegistry(registry: RegistryInfo): Promise<RegistryFile>;
     writeRegistry(registry: RegistryInfo, data: RegistryFile): Promise<void>;
     resolveCollectionRef(ref: RegistryCollectionRef): Promise<Omit<CollectionInfo, "id"> | null>;
     createRegistry(name?: string, repoRef?: string): Promise<RegistryInfo>;
-    createCollection(collectionName: string, repoRef?: string): Promise<CollectionInfo>;
+    createCollection(collectionName: string, repoRef?: string, skillsRepoRef?: string): Promise<CollectionInfo>;
     static detectRepoContext(absPath: string): {
         repo: string;
         repoRoot: string;

package/dist/backends/github.js

@@ -20,6 +20,10 @@ function parseRef(folderId) {
 function workdirFor(repo) {
     return path.join(GITHUB_WORKDIR, repo.replace("/", "_"));
 }
+/** Returns the repo where skill files live — defaults to the collection host repo. */
+function skillsRepo(col, hostRepo) {
+    return col.metadata?.repo ?? hostRepo;
+}
 // ── CLI helpers ───────────────────────────────────────────────────────────────
 function ghExec(args, opts) {
     const r = spawnSync("gh", args, {
@@ -206,26 +210,33 @@ export class GithubBackend {
         await this.commitAndPush(workdir, `chore: update ${COLLECTION_FILENAME} for ${collection.name}`);
     }
     async downloadSkill(collection, skillName, destDir) {
-        const { repo } = parseRef(collection.folderId);
-        const workdir = this.ensureWorkdir(repo);
-        // Refresh to get latest
-        gitExec(["pull", "--ff-only"], workdir);
+        const { repo: hostRepo } = parseRef(collection.folderId);
         const col = await this.readCollection(collection);
         const entry = col.skills.find((s) => s.name === skillName);
         if (!entry) {
             throw new Error(`Skill "${skillName}" not found in collection "${collection.name}"`);
         }
+        const srcRepo = skillsRepo(col, hostRepo);
+        const workdir = this.ensureWorkdir(srcRepo);
+        gitExec(["pull", "--ff-only"], workdir);
         const skillPath = path.join(workdir, entry.path);
         if (!fs.existsSync(skillPath)) {
-            throw new Error(`Skill directory not found at "${entry.path}" in repo "${repo}"`);
+            throw new Error(`Skill directory not found at "${entry.path}" in repo "${srcRepo}"`);
         }
         if (path.resolve(skillPath) !== path.resolve(destDir)) {
             copyDirSync(skillPath, destDir);
         }
     }
     async uploadSkill(collection, localPath, skillName) {
-        const { repo } = parseRef(collection.folderId);
-        const workdir = this.ensureWorkdir(repo);
+        const { repo: hostRepo } = parseRef(collection.folderId);
+        // If collection points to a foreign skills repo, we can't upload there
+        const col = await this.readCollection(collection);
+        const foreign = col.metadata?.repo;
+        if (foreign && foreign !== hostRepo) {
+            throw new Error(`Cannot upload skill to collection "${collection.name}": its skills source is "${foreign}" (a repo you may not own). ` +
+                `Use --remote-path to register a skill path from that repo instead.`);
+        }
+        const workdir = this.ensureWorkdir(hostRepo);
         const resolvedLocal = path.resolve(localPath);
         const resolvedWorkdir = path.resolve(workdir);
         if (resolvedLocal.startsWith(resolvedWorkdir + path.sep) ||
@@ -249,6 +260,21 @@ export class GithubBackend {
         gitExec(["add", "-A"], workdir);
         await this.commitAndPush(workdir, `chore: remove collection ${collection.name}`);
     }
+    async deleteSkill(collection, skillName) {
+        const { repo: hostRepo } = parseRef(collection.folderId);
+        const col = await this.readCollection(collection);
+        const entry = col.skills.find((s) => s.name === skillName);
+        if (!entry)
+            return;
+        const srcRepo = skillsRepo(col, hostRepo);
+        const workdir = this.ensureWorkdir(srcRepo);
+        const skillPath = path.join(workdir, entry.path);
+        if (!fs.existsSync(skillPath))
+            return;
+        fs.rmSync(skillPath, { recursive: true, force: true });
+        gitExec(["add", "-A"], workdir);
+        await this.commitAndPush(workdir, `chore: remove skill ${skillName}`);
+    }
     // ── Registry operations ───────────────────────────────────────────────────────
     async discoverRegistries() {
         const r = ghExec(["repo", "list", "--json", "nameWithOwner", "--limit", "100"]);
@@ -332,7 +358,7 @@ export class GithubBackend {
         };
     }
     // ── createCollection ─────────────────────────────────────────────────────────
-    async createCollection(collectionName, repoRef) {
+    async createCollection(collectionName, repoRef, skillsRepoRef) {
         if (!repoRef)
             throw new Error("GitHub backend requires --repo <owner/repo>");
         const repo = repoRef;
@@ -343,6 +369,9 @@ export class GithubBackend {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const owner = await this.getOwner();
         const colData = { name: collectionName, owner, skills: [] };
+        if (skillsRepoRef && skillsRepoRef !== repo) {
+            colData.metadata = { repo: skillsRepoRef };
+        }
         fs.writeFileSync(filePath, serializeCollection(colData));
         gitExec(["add", path.join(metaDir, COLLECTION_FILENAME)], workdir);
         await this.commitAndPush(workdir, `chore: init collection ${collectionName}`);

package/dist/backends/interface.d.ts

@@ -7,6 +7,7 @@ export interface StorageBackend {
     downloadSkill(collection: CollectionInfo, skillName: string, destDir: string): Promise<void>;
     uploadSkill(collection: CollectionInfo, localPath: string, skillName: string): Promise<void>;
     deleteCollection(collection: CollectionInfo): Promise<void>;
+    deleteSkill(collection: CollectionInfo, skillName: string): Promise<void>;
     discoverRegistries(): Promise<Omit<RegistryInfo, "id">[]>;
     readRegistry(registry: RegistryInfo): Promise<RegistryFile>;
     writeRegistry(registry: RegistryInfo, data: RegistryFile): Promise<void>;

package/dist/backends/local.d.ts

@@ -12,6 +12,7 @@ export declare class LocalBackend implements StorageBackend {
     downloadSkill(collection: CollectionInfo, skillName: string, destDir: string): Promise<void>;
     uploadSkill(collection: CollectionInfo, localPath: string, skillName: string): Promise<void>;
     deleteCollection(collection: CollectionInfo): Promise<void>;
+    deleteSkill(collection: CollectionInfo, skillName: string): Promise<void>;
     discoverRegistries(): Promise<Omit<RegistryInfo, "id">[]>;
     readRegistry(registry: RegistryInfo): Promise<RegistryFile>;
     writeRegistry(registry: RegistryInfo, data: RegistryFile): Promise<void>;

package/dist/backends/local.js

@@ -78,6 +78,12 @@ export class LocalBackend {
             fs.rmSync(collection.folderId, { recursive: true, force: true });
         }
     }
+    async deleteSkill(collection, skillName) {
+        const skillPath = path.join(collection.folderId, skillName);
+        if (fs.existsSync(skillPath)) {
+            fs.rmSync(skillPath, { recursive: true, force: true });
+        }
+    }
     // ── Registry operations ──────────────────────────────────────────────────
     async discoverRegistries() {
         if (!fs.existsSync(LOCAL_REGISTRY_PATH))

package/dist/commands/add.d.ts

@@ -1,3 +1,6 @@
 export declare function addCommand(skillPath: string, options: {
     collection?: string;
+    remotePath?: string;
+    name?: string;
+    description?: string;
 }): Promise<void>;

package/dist/commands/add.js

@@ -7,6 +7,11 @@ import { readConfig, trackSkill } from "../config.js";
 import { GithubBackend } from "../backends/github.js";
 import { resolveBackend } from "../backends/resolve.js";
 export async function addCommand(skillPath, options) {
+    // ── Remote-path mode: register a skill from a foreign repo without local files ─
+    if (options.remotePath) {
+        await addRemotePath(options);
+        return;
+    }
     const absPath = path.resolve(skillPath);
     if (!fs.existsSync(absPath) || !fs.statSync(absPath).isDirectory()) {
         console.log(chalk.red(`"${skillPath}" is not a valid directory.`));
@@ -75,21 +80,136 @@ export async function addCommand(skillPath, options) {
         console.log(chalk.red("No collections configured. Run: skillsmanager collection create"));
         return;
     }
+    // If the collection has metadata.repo (foreign skills repo), handle specially
+    if (collection.backend === "github") {
+        const github = new GithubBackend();
+        const col = await github.readCollection(collection);
+        const foreignRepo = col.metadata?.repo;
+        if (foreignRepo) {
+            const ctx = GithubBackend.detectRepoContext(absPath);
+            if (!ctx || ctx.repo !== foreignRepo) {
+                console.log(chalk.red(`This collection's skills source is "${foreignRepo}". ` +
+                    `The provided path does not belong to that repo.\n` +
+                    chalk.dim(`  To register a skill by path without a local clone, use:\n`) +
+                    chalk.dim(`  skillsmanager add --collection ${collection.name} --remote-path <rel/path> --name <name> --description <desc>`)));
+                return;
+            }
+            // Path is from the foreign repo (cloned locally) — register relative path only, no upload
+            const spinner = ora(`Adding ${chalk.bold(skillName)} to ${collection.name}...`).start();
+            try {
+                const existing = col.skills.findIndex((s) => s.name === skillName);
+                const entry = { name: skillName, path: ctx.relPath, description };
+                if (existing >= 0) {
+                    col.skills[existing] = entry;
+                }
+                else {
+                    col.skills.push(entry);
+                }
+                await github.writeCollection(collection, col);
+                trackSkill(skillName, collection.id, absPath);
+                spinner.succeed(`${chalk.bold(skillName)} registered in ${collection.name} at ${chalk.dim(ctx.relPath)}`);
+            }
+            catch (err) {
+                spinner.fail(`Failed: ${err.message}`);
+            }
+            return;
+        }
+    }
     const backend = await resolveBackend(collection.backend);
     await uploadToCollection(backend, collection, absPath, skillName, description);
 }
+// ── Remote-path mode: register a skill entry without local files ─────────────
+async function addRemotePath(options) {
+    const { remotePath, name: skillName, description = "", collection: collectionName } = options;
+    if (!remotePath) {
+        console.log(chalk.red("--remote-path requires a relative path (e.g. tools/my-skill/)"));
+        return;
+    }
+    if (!skillName) {
+        console.log(chalk.red("--remote-path requires --name <skill-name>"));
+        return;
+    }
+    let config;
+    try {
+        config = readConfig();
+    }
+    catch {
+        console.log(chalk.red("No config found. Run: skillsmanager collection create"));
+        return;
+    }
+    let collection = config.collections[0];
+    if (collectionName) {
+        const found = config.collections.find((c) => c.name === collectionName);
+        if (!found) {
+            console.log(chalk.red(`Collection "${collectionName}" not found.`));
+            console.log(chalk.dim(`  Available: ${config.collections.map((c) => c.name).join(", ")}`));
+            return;
+        }
+        collection = found;
+    }
+    if (!collection) {
+        console.log(chalk.red("No collections configured. Run: skillsmanager collection create"));
+        return;
+    }
+    if (collection.backend !== "github") {
+        console.log(chalk.red("--remote-path is only supported for GitHub collections."));
+        return;
+    }
+    const github = new GithubBackend();
+    const spinner = ora(`Registering ${chalk.bold(skillName)} in ${collection.name} at ${chalk.dim(remotePath)}...`).start();
+    try {
+        const col = await github.readCollection(collection);
+        const existing = col.skills.findIndex((s) => s.name === skillName);
+        const entry = { name: skillName, path: remotePath, description };
+        if (existing >= 0) {
+            col.skills[existing] = entry;
+        }
+        else {
+            col.skills.push(entry);
+        }
+        await github.writeCollection(collection, col);
+        spinner.succeed(`${chalk.bold(skillName)} registered in ${collection.name} at ${chalk.dim(remotePath)}`);
+    }
+    catch (err) {
+        spinner.fail(`Failed: ${err.message}`);
+    }
+}
 // ── GitHub path: register in-repo skill or copy external skill ────────────────
 async function addToGithub(absPath, ctx, skillName, description, collection) {
     const github = new GithubBackend();
     const spinner = ora(`Adding ${chalk.bold(skillName)} to github:${collection.folderId}...`).start();
     try {
+        const col = await github.readCollection(collection);
+        const foreignRepo = col.metadata?.repo;
+        const hostRepo = collection.folderId.split(":")[0];
+        // If collection has metadata.repo pointing to a foreign repo, validate that
+        // the local skill belongs to that foreign repo (not the collection host repo).
+        if (foreignRepo && foreignRepo !== hostRepo) {
+            if (ctx.repo !== foreignRepo) {
+                spinner.fail(`This collection's skills source is "${foreignRepo}" but the provided path belongs to "${ctx.repo}".`);
+                return;
+            }
+            // Skill is in the foreign repo (cloned locally) — register path only, no upload
+            const entry = { name: skillName, path: ctx.relPath, description };
+            const existing = col.skills.findIndex((s) => s.name === skillName);
+            if (existing >= 0) {
+                col.skills[existing] = entry;
+            }
+            else {
+                col.skills.push(entry);
+            }
+            await github.writeCollection(collection, col);
+            trackSkill(skillName, collection.id, absPath);
+            spinner.succeed(`${chalk.bold(skillName)} registered in github:${collection.folderId} at ${chalk.dim(ctx.relPath)}`);
+            return;
+        }
+        // Standard case: skill is in (or being added to) the collection's host repo
         // uploadSkill is a no-op for in-repo skills; copies if external
         await github.uploadSkill(collection, absPath, skillName);
         // Determine effective skill path in the repo
         const skillEntry = absPath.startsWith(ctx.repoRoot)
             ? ctx.relPath // in-repo: use relative path
             : `.agentskills/${skillName}`; // external: was copied here by uploadSkill
-        const col = await github.readCollection(collection);
         const existing = col.skills.findIndex((s) => s.name === skillName);
         if (existing >= 0) {
             col.skills[existing] = { name: skillName, path: skillEntry, description };

package/dist/commands/collection.d.ts

@@ -1,4 +1,5 @@
 export declare function collectionCreateCommand(name?: string, options?: {
     backend?: string;
     repo?: string;
+    skillsRepo?: string;
 }): Promise<void>;