openskill-ai 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agent Skills Community
+
+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,230 @@
+# agent-skills
+
+> Install AI agent skills from any Git repository
+
+A powerful CLI tool to install and manage AI coding agent skills from GitHub, GitLab, or any Git repository. Supports 15+ popular AI agents with auto-detection and interactive prompts.
+
+## Features
+
+✨ **Remote Repository Support** - Install skills from any Git repository  
+🤖 **15+ AI Agents** - Antigravity, Cursor, Claude Code, OpenCode, GitHub Copilot, and more  
+💬 **Interactive CLI** - Beautiful prompts with multi-select workflows  
+🔍 **Auto-Detection** - Automatically finds installed agents on your system  
+🌐 **Global/Project Installs** - Choose your installation scope  
+🔒 **Security** - Path sanitization and traversal protection  
+
+## Quick Start
+
+```bash
+# Install skills from a repository
+npx agent-skills vercel-labs/agent-skills
+
+# List available skills first
+npx agent-skills vercel-labs/agent-skills --list
+
+# Install specific skill to Antigravity
+npx agent-skills vercel-labs/agent-skills \
+  --skill frontend-design \
+  --agent antigravity
+```
+
+## Installation
+
+### As a CLI Tool (Recommended)
+
+Use with `npx` without installing:
+```bash
+npx agent-skills <source>
+```
+
+Or install globally:
+```bash
+npm install -g agent-skills
+agent-skills <source>
+```
+
+### As a Library
+
+```bash
+npm install agent-skills
+```
+
+```javascript
+import { installSkillForAgent, discoverSkills } from 'agent-skills';
+```
+
+## Usage
+
+### Source Formats
+
+The CLI accepts multiple source formats:
+
+```bash
+# GitHub shorthand
+agent-skills vercel-labs/agent-skills
+
+# GitHub URL
+agent-skills https://github.com/owner/repo
+
+# GitHub tree path (specific directory)
+agent-skills https://github.com/owner/repo/tree/main/skills/frontend
+
+# GitLab
+agent-skills https://gitlab.com/owner/repo
+
+# Direct Git URL
+agent-skills git@github.com:owner/repo.git
+```
+
+### CLI Options
+
+| Option | Description |
+|--------|-------------|
+| `-g, --global` | Install globally (user-level) instead of project-level |
+| `-a, --agent <agents...>` | Target specific agents |
+| `-s, --skill <skills...>` | Select specific skills to install |
+| `-l, --list` | List available skills without installing |
+| `-y, --yes` | Skip all confirmation prompts |
+| `-h, --help` | Show help |
+
+### Examples
+
+**Interactive Installation** (recommended for first-time users):
+```bash
+agent-skills vercel-labs/agent-skills
+```
+
+**List Skills Before Installing:**
+```bash
+agent-skills vercel-labs/agent-skills --list
+```
+
+**Install Specific Skill:**
+```bash
+agent-skills vercel-labs/agent-skills --skill frontend-design
+```
+
+**Install to Multiple Agents:**
+```bash
+agent-skills vercel-labs/agent-skills \
+  --skill frontend-design \
+  --agent antigravity \
+  --agent cursor \
+  --agent claude-code
+```
+
+**Global Installation (Non-Interactive):**
+```bash
+agent-skills vercel-labs/agent-skills \
+  --skill frontend-design \
+  --global \
+  --yes
+```
+
+**List All Supported Agents:**
+```bash
+agent-skills list-agents
+```
+
+## Supported AI Agents
+
+The tool supports 15 AI coding agents with auto-detection:
+
+- **Antigravity** - `.agent/skills` (project) or `~/.gemini/antigravity/skills` (global)
+- **Cursor** - `.cursor/skills` or `~/.cursor/skills`
+- **Claude Code** - `.claude/skills` or `~/.claude/skills`
+- **OpenCode** - `.opencode/skill` or `~/.config/opencode/skill`
+- **GitHub Copilot** - `.github/skills` or `~/.copilot/skills`
+- **Codex** - `.codex/skills` or `~/.codex/skills`
+- **Windsurf** - `.windsurf/skills` or `~/.codeium/windsurf/skills`
+- **Roo Code** - `.roo/skills` or `~/.roo/skills`
+- **Goose** - `.goose/skills` or `~/.config/goose/skills`
+- **Gemini CLI** - `.gemini/skills` or `~/.gemini/skills`
+- **Amp** - `.agents/skills` or `~/.config/agents/skills`
+- **Kilo Code** - `.kilocode/skills` or `~/.kilocode/skills`
+- **Clawdbot** - `skills/` or `~/.clawdbot/skills`
+- **Droid** - `.factory/skills` or `~/.factory/skills`
+
+## Creating Skills
+
+Skills are defined using `SKILL.md` files with YAML frontmatter:
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it
+---
+
+# My Skill
+
+Instructions for the AI agent to follow when this skill is activated.
+
+## When to Use
+
+Describe scenarios where this skill should be applied.
+
+## Guidelines
+
+1. First guideline
+2. Second guideline
+```
+
+### Skill Discovery
+
+The CLI searches for skills in these locations:
+- Root directory (if it contains `SKILL.md`)
+- `skills/`, `skills/.curated/`, `skills/.experimental/`
+- `.agent/skills/`, `.claude/skills/`, `.cursor/skills/`
+- All other agent-specific directories
+- Recursive search as fallback (max depth 5)
+
+## Security
+
+The tool implements several security measures:
+
+- **Path Sanitization** - Removes dangerous characters from skill names
+- **Traversal Protection** - Validates all paths to prevent directory traversal
+- **Safe Cloning** - Uses temporary directories for Git operations
+- **File Exclusions** - Skips `README.md`, `metadata.json`, and files starting with `_`
+
+## Programmatic API
+
+```javascript
+import { 
+  installSkillForAgent,
+  discoverSkills,
+  detectInstalledAgents,
+  parseSource,
+  cloneRepo
+} from 'agent-skills';
+
+// Clone and discover skills
+const parsed = parseSource('vercel-labs/agent-skills');
+const tempDir = await cloneRepo(parsed.url);
+const skills = await discoverSkills(tempDir);
+
+// Detect installed agents
+const agents = await detectInstalledAgents();
+
+// Install skill
+await installSkillForAgent(skills[0], 'antigravity', { global: false });
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Git installed on your system
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © Agent Skills Community
+
+## Links
+
+- [GitHub Repository](https://github.com/yourusername/agent-skills)
+- [Report Issues](https://github.com/yourusername/agent-skills/issues)
+- [npm Package](https://www.npmjs.com/package/agent-skills)

package/dist/chunk-63EFN7CX.js

@@ -0,0 +1,450 @@
+// src/utils/git.ts
+import simpleGit from "simple-git";
+import { join, normalize, resolve, sep } from "path";
+import { mkdtemp, rm } from "fs/promises";
+import { tmpdir } from "os";
+function parseSource(input) {
+  const githubTreeMatch = input.match(
+    /github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)\/(.+)/
+  );
+  if (githubTreeMatch) {
+    const [, owner, repo, , subpath] = githubTreeMatch;
+    return {
+      type: "github",
+      url: `https://github.com/${owner}/${repo}.git`,
+      subpath
+    };
+  }
+  const githubRepoMatch = input.match(/github\.com\/([^/]+)\/([^/]+)/);
+  if (githubRepoMatch) {
+    const [, owner, repo] = githubRepoMatch;
+    const cleanRepo = repo.replace(/\.git$/, "");
+    return {
+      type: "github",
+      url: `https://github.com/${owner}/${cleanRepo}.git`
+    };
+  }
+  const gitlabTreeMatch = input.match(
+    /gitlab\.com\/([^/]+)\/([^/]+)\/-\/tree\/([^/]+)\/(.+)/
+  );
+  if (gitlabTreeMatch) {
+    const [, owner, repo, , subpath] = gitlabTreeMatch;
+    return {
+      type: "gitlab",
+      url: `https://gitlab.com/${owner}/${repo}.git`,
+      subpath
+    };
+  }
+  const gitlabRepoMatch = input.match(/gitlab\.com\/([^/]+)\/([^/]+)/);
+  if (gitlabRepoMatch) {
+    const [, owner, repo] = gitlabRepoMatch;
+    const cleanRepo = repo.replace(/\.git$/, "");
+    return {
+      type: "gitlab",
+      url: `https://gitlab.com/${owner}/${cleanRepo}.git`
+    };
+  }
+  const shorthandMatch = input.match(/^([^/]+)\/([^/]+)(?:\/(.+))?$/);
+  if (shorthandMatch && !input.includes(":")) {
+    const [, owner, repo, subpath] = shorthandMatch;
+    return {
+      type: "github",
+      url: `https://github.com/${owner}/${repo}.git`,
+      subpath
+    };
+  }
+  return {
+    type: "git",
+    url: input
+  };
+}
+async function cloneRepo(url) {
+  const tempDir = await mkdtemp(join(tmpdir(), "agent-skills-"));
+  const git = simpleGit();
+  await git.clone(url, tempDir, ["--depth", "1"]);
+  return tempDir;
+}
+async function cleanupTempDir(dir) {
+  const normalizedDir = normalize(resolve(dir));
+  const normalizedTmpDir = normalize(resolve(tmpdir()));
+  if (!normalizedDir.startsWith(normalizedTmpDir + sep) && normalizedDir !== normalizedTmpDir) {
+    throw new Error("Attempted to clean up directory outside of temp directory");
+  }
+  await rm(dir, { recursive: true, force: true });
+}
+
+// src/utils/skills.ts
+import { readdir, readFile, stat } from "fs/promises";
+import { join as join2, basename, dirname } from "path";
+import matter from "gray-matter";
+var SKIP_DIRS = ["node_modules", ".git", "dist", "build", "__pycache__"];
+async function hasSkillMd(dir) {
+  try {
+    const skillPath = join2(dir, "SKILL.md");
+    const stats = await stat(skillPath);
+    return stats.isFile();
+  } catch {
+    return false;
+  }
+}
+async function parseSkillMd(skillMdPath) {
+  try {
+    const content = await readFile(skillMdPath, "utf-8");
+    const { data } = matter(content);
+    if (!data.name || !data.description) {
+      return null;
+    }
+    return {
+      name: data.name,
+      description: data.description,
+      path: dirname(skillMdPath),
+      metadata: data.metadata
+    };
+  } catch {
+    return null;
+  }
+}
+async function findSkillDirs(dir, depth = 0, maxDepth = 5) {
+  const skillDirs = [];
+  if (depth > maxDepth) return skillDirs;
+  try {
+    if (await hasSkillMd(dir)) {
+      skillDirs.push(dir);
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && !SKIP_DIRS.includes(entry.name)) {
+        const subDirs = await findSkillDirs(join2(dir, entry.name), depth + 1, maxDepth);
+        skillDirs.push(...subDirs);
+      }
+    }
+  } catch {
+  }
+  return skillDirs;
+}
+async function discoverSkills(basePath, subpath) {
+  const skills = [];
+  const seenNames = /* @__PURE__ */ new Set();
+  const searchPath = subpath ? join2(basePath, subpath) : basePath;
+  if (await hasSkillMd(searchPath)) {
+    const skill = await parseSkillMd(join2(searchPath, "SKILL.md"));
+    if (skill) {
+      skills.push(skill);
+      return skills;
+    }
+  }
+  const prioritySearchDirs = [
+    searchPath,
+    join2(searchPath, "skills"),
+    join2(searchPath, "skills/.curated"),
+    join2(searchPath, "skills/.experimental"),
+    join2(searchPath, "skills/.system"),
+    join2(searchPath, ".codex/skills"),
+    join2(searchPath, ".claude/skills"),
+    join2(searchPath, ".opencode/skill"),
+    join2(searchPath, ".cursor/skills"),
+    join2(searchPath, ".agents/skills"),
+    join2(searchPath, ".kilocode/skills"),
+    join2(searchPath, ".roo/skills"),
+    join2(searchPath, ".goose/skills"),
+    join2(searchPath, ".agent/skills"),
+    join2(searchPath, ".github/skills")
+  ];
+  for (const dir of prioritySearchDirs) {
+    try {
+      const entries = await readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory()) {
+          const skillDir = join2(dir, entry.name);
+          if (await hasSkillMd(skillDir)) {
+            const skill = await parseSkillMd(join2(skillDir, "SKILL.md"));
+            if (skill && !seenNames.has(skill.name)) {
+              skills.push(skill);
+              seenNames.add(skill.name);
+            }
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  if (skills.length === 0) {
+    const allSkillDirs = await findSkillDirs(searchPath);
+    for (const skillDir of allSkillDirs) {
+      const skill = await parseSkillMd(join2(skillDir, "SKILL.md"));
+      if (skill && !seenNames.has(skill.name)) {
+        skills.push(skill);
+        seenNames.add(skill.name);
+      }
+    }
+  }
+  return skills;
+}
+function getSkillDisplayName(skill) {
+  return skill.name || basename(skill.path);
+}
+
+// src/utils/agents.ts
+import { homedir } from "os";
+import { join as join3 } from "path";
+import { existsSync } from "fs";
+var home = homedir();
+var agents = {
+  opencode: {
+    name: "opencode",
+    displayName: "OpenCode",
+    skillsDir: ".opencode/skill",
+    globalSkillsDir: join3(home, ".config/opencode/skill"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".config/opencode")) || existsSync(join3(home, ".claude/skills"));
+    }
+  },
+  "claude-code": {
+    name: "claude-code",
+    displayName: "Claude Code",
+    skillsDir: ".claude/skills",
+    globalSkillsDir: join3(home, ".claude/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".claude"));
+    }
+  },
+  codex: {
+    name: "codex",
+    displayName: "Codex",
+    skillsDir: ".codex/skills",
+    globalSkillsDir: join3(home, ".codex/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".codex"));
+    }
+  },
+  cursor: {
+    name: "cursor",
+    displayName: "Cursor",
+    skillsDir: ".cursor/skills",
+    globalSkillsDir: join3(home, ".cursor/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".cursor"));
+    }
+  },
+  amp: {
+    name: "amp",
+    displayName: "Amp",
+    skillsDir: ".agents/skills",
+    globalSkillsDir: join3(home, ".config/agents/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".config/amp"));
+    }
+  },
+  kilo: {
+    name: "kilo",
+    displayName: "Kilo Code",
+    skillsDir: ".kilocode/skills",
+    globalSkillsDir: join3(home, ".kilocode/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".kilocode"));
+    }
+  },
+  roo: {
+    name: "roo",
+    displayName: "Roo Code",
+    skillsDir: ".roo/skills",
+    globalSkillsDir: join3(home, ".roo/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".roo"));
+    }
+  },
+  goose: {
+    name: "goose",
+    displayName: "Goose",
+    skillsDir: ".goose/skills",
+    globalSkillsDir: join3(home, ".config/goose/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".config/goose"));
+    }
+  },
+  "gemini-cli": {
+    name: "gemini-cli",
+    displayName: "Gemini CLI",
+    skillsDir: ".gemini/skills",
+    globalSkillsDir: join3(home, ".gemini/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".gemini"));
+    }
+  },
+  antigravity: {
+    name: "antigravity",
+    displayName: "Antigravity",
+    skillsDir: ".agent/skills",
+    globalSkillsDir: join3(home, ".gemini/antigravity/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(process.cwd(), ".agent")) || existsSync(join3(home, ".gemini/antigravity"));
+    }
+  },
+  "github-copilot": {
+    name: "github-copilot",
+    displayName: "GitHub Copilot",
+    skillsDir: ".github/skills",
+    globalSkillsDir: join3(home, ".copilot/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(process.cwd(), ".github")) || existsSync(join3(home, ".copilot"));
+    }
+  },
+  clawdbot: {
+    name: "clawdbot",
+    displayName: "Clawdbot",
+    skillsDir: "skills",
+    globalSkillsDir: join3(home, ".clawdbot/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".clawdbot"));
+    }
+  },
+  droid: {
+    name: "droid",
+    displayName: "Droid",
+    skillsDir: ".factory/skills",
+    globalSkillsDir: join3(home, ".factory/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".factory/skills"));
+    }
+  },
+  gemini: {
+    name: "gemini",
+    displayName: "Gemini CLI",
+    skillsDir: ".gemini/skills",
+    globalSkillsDir: join3(home, ".gemini/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".gemini"));
+    }
+  },
+  windsurf: {
+    name: "windsurf",
+    displayName: "Windsurf",
+    skillsDir: ".windsurf/skills",
+    globalSkillsDir: join3(home, ".codeium/windsurf/skills"),
+    detectInstalled: async () => {
+      return existsSync(join3(home, ".codeium/windsurf"));
+    }
+  }
+};
+async function detectInstalledAgents() {
+  const installed = [];
+  for (const [type, config] of Object.entries(agents)) {
+    if (await config.detectInstalled()) {
+      installed.push(type);
+    }
+  }
+  return installed;
+}
+function getAgentConfig(type) {
+  return agents[type];
+}
+
+// src/utils/installer.ts
+import { mkdir, cp, access, readdir as readdir2 } from "fs/promises";
+import { join as join4, basename as basename2, normalize as normalize2, resolve as resolve2, sep as sep2 } from "path";
+function sanitizeName(name) {
+  let sanitized = name.replace(/[\/\\:\0]/g, "");
+  sanitized = sanitized.replace(/^[.\s]+|[.\s]+$/g, "");
+  sanitized = sanitized.replace(/^\.+/, "");
+  if (!sanitized || sanitized.length === 0) {
+    sanitized = "unnamed-skill";
+  }
+  if (sanitized.length > 255) {
+    sanitized = sanitized.substring(0, 255);
+  }
+  return sanitized;
+}
+function isPathSafe(basePath, targetPath) {
+  const normalizedBase = normalize2(resolve2(basePath));
+  const normalizedTarget = normalize2(resolve2(targetPath));
+  return normalizedTarget.startsWith(normalizedBase + sep2) || normalizedTarget === normalizedBase;
+}
+async function installSkillForAgent(skill, agentType, options = {}) {
+  const agent = agents[agentType];
+  const rawSkillName = skill.name || basename2(skill.path);
+  const skillName = sanitizeName(rawSkillName);
+  const targetBase = options.global ? agent.globalSkillsDir : join4(options.cwd || process.cwd(), agent.skillsDir);
+  const targetDir = join4(targetBase, skillName);
+  if (!isPathSafe(targetBase, targetDir)) {
+    return {
+      success: false,
+      path: targetDir,
+      error: "Invalid skill name: potential path traversal detected"
+    };
+  }
+  try {
+    await mkdir(targetDir, { recursive: true });
+    await copyDirectory(skill.path, targetDir);
+    return { success: true, path: targetDir };
+  } catch (error) {
+    return {
+      success: false,
+      path: targetDir,
+      error: error instanceof Error ? error.message : "Unknown error"
+    };
+  }
+}
+var EXCLUDE_FILES = /* @__PURE__ */ new Set([
+  "README.md",
+  "metadata.json"
+]);
+var isExcluded = (name) => {
+  if (EXCLUDE_FILES.has(name)) return true;
+  if (name.startsWith("_")) return true;
+  return false;
+};
+async function copyDirectory(src, dest) {
+  await mkdir(dest, { recursive: true });
+  const entries = await readdir2(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (isExcluded(entry.name)) {
+      continue;
+    }
+    const srcPath = join4(src, entry.name);
+    const destPath = join4(dest, entry.name);
+    if (entry.isDirectory()) {
+      await copyDirectory(srcPath, destPath);
+    } else {
+      await cp(srcPath, destPath);
+    }
+  }
+}
+async function isSkillInstalled(skillName, agentType, options = {}) {
+  const agent = agents[agentType];
+  const sanitized = sanitizeName(skillName);
+  const targetBase = options.global ? agent.globalSkillsDir : join4(options.cwd || process.cwd(), agent.skillsDir);
+  const skillDir = join4(targetBase, sanitized);
+  if (!isPathSafe(targetBase, skillDir)) {
+    return false;
+  }
+  try {
+    await access(skillDir);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function getInstallPath(skillName, agentType, options = {}) {
+  const agent = agents[agentType];
+  const sanitized = sanitizeName(skillName);
+  const targetBase = options.global ? agent.globalSkillsDir : join4(options.cwd || process.cwd(), agent.skillsDir);
+  const installPath = join4(targetBase, sanitized);
+  if (!isPathSafe(targetBase, installPath)) {
+    throw new Error("Invalid skill name: potential path traversal detected");
+  }
+  return installPath;
+}
+
+export {
+  parseSource,
+  cloneRepo,
+  cleanupTempDir,
+  discoverSkills,
+  getSkillDisplayName,
+  agents,
+  detectInstalledAgents,
+  getAgentConfig,
+  installSkillForAgent,
+  isSkillInstalled,
+  getInstallPath
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node