skills 1.4.3 → 1.4.5

package/README.md

@@ -3,7 +3,7 @@
 The CLI for the open agent skills ecosystem.
 
 <!-- agent-list:start -->
-Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [37 more](#available-agents).
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [38 more](#available-agents).
 <!-- agent-list:end -->
 
 ## Install a Skill
@@ -214,7 +214,7 @@ Skills can be installed to any of these agents:
 | Augment | `augment` | `.augment/skills/` | `~/.augment/skills/` |
 | Claude Code | `claude-code` | `.claude/skills/` | `~/.claude/skills/` |
 | OpenClaw | `openclaw` | `skills/` | `~/.openclaw/skills/` |
-| Cline | `cline` | `.agents/skills/` | `~/.agents/skills/` |
+| Cline, Warp | `cline`, `warp` | `.agents/skills/` | `~/.agents/skills/` |
 | CodeBuddy | `codebuddy` | `.codebuddy/skills/` | `~/.codebuddy/skills/` |
 | Codex | `codex` | `.agents/skills/` | `~/.codex/skills/` |
 | Command Code | `command-code` | `.commandcode/skills/` | `~/.commandcode/skills/` |

package/dist/cli.mjs

@@ -21,6 +21,13 @@ import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, realpat
 var import_picocolors = /* @__PURE__ */ __toESM(require_picocolors(), 1);
 function getOwnerRepo(parsed) {
 	if (parsed.type === "local") return null;
+	const sshMatch = parsed.url.match(/^git@[^:]+:(.+)$/);
+	if (sshMatch) {
+		let path = sshMatch[1];
+		path = path.replace(/\.git$/, "");
+		if (path.includes("/")) return path;
+		return null;
+	}
 	if (!parsed.url.startsWith("http://") && !parsed.url.startsWith("https://")) return null;
 	try {
 		let path = new URL(parsed.url).pathname.slice(1);
@@ -46,6 +53,11 @@ async function isRepoPrivate(owner, repo) {
 		return null;
 	}
 }
+function sanitizeSubpath(subpath) {
+	const segments = subpath.replace(/\\/g, "/").split("/");
+	for (const segment of segments) if (segment === "..") throw new Error(`Unsafe subpath: "${subpath}" contains path traversal segments. Subpaths must not contain ".." components.`);
+	return subpath;
+}
 function isLocalPath(input) {
 	return isAbsolute(input) || input.startsWith("./") || input.startsWith("../") || input === "." || input === ".." || /^[a-zA-Z]:[/\\]/.test(input);
 }
@@ -53,6 +65,10 @@ const SOURCE_ALIASES = { "coinbase/agentWallet": "coinbase/agentic-wallet-skills
 function parseSource(input) {
 	const alias = SOURCE_ALIASES[input];
 	if (alias) input = alias;
+	const githubPrefixMatch = input.match(/^github:(.+)$/);
+	if (githubPrefixMatch) return parseSource(githubPrefixMatch[1]);
+	const gitlabPrefixMatch = input.match(/^gitlab:(.+)$/);
+	if (gitlabPrefixMatch) return parseSource(`https://gitlab.com/${gitlabPrefixMatch[1]}`);
 	if (isLocalPath(input)) {
 		const resolvedPath = resolve(input);
 		return {
@@ -68,7 +84,7 @@ function parseSource(input) {
 			type: "github",
 			url: `https://github.com/${owner}/${repo}.git`,
 			ref,
-			subpath
+			subpath: subpath ? sanitizeSubpath(subpath) : subpath
 		};
 	}
 	const githubTreeMatch = input.match(/github\.com\/([^/]+)\/([^/]+)\/tree\/([^/]+)$/);
@@ -95,7 +111,7 @@ function parseSource(input) {
 			type: "gitlab",
 			url: `${protocol}://${hostname}/${repoPath.replace(/\.git$/, "")}.git`,
 			ref,
-			subpath
+			subpath: subpath ? sanitizeSubpath(subpath) : subpath
 		};
 	}
 	const gitlabTreeMatch = input.match(/^(https?):\/\/([^/]+)\/(.+?)\/-\/tree\/([^/]+)$/);
@@ -130,7 +146,7 @@ function parseSource(input) {
 		return {
 			type: "github",
 			url: `https://github.com/${owner}/${repo}.git`,
-			subpath
+			subpath: subpath ? sanitizeSubpath(subpath) : subpath
 		};
 	}
 	if (isWellKnownUrl(input)) return {
@@ -486,9 +502,15 @@ async function findSkillDirs(dir, depth = 0, maxDepth = 5) {
 		return [];
 	}
 }
+function isSubpathSafe(basePath, subpath) {
+	const normalizedBase = normalize(resolve(basePath));
+	const normalizedTarget = normalize(resolve(join(basePath, subpath)));
+	return normalizedTarget.startsWith(normalizedBase + sep) || normalizedTarget === normalizedBase;
+}
 async function discoverSkills(basePath, subpath, options) {
 	const skills = [];
 	const seenNames = /* @__PURE__ */ new Set();
+	if (subpath && !isSubpathSafe(basePath, subpath)) throw new Error(`Invalid subpath: "${subpath}" resolves outside the repository directory. Subpath must not contain ".." segments that escape the base path.`);
 	const searchPath = subpath ? join(basePath, subpath) : basePath;
 	const pluginGroupings = await getPluginGroupings(searchPath);
 	const enhanceSkill = (skill) => {
@@ -902,6 +924,15 @@ const agents = {
 			return existsSync(join(home, ".trae-cn"));
 		}
 	},
+	warp: {
+		name: "warp",
+		displayName: "Warp",
+		skillsDir: ".agents/skills",
+		globalSkillsDir: join(home, ".agents/skills"),
+		detectInstalled: async () => {
+			return existsSync(join(home, ".warp"));
+		}
+	},
 	windsurf: {
 		name: "windsurf",
 		displayName: "Windsurf",
@@ -1114,10 +1145,14 @@ async function installSkillForAgent(skill, agentType, options = {}) {
 	}
 }
 const EXCLUDE_FILES = new Set(["metadata.json"]);
-const EXCLUDE_DIRS = new Set([".git"]);
+const EXCLUDE_DIRS = new Set([
+	".git",
+	"__pycache__",
+	"__pypackages__"
+]);
 const isExcluded = (name, isDirectory = false) => {
 	if (EXCLUDE_FILES.has(name)) return true;
-	if (name.startsWith("_")) return true;
+	if (name.startsWith(".")) return true;
 	if (isDirectory && EXCLUDE_DIRS.has(name)) return true;
 	return false;
 };
@@ -1128,10 +1163,15 @@ async function copyDirectory(src, dest) {
 		const srcPath = join(src, entry.name);
 		const destPath = join(dest, entry.name);
 		if (entry.isDirectory()) await copyDirectory(srcPath, destPath);
-		else await cp(srcPath, destPath, {
-			dereference: true,
-			recursive: true
-		});
+		else try {
+			await cp(srcPath, destPath, {
+				dereference: true,
+				recursive: true
+			});
+		} catch (err) {
+			if (err instanceof Error && "code" in err && err.code === "ENOENT" && entry.isSymbolicLink()) console.warn(`Skipping broken symlink: ${srcPath}`);
+			else throw err;
+		}
 	}));
 }
 async function isSkillInstalled(skillName, agentType, options = {}) {
@@ -1579,6 +1619,8 @@ const AGENTS_DIR$1 = ".agents";
 const LOCK_FILE$1 = ".skill-lock.json";
 const CURRENT_VERSION$1 = 3;
 function getSkillLockPath$1() {
+	const xdgStateHome = process.env.XDG_STATE_HOME;
+	if (xdgStateHome) return join(xdgStateHome, "skills", LOCK_FILE$1);
 	return join(homedir(), AGENTS_DIR$1, LOCK_FILE$1);
 }
 async function readSkillLock$1() {
@@ -1751,7 +1793,7 @@ function createEmptyLocalLock() {
 		skills: {}
 	};
 }
-var version$1 = "1.4.3";
+var version$1 = "1.4.5";
 const isCancelled$1 = (value) => typeof value === "symbol";
 async function isSourcePrivate(source) {
 	const ownerRepo = parseOwnerRepo(source);
@@ -2048,7 +2090,8 @@ async function handleWellKnownSkills(source, url, options, spinner) {
 		installGlobally = scope;
 	}
 	let installMode = options.copy ? "copy" : "symlink";
-	if (!options.copy && !options.yes) {
+	const uniqueDirs = new Set(targetAgents.map((a) => agents[a].skillsDir));
+	if (!options.copy && !options.yes && uniqueDirs.size > 1) {
 		const modeChoice = await ve({
 			message: "Installation method",
 			options: [{
@@ -2066,7 +2109,7 @@ async function handleWellKnownSkills(source, url, options, spinner) {
 			process.exit(0);
 		}
 		installMode = modeChoice;
-	}
+	} else if (uniqueDirs.size <= 1) installMode = "copy";
 	const cwd = process.cwd();
 	const summaryLines = [];
 	targetAgents.map((a) => agents[a].displayName);
@@ -2440,7 +2483,8 @@ async function runAdd(args, options = {}) {
 			installGlobally = scope;
 		}
 		let installMode = options.copy ? "copy" : "symlink";
-		if (!options.copy && !options.yes) {
+		const uniqueDirs = new Set(targetAgents.map((a) => agents[a].skillsDir));
+		if (!options.copy && !options.yes && uniqueDirs.size > 1) {
 			const modeChoice = await ve({
 				message: "Installation method",
 				options: [{
@@ -2459,7 +2503,7 @@ async function runAdd(args, options = {}) {
 				process.exit(0);
 			}
 			installMode = modeChoice;
-		}
+		} else if (uniqueDirs.size <= 1) installMode = "copy";
 		const cwd = process.cwd();
 		const summaryLines = [];
 		targetAgents.map((a) => agents[a].displayName);
@@ -2552,6 +2596,7 @@ async function runAdd(args, options = {}) {
 			skillFiles[skill.name] = relativePath;
 		}
 		const normalizedSource = getOwnerRepo(parsed);
+		const lockSource = parsed.url.startsWith("git@") ? parsed.url : normalizedSource;
 		if (normalizedSource) {
 			const ownerRepo = parseOwnerRepo(normalizedSource);
 			if (ownerRepo) {
@@ -2580,11 +2625,11 @@ async function runAdd(args, options = {}) {
 					let skillFolderHash = "";
 					const skillPathValue = skillFiles[skill.name];
 					if (parsed.type === "github" && skillPathValue) {
-						const hash = await fetchSkillFolderHash(normalizedSource, skillPathValue);
+						const hash = await fetchSkillFolderHash(normalizedSource, skillPathValue, getGitHubToken());
 						if (hash) skillFolderHash = hash;
 					}
 					await addSkillToLock(skill.name, {
-						source: normalizedSource,
+						source: lockSource || normalizedSource,
 						sourceType: parsed.type,
 						sourceUrl: parsed.url,
 						skillPath: skillPathValue,
@@ -2601,7 +2646,7 @@ async function runAdd(args, options = {}) {
 				if (successfulSkillNames.has(skillDisplayName)) try {
 					const computedHash = await computeSkillFolderHash(skill.path);
 					await addSkillToLocalLock(skill.name, {
-						source: normalizedSource || parsed.url,
+						source: lockSource || parsed.url,
 						sourceType: parsed.type,
 						computedHash
 					}, cwd);
@@ -2790,7 +2835,7 @@ async function searchSkillsAPI(query) {
 			slug: skill.id,
 			source: skill.source || "",
 			installs: skill.installs
-		}));
+		})).sort((a, b) => (b.installs || 0) - (a.installs || 0));
 	} catch {
 		return [];
 	}
@@ -3346,6 +3391,7 @@ function parseListOptions(args) {
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i];
 		if (arg === "-g" || arg === "--global") options.global = true;
+		else if (arg === "--json") options.json = true;
 		else if (arg === "-a" || arg === "--agent") {
 			options.agent = options.agent || [];
 			while (i + 1 < args.length && !args[i + 1].startsWith("-")) options.agent.push(args[++i]);
@@ -3371,10 +3417,24 @@ async function runList(args) {
 		global: scope,
 		agentFilter
 	});
+	if (options.json) {
+		const jsonOutput = installedSkills.map((skill) => ({
+			name: skill.name,
+			path: skill.canonicalPath,
+			scope: skill.scope,
+			agents: skill.agents.map((a) => agents[a].displayName)
+		}));
+		console.log(JSON.stringify(jsonOutput, null, 2));
+		return;
+	}
 	const lockedSkills = await getAllLockedSkills();
 	const cwd = process.cwd();
 	const scopeLabel = scope ? "Global" : "Project";
 	if (installedSkills.length === 0) {
+		if (options.json) {
+			console.log("[]");
+			return;
+		}
 		console.log(`${DIM$1}No ${scopeLabel.toLowerCase()} skills found.${RESET$1}`);
 		if (scope) console.log(`${DIM$1}Try listing project skills without -g${RESET$1}`);
 		else console.log(`${DIM$1}Try listing global skills with -g${RESET$1}`);
@@ -3713,6 +3773,7 @@ ${BOLD}Experimental Sync Options:${RESET}
 ${BOLD}List Options:${RESET}
   -g, --global           List global skills (default: project)
   -a, --agent <agents>   Filter by specific agents
+  --json                 Output as JSON (machine-readable, no ANSI codes)
 
 ${BOLD}Options:${RESET}
   --help, -h        Show this help message
@@ -3729,6 +3790,7 @@ ${BOLD}Examples:${RESET}
   ${DIM}$${RESET} skills list                          ${DIM}# list project skills${RESET}
   ${DIM}$${RESET} skills ls -g                         ${DIM}# list global skills${RESET}
   ${DIM}$${RESET} skills ls -a claude-code             ${DIM}# filter by agent${RESET}
+  ${DIM}$${RESET} skills ls --json                      ${DIM}# JSON output${RESET}
   ${DIM}$${RESET} skills find                          ${DIM}# interactive search${RESET}
   ${DIM}$${RESET} skills find typescript               ${DIM}# search by keyword${RESET}
   ${DIM}$${RESET} skills check
@@ -3822,6 +3884,8 @@ const AGENTS_DIR = ".agents";
 const LOCK_FILE = ".skill-lock.json";
 const CURRENT_LOCK_VERSION = 3;
 function getSkillLockPath() {
+	const xdgStateHome = process.env.XDG_STATE_HOME;
+	if (xdgStateHome) return join(xdgStateHome, "skills", LOCK_FILE);
 	return join(homedir(), AGENTS_DIR, LOCK_FILE);
 }
 function readSkillLock() {
@@ -3845,6 +3909,22 @@ function readSkillLock() {
 		};
 	}
 }
+function getSkipReason(entry) {
+	if (entry.sourceType === "local") return "Local path";
+	if (entry.sourceType === "git") return "Git URL (hash tracking not supported)";
+	if (!entry.skillFolderHash) return "No version hash available";
+	if (!entry.skillPath) return "No skill path recorded";
+	return "No version tracking";
+}
+function printSkippedSkills(skipped) {
+	if (skipped.length === 0) return;
+	console.log();
+	console.log(`${DIM}${skipped.length} skill(s) cannot be checked automatically:${RESET}`);
+	for (const skill of skipped) {
+		console.log(`  ${TEXT}•${RESET} ${skill.name} ${DIM}(${skill.reason})${RESET}`);
+		console.log(`    ${DIM}To update: ${TEXT}npx skills add ${skill.sourceUrl} -g -y${RESET}`);
+	}
+}
 async function runCheck(args = []) {
 	console.log(`${TEXT}Checking for skill updates...${RESET}`);
 	console.log();
@@ -3857,12 +3937,16 @@ async function runCheck(args = []) {
 	}
 	const token = getGitHubToken();
 	const skillsBySource = /* @__PURE__ */ new Map();
-	let skippedCount = 0;
+	const skipped = [];
 	for (const skillName of skillNames) {
 		const entry = lock.skills[skillName];
 		if (!entry) continue;
-		if (entry.sourceType !== "github" || !entry.skillFolderHash || !entry.skillPath) {
-			skippedCount++;
+		if (!entry.skillFolderHash || !entry.skillPath) {
+			skipped.push({
+				name: skillName,
+				reason: getSkipReason(entry),
+				sourceUrl: entry.sourceUrl
+			});
 			continue;
 		}
 		const existing = skillsBySource.get(entry.source) || [];
@@ -3872,9 +3956,10 @@ async function runCheck(args = []) {
 		});
 		skillsBySource.set(entry.source, existing);
 	}
-	const totalSkills = skillNames.length - skippedCount;
+	const totalSkills = skillNames.length - skipped.length;
 	if (totalSkills === 0) {
 		console.log(`${DIM}No GitHub skills to check.${RESET}`);
+		printSkippedSkills(skipped);
 		return;
 	}
 	console.log(`${DIM}Checking ${totalSkills} skill(s) for updates...${RESET}`);
@@ -3917,6 +4002,7 @@ async function runCheck(args = []) {
 		console.log();
 		console.log(`${DIM}Could not check ${errors.length} skill(s) (may need reinstall)${RESET}`);
 	}
+	printSkippedSkills(skipped);
 	track({
 		event: "check",
 		skillCount: String(totalSkills),
@@ -3936,12 +4022,18 @@ async function runUpdate() {
 	}
 	const token = getGitHubToken();
 	const updates = [];
-	let checkedCount = 0;
+	const skipped = [];
 	for (const skillName of skillNames) {
 		const entry = lock.skills[skillName];
 		if (!entry) continue;
-		if (entry.sourceType !== "github" || !entry.skillFolderHash || !entry.skillPath) continue;
-		checkedCount++;
+		if (!entry.skillFolderHash || !entry.skillPath) {
+			skipped.push({
+				name: skillName,
+				reason: getSkipReason(entry),
+				sourceUrl: entry.sourceUrl
+			});
+			continue;
+		}
 		try {
 			const latestHash = await fetchSkillFolderHash(entry.source, entry.skillPath, token);
 			if (latestHash && latestHash !== entry.skillFolderHash) updates.push({
@@ -3951,8 +4043,9 @@ async function runUpdate() {
 			});
 		} catch {}
 	}
-	if (checkedCount === 0) {
+	if (skillNames.length - skipped.length === 0) {
 		console.log(`${DIM}No skills to check.${RESET}`);
+		printSkippedSkills(skipped);
 		return;
 	}
 	if (updates.length === 0) {
@@ -3982,11 +4075,14 @@ async function runUpdate() {
 			installUrl,
 			"-g",
 			"-y"
-		], { stdio: [
-			"inherit",
-			"pipe",
-			"pipe"
-		] }).status === 0) {
+		], {
+			stdio: [
+				"inherit",
+				"pipe",
+				"pipe"
+			],
+			shell: process.platform === "win32"
+		}).status === 0) {
 			successCount++;
 			console.log(`  ${TEXT}✓${RESET} Updated ${update.name}`);
 		} else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "The open agent skills ecosystem",
   "type": "module",
   "bin": {
@@ -71,6 +71,7 @@
     "roo",
     "trae",
     "trae-cn",
+    "warp",
     "windsurf",
     "zencoder",
     "neovate",