@rohilaharsh/skills-pm 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Harsh Rohila
+
+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,148 @@
+# skills-pm
+
+A package manager for [Cursor](https://cursor.com) agent skills. Install skills from public or private GitHub repositories with a single command.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org) >= 18 or [Bun](https://bun.sh)
+- Git (for cloning repositories)
+
+## Installation
+
+```bash
+# Run without installing
+npx @rohilaharsh/skills-pm <command>
+bunx @rohilaharsh/skills-pm <command>
+
+# Or install globally
+npm install -g @rohilaharsh/skills-pm
+```
+
+## Usage
+
+### Install a skill
+
+```bash
+# From a public repo (owner/repo shorthand)
+skills-pm add vercel-labs/agent-skills -s frontend-design
+
+# From a full GitHub URL
+skills-pm add https://github.com/vercel-labs/agent-skills -s frontend-design
+
+# From a specific branch
+skills-pm add owner/repo -s my-skill --ref develop
+
+# From a specific tag
+skills-pm add owner/repo -s my-skill --ref v1.2.0
+
+# From a specific commit SHA
+skills-pm add owner/repo -s my-skill --ref abc123f
+
+# Install globally (available across all projects)
+skills-pm add owner/repo -s my-skill -g
+```
+
+The `-s` (or `--skill`) flag is required. You must specify the skill name to install.
+
+### Private repositories
+
+Private repos work automatically if you have git credentials configured (SSH keys, HTTPS credentials, or a git credential helper). No extra setup needed.
+
+```bash
+skills-pm add my-org/private-skills-repo -s internal-skill
+```
+
+### List installed skills
+
+```bash
+# Show all installed skills (project + global)
+skills-pm list
+
+# Show only global skills
+skills-pm list -g
+
+# Alias
+skills-pm ls
+```
+
+### Remove a skill
+
+```bash
+# Remove from project
+skills-pm remove my-skill
+
+# Remove from global
+skills-pm remove my-skill -g
+
+# Alias
+skills-pm rm my-skill
+```
+
+## How it works
+
+1. **Clone** — The repository is shallow-cloned into `~/.cache/skills-pm/<owner>/<repo>/<ref>/`
+2. **Discover** — SKILL.md files are found by scanning [standard search paths](https://github.com/vercel-labs/skills#skill-discovery) used by the agent skills ecosystem
+3. **Filter** — The skill matching the `-s` name is selected
+4. **Symlink** — The skill directory is symlinked into the target location
+5. **Record** — Metadata is written to track installed skills
+
+### Installation paths
+
+| Scope | Skills directory | Metadata file |
+|-------|-----------------|---------------|
+| Project (default) | `.agents/skills/<name>/` | `.skills-pm.json` |
+| Global (`-g`) | `~/.cursor/skills/<name>/` | `~/.cache/skills-pm/global.json` |
+
+### Skill discovery
+
+The tool searches repositories using the same paths as [vercel-labs/skills](https://github.com/vercel-labs/skills):
+
+- Root `SKILL.md`
+- `skills/`, `skills/.curated/`, `skills/.experimental/`, `skills/.system/`
+- Agent-specific directories (`.agents/skills/`, `.claude/skills/`, `.cursor/skills/`, etc.)
+- Recursive fallback if no skills found in standard locations
+
+A valid `SKILL.md` file must have YAML frontmatter with `name` and `description`:
+
+```markdown
+---
+name: my-skill
+description: What this skill does
+---
+
+# My Skill
+
+Instructions for the agent...
+```
+
+## Options reference
+
+| Option | Description |
+|--------|-------------|
+| `-s, --skill <name>` | Skill name to install (required for `add`) |
+| `--ref <ref>` | Git branch, tag, or commit SHA (default: default branch) |
+| `-g, --global` | Use global scope instead of project |
+| `-h, --help` | Show help message |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Build for distribution
+bun run build
+
+# Run from source
+bun run src/cli.ts add owner/repo -s skill-name
+
+# Run the built version
+node dist/cli.js add owner/repo -s skill-name
+```
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,418 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { parseArgs } from "util";
+
+// src/source-parser.ts
+function parseSource(input) {
+  if (!input) {
+    throw new Error("Source cannot be empty");
+  }
+  if (input.startsWith("https://github.com/")) {
+    const path = input.replace("https://github.com/", "").replace(/\.git$/, "").replace(/\/$/, "");
+    return parseShorthand(path);
+  }
+  return parseShorthand(input);
+}
+function parseShorthand(path) {
+  const parts = path.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    throw new Error(`Invalid source "${path}". Expected format: owner/repo or https://github.com/owner/repo`);
+  }
+  return { owner: parts[0], repo: parts[1] };
+}
+
+// src/git.ts
+import { join } from "path";
+import { stat } from "fs/promises";
+import { execFile } from "child_process";
+function execGit(args) {
+  return new Promise((resolve, reject) => {
+    execFile("git", args, { maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) {
+        reject(new Error(`git ${args[0]} failed (exit ${error.code}): ${stderr.trim()}`));
+      } else {
+        resolve({ stdout, stderr });
+      }
+    });
+  });
+}
+async function cloneRepo(source, options) {
+  const refLabel = options.ref ?? "HEAD";
+  const destDir = join(options.cacheBase, source.owner, source.repo, refLabel);
+  if (await dirExists(destDir)) {
+    return destDir;
+  }
+  const url = `https://github.com/${source.owner}/${source.repo}.git`;
+  const cloneArgs = ["clone", "--depth", "1"];
+  if (options.ref) {
+    cloneArgs.push("--branch", options.ref);
+  }
+  cloneArgs.push(url, destDir);
+  await execGit(cloneArgs);
+  return destDir;
+}
+async function dirExists(path) {
+  try {
+    const s = await stat(path);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// src/discover.ts
+import { join as join2 } from "path";
+import { readdir, stat as stat2 } from "fs/promises";
+var SEARCH_DIRS = [
+  "skills",
+  "skills/.curated",
+  "skills/.experimental",
+  "skills/.system",
+  ".agents/skills",
+  ".augment/skills",
+  ".claude/skills",
+  ".codebuddy/skills",
+  ".commandcode/skills",
+  ".continue/skills",
+  ".cortex/skills",
+  ".crush/skills",
+  ".factory/skills",
+  ".goose/skills",
+  ".junie/skills",
+  ".iflow/skills",
+  ".kilocode/skills",
+  ".kiro/skills",
+  ".kode/skills",
+  ".mcpjam/skills",
+  ".vibe/skills",
+  ".mux/skills",
+  ".openhands/skills",
+  ".pi/skills",
+  ".qoder/skills",
+  ".qwen/skills",
+  ".roo/skills",
+  ".trae/skills",
+  ".windsurf/skills",
+  ".zencoder/skills",
+  ".neovate/skills",
+  ".pochi/skills",
+  ".adal/skills"
+];
+async function discoverSkillPaths(repoDir) {
+  const found = [];
+  const rootSkill = join2(repoDir, "SKILL.md");
+  if (await fileExists(rootSkill)) {
+    found.push(rootSkill);
+  }
+  for (const dir of SEARCH_DIRS) {
+    const fullDir = join2(repoDir, dir);
+    if (!await dirExists2(fullDir))
+      continue;
+    const entries = await readdir(fullDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory())
+        continue;
+      const skillMd = join2(fullDir, entry.name, "SKILL.md");
+      if (await fileExists(skillMd)) {
+        found.push(skillMd);
+      }
+    }
+  }
+  if (found.length > 0)
+    return found;
+  return recursiveFind(repoDir);
+}
+async function recursiveFind(dir) {
+  const results = [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = join2(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name === ".git")
+        continue;
+      results.push(...await recursiveFind(fullPath));
+    } else if (entry.name === "SKILL.md") {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+async function fileExists(path) {
+  try {
+    const s = await stat2(path);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+async function dirExists2(path) {
+  try {
+    const s = await stat2(path);
+    return s.isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+// src/parse-skill.ts
+import matter from "gray-matter";
+import { readFile } from "fs/promises";
+import { dirname } from "path";
+async function parseSkill(skillMdPath) {
+  const content = await readFile(skillMdPath, "utf-8");
+  const { data } = matter(content);
+  if (!data.name) {
+    throw new Error(`SKILL.md at ${skillMdPath} missing required field: name`);
+  }
+  if (!data.description) {
+    throw new Error(`SKILL.md at ${skillMdPath} missing required field: description`);
+  }
+  return {
+    name: data.name,
+    description: data.description,
+    dir: dirname(skillMdPath)
+  };
+}
+
+// src/install.ts
+import { symlink, mkdir as mkdir2 } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/metadata.ts
+import { readFile as readFile2, writeFile, mkdir } from "fs/promises";
+import { dirname as dirname2 } from "path";
+async function readMetadata(metaPath) {
+  try {
+    const content = await readFile2(metaPath, "utf-8");
+    return JSON.parse(content);
+  } catch {
+    return { skills: {} };
+  }
+}
+async function writeSkillEntry(metaPath, name, entry) {
+  const meta = await readMetadata(metaPath);
+  meta.skills[name] = entry;
+  await mkdir(dirname2(metaPath), { recursive: true });
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + `
+`);
+}
+async function removeSkillEntry(metaPath, name) {
+  const meta = await readMetadata(metaPath);
+  delete meta.skills[name];
+  await writeFile(metaPath, JSON.stringify(meta, null, 2) + `
+`);
+}
+
+// src/install.ts
+async function installSkill(options) {
+  const linkPath = join3(options.targetBase, options.name);
+  await mkdir2(options.targetBase, { recursive: true });
+  await symlink(options.sourceDir, linkPath);
+  await writeSkillEntry(options.metaPath, options.name, {
+    source: options.source,
+    ref: options.ref,
+    skillDir: options.sourceDir,
+    installedAt: new Date().toISOString()
+  });
+}
+
+// src/commands/add.ts
+async function addSkill(options) {
+  const skillPaths = await discoverSkillPaths(options.repoDir);
+  if (skillPaths.length === 0) {
+    throw new Error(`No skills found in ${options.repoDir}`);
+  }
+  const skills = [];
+  for (const path of skillPaths) {
+    try {
+      skills.push(await parseSkill(path));
+    } catch {}
+  }
+  const match = skills.find((s) => s.name.toLowerCase() === options.skillName.toLowerCase());
+  if (!match) {
+    const available = skills.map((s) => s.name).join(", ");
+    throw new Error(`Skill "${options.skillName}" not found. Available: ${available}`);
+  }
+  await installSkill({
+    name: match.name,
+    sourceDir: match.dir,
+    targetBase: options.targetBase,
+    metaPath: options.metaPath,
+    source: options.source,
+    ref: options.ref
+  });
+  return {
+    name: match.name,
+    description: match.description,
+    installedTo: options.targetBase
+  };
+}
+
+// src/commands/list.ts
+async function listSkills(options) {
+  const result = { project: [], global: [] };
+  if (!options.globalOnly) {
+    const projectMeta = await readMetadata(options.projectMetaPath);
+    result.project = Object.entries(projectMeta.skills).map(([name, entry]) => ({
+      name,
+      source: entry.source,
+      ref: entry.ref,
+      installedAt: entry.installedAt
+    }));
+  }
+  const globalMeta = await readMetadata(options.globalMetaPath);
+  result.global = Object.entries(globalMeta.skills).map(([name, entry]) => ({
+    name,
+    source: entry.source,
+    ref: entry.ref,
+    installedAt: entry.installedAt
+  }));
+  return result;
+}
+
+// src/commands/remove.ts
+import { rm } from "fs/promises";
+import { join as join4 } from "path";
+async function removeSkill(options) {
+  const meta = await readMetadata(options.metaPath);
+  if (!meta.skills[options.name]) {
+    throw new Error(`Skill "${options.name}" is not installed`);
+  }
+  const linkPath = join4(options.targetBase, options.name);
+  await rm(linkPath, { force: true });
+  await removeSkillEntry(options.metaPath, options.name);
+}
+
+// src/paths.ts
+import { join as join5 } from "path";
+import { homedir } from "os";
+function getProjectPaths(cwd) {
+  return {
+    targetBase: join5(cwd, ".agents", "skills"),
+    metaPath: join5(cwd, ".skills-pm.json")
+  };
+}
+function getGlobalPaths() {
+  return {
+    targetBase: join5(homedir(), ".cursor", "skills"),
+    metaPath: join5(homedir(), ".cache", "skills-pm", "global.json")
+  };
+}
+function getCacheBase() {
+  return join5(homedir(), ".cache", "skills-pm");
+}
+
+// src/cli.ts
+var HELP_TEXT = `skills-pm - Cursor Skills Package Manager
+
+Usage:
+  skills-pm add <repo> -s <skill-name> [--ref <branch|SHA>] [-g]
+  skills-pm list [-g]
+  skills-pm remove <skill-name> [-g]
+
+Options:
+  -s, --skill <name>   Skill name to install (required for add)
+  --ref <ref>          Git branch, tag, or commit SHA (default: HEAD)
+  -g, --global         Install/list/remove globally (~/.cursor/skills/)
+  -h, --help           Show this help message`;
+var { values, positionals } = parseArgs({
+  args: process.argv.slice(2),
+  options: {
+    skill: { type: "string", short: "s" },
+    ref: { type: "string" },
+    global: { type: "boolean", short: "g", default: false },
+    help: { type: "boolean", short: "h", default: false }
+  },
+  allowPositionals: true,
+  strict: true
+});
+var command = positionals[0];
+if (!command || values.help) {
+  console.log(HELP_TEXT);
+  process.exit(0);
+}
+function formatSkillLine(s) {
+  const refSuffix = s.ref !== "HEAD" ? ` @ ${s.ref}` : "";
+  return `  ${s.name} (${s.source}${refSuffix})`;
+}
+async function handleAdd() {
+  const repoArg = positionals[1];
+  if (!repoArg) {
+    console.error("Error: repository is required. Usage: skills-pm add <owner/repo> -s <skill-name>");
+    process.exit(1);
+  }
+  const skillName = values.skill;
+  if (!skillName) {
+    console.error("Error: --skill (-s) is required. Usage: skills-pm add <owner/repo> -s <skill-name>");
+    process.exit(1);
+  }
+  const source = parseSource(repoArg);
+  const sourceStr = `${source.owner}/${source.repo}`;
+  const ref = values.ref;
+  const refLabel = ref ? ` (ref: ${ref})` : "";
+  console.log(`Cloning ${sourceStr}${refLabel}...`);
+  const repoDir = await cloneRepo(source, {
+    cacheBase: getCacheBase(),
+    ref
+  });
+  const paths = values.global ? getGlobalPaths() : getProjectPaths(process.cwd());
+  const result = await addSkill({
+    repoDir,
+    skillName,
+    targetBase: paths.targetBase,
+    metaPath: paths.metaPath,
+    source: sourceStr,
+    ref: ref ?? "HEAD"
+  });
+  console.log(`Installed "${result.name}" to ${result.installedTo}`);
+}
+async function handleList() {
+  const result = await listSkills({
+    projectMetaPath: getProjectPaths(process.cwd()).metaPath,
+    globalMetaPath: getGlobalPaths().metaPath,
+    globalOnly: values.global
+  });
+  if (result.project.length === 0 && result.global.length === 0) {
+    console.log("No skills installed.");
+    return;
+  }
+  if (result.project.length > 0) {
+    console.log("Project skills:");
+    result.project.forEach((s) => console.log(formatSkillLine(s)));
+  }
+  if (result.global.length > 0) {
+    console.log("Global skills:");
+    result.global.forEach((s) => console.log(formatSkillLine(s)));
+  }
+}
+async function handleRemove() {
+  const skillName = positionals[1];
+  if (!skillName) {
+    console.error("Error: skill name is required. Usage: skills-pm remove <skill-name>");
+    process.exit(1);
+  }
+  const paths = values.global ? getGlobalPaths() : getProjectPaths(process.cwd());
+  await removeSkill({
+    name: skillName,
+    targetBase: paths.targetBase,
+    metaPath: paths.metaPath
+  });
+  console.log(`Removed "${skillName}"`);
+}
+var commands = {
+  add: handleAdd,
+  list: handleList,
+  ls: handleList,
+  remove: handleRemove,
+  rm: handleRemove
+};
+var handler = commands[command];
+if (!handler) {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}
+handler().catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@rohilaharsh/skills-pm",
+  "version": "0.1.1",
+  "description": "A package manager for Cursor agent skills. Install skills from public or private GitHub repositories.",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "skills-pm": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun build src/cli.ts --outdir dist --target node --packages external",
+    "test": "bun test",
+    "prepublishOnly": "bun test && bun run build",
+    "start": "bun run src/cli.ts",
+    "release": "bash scripts/publish.sh"
+  },
+  "keywords": [
+    "cursor",
+    "skills",
+    "agent",
+    "ai",
+    "cli",
+    "package-manager"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/skills-pm"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3"
+  }
+}