@skillsmanager/cli 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ajay Prakash
+
+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:
+
+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.

package/README.md

@@ -0,0 +1,84 @@
+# Skills Manager
+
+A CLI for AI agents to discover, fetch, and share agent skills stored in Google Drive.
+
+## What is it?
+
+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.
+
+Skills are downloaded to a local cache (`~/.skillsmanager/cache/`) and symlinked into the agent's skills directory. No duplication — one copy, many agents.
+
+## Supported agents
+
+`claude`, `codex`, `cursor`, `windsurf`, `copilot`, `gemini`, `roo`, `agents`
+
+## Installation
+
+```bash
+npm install -g skillsmanager
+```
+
+## Google Drive setup
+
+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)
+4. Download `credentials.json` and save it to `~/.skillsmanager/credentials.json`
+
+## Usage
+
+```bash
+# Authenticate and discover registries
+skillsmanager init
+
+# List all available skills
+skillsmanager list
+
+# Search skills by name or description
+skillsmanager search <query>
+
+# Download a skill and install it for an agent
+skillsmanager fetch <skill-name> --agent claude
+
+# Add a local skill to your registry
+skillsmanager add ./my-skill
+
+# Push local changes to an existing skill back to Drive
+skillsmanager update <skill-name>
+
+# Re-scan Drive for new registries
+skillsmanager refresh
+```
+
+## Registry format
+
+Skills are indexed by a `SKILLS_SYNC.yaml` file inside any Google Drive folder you own:
+
+```yaml
+name: my-skills
+owner: you@example.com
+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:
+
+```markdown
+---
+name: code-review
+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`.
+
+## Design doc
+
+See [WRITEUP.md](./WRITEUP.md) for the full design.

package/dist/auth.d.ts

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

package/dist/auth.js

@@ -0,0 +1,68 @@
+import fs from "fs";
+import readline from "readline";
+import { google } from "googleapis";
+import { TOKEN_PATH, ensureConfigDir, readCredentials, credentialsExist } from "./config.js";
+const SCOPES = ["https://www.googleapis.com/auth/drive"];
+function createOAuth2Client() {
+    const { client_id, client_secret } = readCredentials();
+    return new google.auth.OAuth2(client_id, client_secret, "urn:ietf:wg:oauth:2.0:oob");
+}
+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());
+        });
+    });
+}
+export async function runAuthFlow() {
+    const client = createOAuth2Client();
+    const authUrl = client.generateAuthUrl({
+        access_type: "offline",
+        scope: SCOPES,
+        prompt: "consent",
+    });
+    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: ");
+    const { tokens } = await client.getToken(code);
+    client.setCredentials(tokens);
+    saveToken(client);
+    return client;
+}
+export function getAuthClient() {
+    if (!fs.existsSync(TOKEN_PATH)) {
+        throw new Error(`Not authenticated. Run "skillsmanager init" first.`);
+    }
+    const client = createOAuth2Client();
+    const token = JSON.parse(fs.readFileSync(TOKEN_PATH, "utf-8"));
+    client.setCredentials(token);
+    client.on("tokens", (newTokens) => {
+        const merged = { ...client.credentials, ...newTokens };
+        client.setCredentials(merged);
+        saveToken(client);
+    });
+    return client;
+}
+export function hasToken() {
+    return fs.existsSync(TOKEN_PATH);
+}
+export async function ensureAuth() {
+    if (!credentialsExist()) {
+        throw new Error("No credentials found. Run: skillsmanager setup google");
+    }
+    if (!hasToken()) {
+        console.log("Not authenticated — launching login...\n");
+        return runAuthFlow();
+    }
+    return getAuthClient();
+}

package/dist/backends/gdrive.d.ts

@@ -0,0 +1,24 @@
+import type { OAuth2Client } from "google-auth-library";
+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>;
+    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>;
+    private downloadFolder;
+    createCollection(folderName: string): Promise<CollectionInfo>;
+    uploadSkill(collection: CollectionInfo, localPath: string, 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): Promise<RegistryInfo>;
+    private findFolder;
+    private uploadFolder;
+}

package/dist/backends/gdrive.js

@@ -0,0 +1,371 @@
+import fs from "fs";
+import path from "path";
+import { google } from "googleapis";
+import { parseCollection, serializeCollection, parseRegistryFile, serializeRegistryFile, COLLECTION_FILENAME, LEGACY_COLLECTION_FILENAME, REGISTRY_FILENAME, } from "../registry.js";
+import { Readable } from "stream";
+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 ?? "";
+    }
+    // Alias for backwards compat
+    async getOwnerEmail() {
+        return this.getOwner();
+    }
+    // ── Collection operations ────────────────────────────────────────────────
+    async discoverCollections() {
+        const collections = [];
+        let pageToken;
+        do {
+            const res = await this.drive.files.list({
+                q: `(name='${COLLECTION_FILENAME}' or name='${LEGACY_COLLECTION_FILENAME}') and 'me' in owners and trashed=false`,
+                fields: "nextPageToken, files(id, name, parents)",
+                pageSize: 100,
+                ...(pageToken ? { pageToken } : {}),
+            });
+            pageToken = res.data.nextPageToken ?? undefined;
+            for (const file of res.data.files ?? []) {
+                const parentId = file.parents?.[0];
+                if (!parentId)
+                    continue;
+                const parent = await this.drive.files.get({
+                    fileId: parentId,
+                    fields: "id, name",
+                });
+                const rawName = parent.data.name ?? "unknown";
+                collections.push({
+                    name: rawName.replace(/^SKILLS_/i, ""),
+                    backend: "gdrive",
+                    folderId: parentId,
+                    registryFileId: file.id ?? undefined,
+                });
+            }
+        } while (pageToken);
+        return collections;
+    }
+    async readCollection(collection) {
+        let fileId = collection.registryFileId;
+        if (!fileId) {
+            // Try new filename first, fall back to legacy
+            for (const filename of [COLLECTION_FILENAME, LEGACY_COLLECTION_FILENAME]) {
+                const res = await this.drive.files.list({
+                    q: `name='${filename}' and '${collection.folderId}' in parents and trashed=false`,
+                    fields: "files(id)",
+                    pageSize: 1,
+                });
+                fileId = res.data.files?.[0]?.id ?? undefined;
+                if (fileId)
+                    break;
+            }
+            if (!fileId) {
+                throw new Error(`Collection file not found in "${collection.name}"`);
+            }
+        }
+        const res = await this.drive.files.get({ fileId, alt: "media" }, { responseType: "text" });
+        return parseCollection(res.data);
+    }
+    async writeCollection(collection, data) {
+        const content = serializeCollection(data);
+        const media = {
+            mimeType: "text/yaml",
+            body: Readable.from(content),
+        };
+        if (collection.registryFileId) {
+            await this.drive.files.update({
+                fileId: collection.registryFileId,
+                media,
+            });
+        }
+        else {
+            // Try to find existing file (new or legacy name)
+            let existingId;
+            for (const filename of [COLLECTION_FILENAME, LEGACY_COLLECTION_FILENAME]) {
+                const res = await this.drive.files.list({
+                    q: `name='${filename}' and '${collection.folderId}' in parents and trashed=false`,
+                    fields: "files(id)",
+                    pageSize: 1,
+                });
+                existingId = res.data.files?.[0]?.id ?? undefined;
+                if (existingId)
+                    break;
+            }
+            if (existingId) {
+                await this.drive.files.update({ fileId: existingId, media });
+            }
+            else {
+                await this.drive.files.create({
+                    requestBody: {
+                        name: COLLECTION_FILENAME,
+                        parents: [collection.folderId],
+                    },
+                    media,
+                });
+            }
+        }
+    }
+    async downloadSkill(collection, skillName, destDir) {
+        const res = await this.drive.files.list({
+            q: `name='${skillName}' and '${collection.folderId}' in parents and mimeType='${FOLDER_MIME}' and trashed=false`,
+            fields: "files(id, name)",
+            pageSize: 1,
+        });
+        const skillFolder = res.data.files?.[0];
+        if (!skillFolder?.id) {
+            throw new Error(`Skill folder "${skillName}" not found in collection "${collection.name}"`);
+        }
+        await this.downloadFolder(skillFolder.id, destDir);
+    }
+    async downloadFolder(folderId, destDir) {
+        fs.mkdirSync(destDir, { recursive: true });
+        let pageToken;
+        do {
+            const res = await this.drive.files.list({
+                q: `'${folderId}' in parents and trashed=false`,
+                fields: "nextPageToken, files(id, name, mimeType)",
+                pageSize: 100,
+                ...(pageToken ? { pageToken } : {}),
+            });
+            pageToken = res.data.nextPageToken ?? undefined;
+            for (const file of res.data.files ?? []) {
+                if (file.mimeType === FOLDER_MIME) {
+                    await this.downloadFolder(file.id, path.join(destDir, file.name));
+                }
+                else {
+                    const filePath = path.join(destDir, file.name);
+                    const fileRes = await this.drive.files.get({ fileId: file.id, alt: "media" }, { responseType: "stream" });
+                    await new Promise((resolve, reject) => {
+                        const dest = fs.createWriteStream(filePath);
+                        fileRes.data.pipe(dest);
+                        dest.on("finish", resolve);
+                        dest.on("error", reject);
+                    });
+                }
+            }
+        } while (pageToken);
+    }
+    async createCollection(folderName) {
+        const folderRes = await this.drive.files.create({
+            requestBody: {
+                name: folderName,
+                mimeType: FOLDER_MIME,
+            },
+            fields: "id, name",
+        });
+        const folderId = folderRes.data.id;
+        const owner = await this.getOwnerEmail();
+        const logicalName = folderName.replace(/^SKILLS_/i, "");
+        const emptyCollection = { name: logicalName, owner, skills: [] };
+        const content = serializeCollection(emptyCollection);
+        const fileRes = await this.drive.files.create({
+            requestBody: {
+                name: COLLECTION_FILENAME,
+                parents: [folderId],
+            },
+            media: { mimeType: "text/yaml", body: Readable.from(content) },
+            fields: "id",
+        });
+        return {
+            id: randomUUID(),
+            name: logicalName,
+            backend: "gdrive",
+            folderId,
+            registryFileId: fileRes.data.id ?? undefined,
+        };
+    }
+    async uploadSkill(collection, localPath, skillName) {
+        let folderId = await this.findFolder(skillName, collection.folderId);
+        if (!folderId) {
+            const res = await this.drive.files.create({
+                requestBody: {
+                    name: skillName,
+                    mimeType: FOLDER_MIME,
+                    parents: [collection.folderId],
+                },
+                fields: "id",
+            });
+            folderId = res.data.id;
+        }
+        await this.uploadFolder(localPath, folderId);
+    }
+    // ── Registry operations ──────────────────────────────────────────────────
+    async discoverRegistries() {
+        const registries = [];
+        let pageToken;
+        do {
+            const res = await this.drive.files.list({
+                q: `name='${REGISTRY_FILENAME}' and 'me' in owners and trashed=false`,
+                fields: "nextPageToken, files(id, name, parents)",
+                pageSize: 100,
+                ...(pageToken ? { pageToken } : {}),
+            });
+            pageToken = res.data.nextPageToken ?? undefined;
+            for (const file of res.data.files ?? []) {
+                const parentId = file.parents?.[0];
+                if (!parentId)
+                    continue;
+                const parent = await this.drive.files.get({
+                    fileId: parentId,
+                    fields: "id, name",
+                });
+                registries.push({
+                    name: (parent.data.name ?? "unknown").replace(/^SKILLS_/i, ""),
+                    backend: "gdrive",
+                    folderId: parentId,
+                    fileId: file.id ?? undefined,
+                });
+            }
+        } while (pageToken);
+        return registries;
+    }
+    async readRegistry(registry) {
+        let fileId = registry.fileId;
+        if (!fileId) {
+            const res = await this.drive.files.list({
+                q: `name='${REGISTRY_FILENAME}' and '${registry.folderId}' in parents and trashed=false`,
+                fields: "files(id)",
+                pageSize: 1,
+            });
+            fileId = res.data.files?.[0]?.id ?? undefined;
+            if (!fileId) {
+                throw new Error(`Registry file not found for "${registry.name}"`);
+            }
+        }
+        const res = await this.drive.files.get({ fileId, alt: "media" }, { responseType: "text" });
+        return parseRegistryFile(res.data);
+    }
+    async writeRegistry(registry, data) {
+        const content = serializeRegistryFile(data);
+        const media = { mimeType: "text/yaml", body: Readable.from(content) };
+        if (registry.fileId) {
+            await this.drive.files.update({ fileId: registry.fileId, media });
+        }
+        else {
+            const res = await this.drive.files.list({
+                q: `name='${REGISTRY_FILENAME}' and '${registry.folderId}' in parents and trashed=false`,
+                fields: "files(id)",
+                pageSize: 1,
+            });
+            const existingId = res.data.files?.[0]?.id;
+            if (existingId) {
+                await this.drive.files.update({ fileId: existingId, media });
+            }
+            else {
+                await this.drive.files.create({
+                    requestBody: { name: REGISTRY_FILENAME, parents: [registry.folderId] },
+                    media,
+                });
+            }
+        }
+    }
+    async resolveCollectionRef(ref) {
+        if (ref.backend !== "gdrive")
+            return null;
+        // Search for folder by name (try with SKILLS_ prefix and without)
+        const names = ref.ref.startsWith("SKILLS_") ? [ref.ref] : [`SKILLS_${ref.ref}`, ref.ref];
+        for (const name of names) {
+            const res = await this.drive.files.list({
+                q: `name='${name}' and mimeType='${FOLDER_MIME}' and 'me' in owners and trashed=false`,
+                fields: "files(id, name)",
+                pageSize: 1,
+            });
+            const folder = res.data.files?.[0];
+            if (folder?.id) {
+                return {
+                    name: (folder.name ?? name).replace(/^SKILLS_/i, ""),
+                    backend: "gdrive",
+                    folderId: folder.id,
+                };
+            }
+        }
+        return null;
+    }
+    async createRegistry(name) {
+        const folderName = name ? `SKILLS_REGISTRY_${name}` : "SKILLS_REGISTRY";
+        const folderRes = await this.drive.files.create({
+            requestBody: { name: folderName, mimeType: FOLDER_MIME },
+            fields: "id, name",
+        });
+        const folderId = folderRes.data.id;
+        const owner = await this.getOwnerEmail();
+        const registryData = {
+            name: name ?? "default",
+            owner,
+            source: "gdrive",
+            collections: [],
+        };
+        const fileRes = await this.drive.files.create({
+            requestBody: { name: REGISTRY_FILENAME, parents: [folderId] },
+            media: { mimeType: "text/yaml", body: Readable.from(serializeRegistryFile(registryData)) },
+            fields: "id",
+        });
+        return {
+            id: randomUUID(),
+            name: name ?? "default",
+            backend: "gdrive",
+            folderId,
+            fileId: fileRes.data.id ?? undefined,
+        };
+    }
+    // ── Private helpers ──────────────────────────────────────────────────────
+    async findFolder(name, parentId) {
+        const res = await this.drive.files.list({
+            q: `name='${name}' and '${parentId}' in parents and mimeType='${FOLDER_MIME}' and trashed=false`,
+            fields: "files(id)",
+            pageSize: 1,
+        });
+        return res.data.files?.[0]?.id ?? null;
+    }
+    async uploadFolder(localDir, parentId) {
+        for (const entry of fs.readdirSync(localDir, { withFileTypes: true })) {
+            if (entry.name.startsWith("."))
+                continue;
+            const fullPath = path.join(localDir, entry.name);
+            if (entry.isDirectory()) {
+                let subFolderId = await this.findFolder(entry.name, parentId);
+                if (!subFolderId) {
+                    const res = await this.drive.files.create({
+                        requestBody: {
+                            name: entry.name,
+                            mimeType: FOLDER_MIME,
+                            parents: [parentId],
+                        },
+                        fields: "id",
+                    });
+                    subFolderId = res.data.id;
+                }
+                await this.uploadFolder(fullPath, subFolderId);
+            }
+            else {
+                const existing = await this.drive.files.list({
+                    q: `name='${entry.name}' and '${parentId}' in parents and trashed=false`,
+                    fields: "files(id)",
+                    pageSize: 1,
+                });
+                const media = {
+                    mimeType: "application/octet-stream",
+                    body: fs.createReadStream(fullPath),
+                };
+                if (existing.data.files?.[0]?.id) {
+                    await this.drive.files.update({
+                        fileId: existing.data.files[0].id,
+                        media,
+                    });
+                }
+                else {
+                    await this.drive.files.create({
+                        requestBody: { name: entry.name, parents: [parentId] },
+                        media,
+                    });
+                }
+            }
+        }
+    }
+}

package/dist/backends/interface.d.ts

@@ -0,0 +1,14 @@
+import type { CollectionFile, CollectionInfo, RegistryCollectionRef, RegistryFile, RegistryInfo } from "../types.js";
+export interface StorageBackend {
+    getOwner(): Promise<string>;
+    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>;
+    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): Promise<RegistryInfo>;
+}

package/dist/backends/interface.js

@@ -0,0 +1 @@
+export {};

package/dist/backends/local.d.ts

@@ -0,0 +1,20 @@
+import type { StorageBackend } from "./interface.js";
+import type { CollectionFile, CollectionInfo, RegistryCollectionRef, RegistryFile, RegistryInfo } from "../types.js";
+/**
+ * Local filesystem backend — stores collections and the registry under ~/.skillsmanager/.
+ * Works with zero setup, no auth, no internet. This is the default backend.
+ */
+export declare class LocalBackend implements StorageBackend {
+    getOwner(): Promise<string>;
+    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>;
+    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): Promise<RegistryInfo>;
+    createCollection(name: string): Promise<CollectionInfo>;
+}