@skillsmanager/cli 0.0.2 → 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

@@ -1,26 +1,56 @@
 import fs from "fs";
-import readline from "readline";
+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() {
     const { client_id, client_secret } = readCredentials();
-    return new google.auth.OAuth2(client_id, client_secret, "urn:ietf:wg:oauth:2.0:oob");
+    return new google.auth.OAuth2(client_id, client_secret, REDIRECT_URI);
 }
 function saveToken(client) {
     ensureConfigDir();
     fs.writeFileSync(TOKEN_PATH, JSON.stringify(client.credentials, null, 2));
 }
-function prompt(question) {
-    const rl = readline.createInterface({
-        input: process.stdin,
-        output: process.stdout,
-    });
-    return new Promise((resolve) => {
-        rl.question(question, (answer) => {
-            rl.close();
-            resolve(answer.trim());
+/**
+ * Starts a temporary local HTTP server to receive the OAuth redirect,
+ * extracts the authorization code, and resolves the promise.
+ */
+function waitForAuthCode() {
+    return new Promise((resolve, reject) => {
+        const server = http.createServer((req, res) => {
+            const url = new URL(req.url ?? "/", `http://localhost:${LOOPBACK_PORT}`);
+            const code = url.searchParams.get("code");
+            const error = url.searchParams.get("error");
+            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;
+            }
+            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);
+            }
+            else {
+                res.writeHead(400, { "Content-Type": "text/html" });
+                res.end("<h2>Missing authorization code.</h2>");
+            }
         });
+        server.listen(LOOPBACK_PORT, () => { });
+        server.on("error", (err) => reject(new Error(`Could not start auth server on port ${LOOPBACK_PORT}: ${err.message}`)));
     });
 }
 export async function runAuthFlow() {
@@ -32,13 +62,23 @@ export async function runAuthFlow() {
     });
     console.log("\nOpen this URL in your browser to authorize Skills Manager:\n");
     console.log(authUrl);
-    console.log();
-    const code = await prompt("Paste the authorization code here: ");
+    console.log("\nWaiting for authorization...");
+    const code = await waitForAuthCode();
     const { tokens } = await client.getToken(code);
     client.setCredentials(tokens);
     saveToken(client);
     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

@@ -3,7 +3,6 @@ import type { StorageBackend } from "./interface.js";
 import type { CollectionFile, CollectionInfo, RegistryCollectionRef, RegistryFile, RegistryInfo } from "../types.js";
 export declare class GDriveBackend implements StorageBackend {
     private drive;
-    private oauth2;
     constructor(auth: OAuth2Client);
     getOwner(): Promise<string>;
     getOwnerEmail(): Promise<string>;
@@ -13,6 +12,8 @@ export declare class GDriveBackend implements StorageBackend {
     downloadSkill(collection: CollectionInfo, skillName: string, destDir: string): Promise<void>;
     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

@@ -7,14 +7,12 @@ import { randomUUID } from "crypto";
 const FOLDER_MIME = "application/vnd.google-apps.folder";
 export class GDriveBackend {
     drive;
-    oauth2;
     constructor(auth) {
         this.drive = google.drive({ version: "v3", auth });
-        this.oauth2 = google.oauth2({ version: "v2", auth });
     }
     async getOwner() {
-        const res = await this.oauth2.userinfo.get();
-        return res.data.email ?? "";
+        const res = await this.drive.about.get({ fields: "user(emailAddress)" });
+        return res.data.user?.emailAddress ?? "";
     }
     // Alias for backwards compat
     async getOwnerEmail() {
@@ -180,6 +178,19 @@ export class GDriveBackend {
             registryFileId: fileRes.data.id ?? undefined,
         };
     }
+    async deleteCollection(collection) {
+        // Trash the collection folder on Drive (moves to trash, not permanent delete)
+        await this.drive.files.update({
+            fileId: collection.folderId,
+            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

@@ -0,0 +1,27 @@
+import type { StorageBackend } from "./interface.js";
+import type { CollectionFile, CollectionInfo, RegistryCollectionRef, RegistryFile, RegistryInfo } from "../types.js";
+export declare class GithubBackend implements StorageBackend {
+    getOwner(): Promise<string>;
+    ensureRepo(repo: string): Promise<void>;
+    private ensureWorkdir;
+    private gitPushOrPR;
+    private commitAndPush;
+    discoverCollections(): Promise<Omit<CollectionInfo, "id">[]>;
+    readCollection(collection: CollectionInfo): Promise<CollectionFile>;
+    writeCollection(collection: CollectionInfo, data: CollectionFile): Promise<void>;
+    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, skillsRepoRef?: string): Promise<CollectionInfo>;
+    static detectRepoContext(absPath: string): {
+        repo: string;
+        repoRoot: string;
+        relPath: string;
+    } | null;
+}