skpm-cli 1.4.7 → 1.4.8

package/README.md

@@ -1,37 +1,60 @@
-# skills
+# skpm
 
-The CLI for the open agent skills ecosystem.
+The Skill Package Manager for AI agents. Fork of [vercel-labs/skills](https://github.com/vercel-labs/skills) with **dependency graph resolution**.
 
 <!-- agent-list:start -->
-Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [40 more](#available-agents).
+Supports **OpenCode**, **Claude Code**, **Codex**, **Cursor**, and [40 more](#supported-agents).
 <!-- agent-list:end -->
 
+## What's different from `skills`?
+
+- **`dependsOn`** — Skills declare dependencies in SKILL.md frontmatter. `skpm add` recursively installs the full tree.
+- **`postInstall`** — Skills can declare setup commands (CLI installs, config). Printed with y/n prompt before execution.
+- **`--trust-scripts`** — Auto-accept postInstall commands (for CI/CD).
+
+## Install
+
+```bash
+pnpm i -g skpm-cli    # global install (recommended)
+skpm add owner/repo@skill -g
+```
+
+Or use without installing:
+
+```bash
+npx skpm-cli add owner/repo@skill -g
+```
+
 ## Install a Skill
 
 ```bash
-npx skills add vercel-labs/agent-skills
+skpm add jonmumm/skills@swarm -g
+# → automatically installs grill-me, mutation-testing, tdd
 ```
 
 ### Source Formats
 
 ```bash
 # GitHub shorthand (owner/repo)
-npx skills add vercel-labs/agent-skills
+skpm add vercel-labs/agent-skills
+
+# Install a specific skill with auto-resolved dependencies
+skpm add jonmumm/skills@swarm
 
 # Full GitHub URL
-npx skills add https://github.com/vercel-labs/agent-skills
+skpm add https://github.com/vercel-labs/agent-skills
 
 # Direct path to a skill in a repo
-npx skills add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
+skpm add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design-guidelines
 
 # GitLab URL
-npx skills add https://gitlab.com/org/repo
+skpm add https://gitlab.com/org/repo
 
 # Any git URL
-npx skills add git@github.com:vercel-labs/agent-skills.git
+skpm add git@github.com:vercel-labs/agent-skills.git
 
 # Local path
-npx skills add ./my-local-skills
+skpm add ./my-local-skills
 ```
 
 ### Options
@@ -49,29 +72,26 @@ npx skills add ./my-local-skills
 ### Examples
 
 ```bash
+# Install a skill (dependencies auto-resolved)
+skpm add jonmumm/skills@swarm -g
+
 # List skills in a repository
-npx skills add vercel-labs/agent-skills --list
+skpm add vercel-labs/agent-skills --list
 
 # Install specific skills
-npx skills add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
-
-# Install a skill with spaces in the name (must be quoted)
-npx skills add owner/repo --skill "Convex Best Practices"
+skpm add vercel-labs/agent-skills --skill frontend-design --skill skill-creator
 
 # Install to specific agents
-npx skills add vercel-labs/agent-skills -a claude-code -a opencode
+skpm add vercel-labs/agent-skills -a claude-code -a opencode
 
 # Non-interactive installation (CI/CD friendly)
-npx skills add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
+skpm add vercel-labs/agent-skills --skill frontend-design -g -a claude-code -y
 
 # Install all skills from a repo to all agents
-npx skills add vercel-labs/agent-skills --all
-
-# Install all skills to specific agents
-npx skills add vercel-labs/agent-skills --skill '*' -a claude-code
+skpm add vercel-labs/agent-skills --all
 
-# Install specific skills to all agents
-npx skills add vercel-labs/agent-skills --agent '*' --skill frontend-design
+# Auto-accept postInstall commands (CI/CD)
+skpm add jonmumm/skills@swarm -g -y --trust-scripts
 ```
 
 ### Installation Scope
@@ -94,12 +114,12 @@ When installing interactively, you can choose:
 
 | Command                      | Description                                    |
 | ---------------------------- | ---------------------------------------------- |
-| `npx skills list`            | List installed skills (alias: `ls`)            |
-| `npx skills find [query]`    | Search for skills interactively or by keyword  |
-| `npx skills remove [skills]` | Remove installed skills from agents            |
-| `npx skills check`           | Check for available skill updates              |
-| `npx skills update`          | Update all installed skills to latest versions |
-| `npx skills init [name]`     | Create a new SKILL.md template                 |
+| `skpm list`            | List installed skills (alias: `ls`)            |
+| `skpm find [query]`    | Search for skills interactively or by keyword  |
+| `skpm remove [skills]` | Remove installed skills from agents            |
+| `skpm check`           | Check for available skill updates              |
+| `skpm update`          | Update all installed skills to latest versions |
+| `skpm init [name]`     | Create a new SKILL.md template                 |
 
 ### `skills list`
 
@@ -107,13 +127,13 @@ List all installed skills. Similar to `npm ls`.
 
 ```bash
 # List all installed skills (project and global)
-npx skills list
+skpm list
 
 # List only global skills
-npx skills ls -g
+skpm ls -g
 
 # Filter by specific agents
-npx skills ls -a claude-code -a cursor
+skpm ls -a claude-code -a cursor
 ```
 
 ### `skills find`
@@ -122,30 +142,30 @@ Search for skills interactively or by keyword.
 
 ```bash
 # Interactive search (fzf-style)
-npx skills find
+skpm find
 
 # Search by keyword
-npx skills find typescript
+skpm find typescript
 ```
 
 ### `skills check` / `skills update`
 
 ```bash
 # Check if any installed skills have updates
-npx skills check
+skpm check
 
 # Update all skills to latest versions
-npx skills update
+skpm update
 ```
 
 ### `skills init`
 
 ```bash
 # Create SKILL.md in current directory
-npx skills init
+skpm init
 
 # Create a new skill in a subdirectory
-npx skills init my-skill
+skpm init my-skill
 ```
 
 ### `skills remove`
@@ -154,31 +174,31 @@ Remove installed skills from agents.
 
 ```bash
 # Remove interactively (select from installed skills)
-npx skills remove
+skpm remove
 
 # Remove specific skill by name
-npx skills remove web-design-guidelines
+skpm remove web-design-guidelines
 
 # Remove multiple skills
-npx skills remove frontend-design web-design-guidelines
+skpm remove frontend-design web-design-guidelines
 
 # Remove from global scope
-npx skills remove --global web-design-guidelines
+skpm remove --global web-design-guidelines
 
 # Remove from specific agents only
-npx skills remove --agent claude-code cursor my-skill
+skpm remove --agent claude-code cursor my-skill
 
 # Remove all installed skills without confirmation
-npx skills remove --all
+skpm remove --all
 
 # Remove all skills from a specific agent
-npx skills remove --skill '*' -a cursor
+skpm remove --skill '*' -a cursor
 
 # Remove a specific skill from all agents
-npx skills remove my-skill --agent '*'
+skpm remove my-skill --agent '*'
 
 # Use 'rm' alias
-npx skills rm my-skill
+skpm rm my-skill
 ```
 
 | Option         | Description                                      |
@@ -200,7 +220,7 @@ Skills let agents perform specialized tasks like:
 - Creating PRs following your team's conventions
 - Integrating with external tools (Linear, Notion, etc.)
 
-Discover skills at **[skills.sh](https://skills.sh)**
+Discover skills at **[skpm.sh](https://skpm.sh)**
 
 ## Supported Agents
 
@@ -295,16 +315,19 @@ Describe the scenarios where this skill should be used.
 
 ### Optional Fields
 
-- `metadata.internal`: Set to `true` to hide the skill from normal discovery. Internal skills are only visible and
-  installable when `INSTALL_INTERNAL_SKILLS=1` is set. Useful for work-in-progress skills or skills meant only for
-  internal tooling.
+- `dependsOn`: Array of skill dependencies in `owner/repo@skill-name` format. Resolved recursively on install.
+- `postInstall`: Array of shell commands to run after installation. Printed with y/n prompt (or auto-accepted with `--trust-scripts`).
+- `metadata.internal`: Set to `true` to hide the skill from normal discovery.
 
 ```markdown
 ---
-name: my-internal-skill
-description: An internal skill not shown by default
-metadata:
-  internal: true
+name: my-skill
+description: My skill that depends on others
+dependsOn:
+  - jonmumm/skills@grill-me
+  - mattpocock/skills@tdd
+postInstall:
+  - "which linear || pnpm i -g @linear/cli"
 ---
 ```
 
@@ -410,7 +433,7 @@ Ensure you have write access to the target directory.
 
 ```bash
 # Install internal skills
-INSTALL_INTERNAL_SKILLS=1 npx skills add vercel-labs/agent-skills --list
+INSTALL_INTERNAL_SKILLS=1 skpm add vercel-labs/agent-skills --list
 ```
 
 ## Telemetry
@@ -422,7 +445,7 @@ Telemetry is automatically disabled in CI environments.
 ## Related Links
 
 - [Agent Skills Specification](https://agentskills.io)
-- [Skills Directory](https://skills.sh)
+- [Skills Directory](https://skpm.sh)
 - [Amp Skills Documentation](https://ampcode.com/manual#agent-skills)
 - [Antigravity Skills Documentation](https://antigravity.google/docs/skills)
 - [Factory AI / Droid Skills Documentation](https://docs.factory.ai/cli/configuration/skills)
@@ -449,6 +472,7 @@ Telemetry is automatically disabled in CI environments.
 - [Replit Skills Documentation](https://docs.replit.com/replitai/skills)
 - [Roo Code Skills Documentation](https://docs.roocode.com/features/skills)
 - [Trae Skills Documentation](https://docs.trae.ai/ide/skills)
+- [skpm CLI](https://github.com/skpm-sh/cli)
 - [Vercel Agent Skills Repository](https://github.com/vercel-labs/agent-skills)
 
 ## License

package/dist/cli.mjs

@@ -1900,7 +1900,7 @@ function createEmptyLocalLock() {
 		skills: {}
 	};
 }
-var version$1 = "1.4.7";
+var version$1 = "1.4.8";
 const isCancelled$1 = (value) => typeof value === "symbol";
 async function isSourcePrivate(source) {
 	const ownerRepo = parseOwnerRepo(source);
@@ -2824,37 +2824,86 @@ async function runAdd(args, options = {}) {
 			for (const r of failed) M.message(`  ${import_picocolors.default.red("✗")} ${r.skill} → ${r.agent}: ${import_picocolors.default.dim(r.error)}`);
 		}
 		const allPostInstallCommands = [];
+		const depFailures = [];
+		const sharedResolved = /* @__PURE__ */ new Set();
+		const depCloneCache = /* @__PURE__ */ new Map();
+		const depTempDirs = /* @__PURE__ */ new Set();
+		if (tempDir && normalizedSource) depCloneCache.set(parsed.url, tempDir);
 		for (const skill of selectedSkills) {
 			if (skill.postInstall.length > 0) allPostInstallCommands.push(...skill.postInstall);
 			if (skill.dependsOn.length > 0) {
 				M.info(import_picocolors.default.dim(`Resolving dependencies for ${skill.name}...`));
-				const depResult = await resolveDependencies(skill, async (source, skillName) => {
-					const depSource = skillName ? `${source}@${skillName}` : source;
+				const depResult = await resolveDependencies(skill, async (depSourceStr, skillName) => {
+					const depSource = skillName ? `${depSourceStr}@${skillName}` : depSourceStr;
 					M.step(import_picocolors.default.dim(`  Installing dependency: ${depSource}`));
-					const parsed = parseSource(source);
-					let depTempDir = null;
+					const depParsed = parseSource(depSourceStr);
+					let depDir;
 					try {
-						if (parsed.type === "local") depTempDir = parsed.localPath;
-						else depTempDir = await cloneRepo(parsed.url, parsed.ref);
-						const depSkills = await discoverSkills(depTempDir, parsed.subpath, { includeInternal: true });
+						if (depParsed.type === "local") depDir = depParsed.localPath;
+						else {
+							const cacheKey = depParsed.url;
+							if (depCloneCache.has(cacheKey)) depDir = depCloneCache.get(cacheKey);
+							else {
+								depDir = await cloneRepo(depParsed.url, depParsed.ref);
+								depCloneCache.set(cacheKey, depDir);
+								depTempDirs.add(depDir);
+							}
+						}
+						const depSkills = await discoverSkills(depDir, depParsed.subpath, { includeInternal: true });
 						const targetSkills = skillName ? depSkills.filter((s) => s.name.toLowerCase() === skillName.toLowerCase()) : depSkills;
 						if (targetSkills.length === 0) {
 							M.warn(import_picocolors.default.yellow(`  Dependency skill not found: ${depSource}`));
 							return [];
 						}
-						for (const depSkill of targetSkills) for (const agent of targetAgents) await installSkillForAgent(depSkill, agent, {
-							global: installGlobally,
-							mode: installMode
-						});
+						for (const depSkill of targetSkills) {
+							for (const agent of targetAgents) {
+								const depInstallResult = await installSkillForAgent(depSkill, agent, {
+									global: installGlobally,
+									mode: installMode
+								});
+								if (!depInstallResult.success) depFailures.push({
+									skill: depSkill.name,
+									agent: agents[agent].displayName,
+									error: depInstallResult.error
+								});
+							}
+							if (installGlobally) try {
+								const depNormalizedSource = getOwnerRepo(depParsed);
+								let depSkillPath;
+								if (depDir && depSkill.path.startsWith(depDir + sep)) depSkillPath = depSkill.path.slice(depDir.length + 1).split(sep).join("/") + "/SKILL.md";
+								else if (depDir && depSkill.path === depDir) depSkillPath = "SKILL.md";
+								let depFolderHash = "";
+								if (depParsed.type === "github" && depSkillPath && depNormalizedSource) {
+									const token = getGitHubToken();
+									const hash = await fetchSkillFolderHash(depNormalizedSource, depSkillPath, token);
+									if (hash) depFolderHash = hash;
+								}
+								const depLockSource = depParsed.url.startsWith("git@") ? depParsed.url : depNormalizedSource || depParsed.url;
+								await addSkillToLock(depSkill.name, {
+									source: depLockSource,
+									sourceType: depParsed.type,
+									sourceUrl: depParsed.url,
+									skillPath: depSkillPath,
+									skillFolderHash: depFolderHash,
+									pluginName: depSkill.pluginName
+								});
+							} catch {}
+						}
 						return targetSkills;
-					} finally {
-						if (depTempDir && parsed.type !== "local") await cleanupTempDir(depTempDir).catch(() => {});
+					} catch (err) {
+						throw err;
 					}
-				}, (warning) => M.warn(import_picocolors.default.yellow(warning)));
+				}, (warning) => M.warn(import_picocolors.default.yellow(warning)), sharedResolved);
 				allPostInstallCommands.push(...depResult.postInstallCommands);
 				if (depResult.errors.length > 0) for (const err of depResult.errors) M.warn(import_picocolors.default.yellow(`Dependency ${err.ref}: ${err.error}`));
 			}
 		}
+		for (const dir of depTempDirs) await cleanupTempDir(dir).catch(() => {});
+		if (depFailures.length > 0) {
+			console.log();
+			M.error(import_picocolors.default.red(`Failed to install ${depFailures.length} dependency(ies)`));
+			for (const f of depFailures) M.message(`  ${import_picocolors.default.red("✗")} ${f.skill} → ${f.agent}${f.error ? `: ${import_picocolors.default.dim(f.error)}` : ""}`);
+		}
 		if (allPostInstallCommands.length > 0) {
 			console.log();
 			M.info("Post-install commands required:");
@@ -2967,10 +3016,10 @@ function parseAddOptions(args) {
 		options
 	};
 }
-const RESET$2 = "\x1B[0m";
-const BOLD$2 = "\x1B[1m";
-const DIM$2 = "\x1B[38;5;102m";
-const TEXT$1 = "\x1B[38;5;145m";
+const RESET$4 = "\x1B[0m";
+const BOLD$4 = "\x1B[1m";
+const DIM$4 = "\x1B[38;5;102m";
+const TEXT$3 = "\x1B[38;5;145m";
 const CYAN$1 = "\x1B[36m";
 const SEARCH_API_BASE = process.env.SKPM_API_URL || "https://skpm.sh";
 function formatInstalls(count) {
@@ -3014,28 +3063,28 @@ async function runSearchPrompt(initialQuery = "") {
 		if (lastRenderedLines > 0) process.stdout.write(MOVE_UP(lastRenderedLines) + MOVE_TO_COL(1));
 		process.stdout.write(CLEAR_DOWN);
 		const lines = [];
-		const cursor = `${BOLD$2}_${RESET$2}`;
-		lines.push(`${TEXT$1}Search skills:${RESET$2} ${query}${cursor}`);
+		const cursor = `${BOLD$4}_${RESET$4}`;
+		lines.push(`${TEXT$3}Search skills:${RESET$4} ${query}${cursor}`);
 		lines.push("");
-		if (!query || query.length < 2) lines.push(`${DIM$2}Start typing to search (min 2 chars)${RESET$2}`);
-		else if (results.length === 0 && loading) lines.push(`${DIM$2}Searching...${RESET$2}`);
-		else if (results.length === 0) lines.push(`${DIM$2}No skills found${RESET$2}`);
+		if (!query || query.length < 2) lines.push(`${DIM$4}Start typing to search (min 2 chars)${RESET$4}`);
+		else if (results.length === 0 && loading) lines.push(`${DIM$4}Searching...${RESET$4}`);
+		else if (results.length === 0) lines.push(`${DIM$4}No skills found${RESET$4}`);
 		else {
 			const visible = results.slice(0, 8);
 			for (let i = 0; i < visible.length; i++) {
 				const skill = visible[i];
 				const isSelected = i === selectedIndex;
-				const arrow = isSelected ? `${BOLD$2}>${RESET$2}` : " ";
-				const name = isSelected ? `${BOLD$2}${skill.name}${RESET$2}` : `${TEXT$1}${skill.name}${RESET$2}`;
-				const source = skill.source ? ` ${DIM$2}${skill.source}${RESET$2}` : "";
+				const arrow = isSelected ? `${BOLD$4}>${RESET$4}` : " ";
+				const name = isSelected ? `${BOLD$4}${skill.name}${RESET$4}` : `${TEXT$3}${skill.name}${RESET$4}`;
+				const source = skill.source ? ` ${DIM$4}${skill.source}${RESET$4}` : "";
 				const installs = formatInstalls(skill.installs);
-				const installsBadge = installs ? ` ${CYAN$1}${installs}${RESET$2}` : "";
-				const loadingIndicator = loading && i === 0 ? ` ${DIM$2}...${RESET$2}` : "";
+				const installsBadge = installs ? ` ${CYAN$1}${installs}${RESET$4}` : "";
+				const loadingIndicator = loading && i === 0 ? ` ${DIM$4}...${RESET$4}` : "";
 				lines.push(`  ${arrow} ${name}${source}${installsBadge}${loadingIndicator}`);
 			}
 		}
 		lines.push("");
-		lines.push(`${DIM$2}up/down navigate | enter select | esc cancel${RESET$2}`);
+		lines.push(`${DIM$4}up/down navigate | enter select | esc cancel${RESET$4}`);
 		for (const line of lines) process.stdout.write(line + "\n");
 		lastRenderedLines = lines.length;
 	}
@@ -3131,9 +3180,9 @@ async function isRepoPublic(owner, repo) {
 async function runFind(args) {
 	const query = args.join(" ");
 	const isNonInteractive = !process.stdin.isTTY;
-	const agentTip = `${DIM$2}Tip: if running in a coding agent, follow these steps:${RESET$2}
-${DIM$2}  1) npx skpm-cli find [query]${RESET$2}
-${DIM$2}  2) npx skpm-cli add <owner/repo@skill>${RESET$2}`;
+	const agentTip = `${DIM$4}Tip: if running in a coding agent, follow these steps:${RESET$4}
+${DIM$4}  1) npx skpm-cli find [query]${RESET$4}
+${DIM$4}  2) npx skpm-cli add <owner/repo@skill>${RESET$4}`;
 	if (query) {
 		const results = await searchSkillsAPI(query);
 		track({
@@ -3142,16 +3191,16 @@ ${DIM$2}  2) npx skpm-cli add <owner/repo@skill>${RESET$2}`;
 			resultCount: String(results.length)
 		});
 		if (results.length === 0) {
-			console.log(`${DIM$2}No skills found for "${query}"${RESET$2}`);
+			console.log(`${DIM$4}No skills found for "${query}"${RESET$4}`);
 			return;
 		}
-		console.log(`${DIM$2}Install with${RESET$2} npx skpm-cli add <owner/repo@skill>`);
+		console.log(`${DIM$4}Install with${RESET$4} npx skpm-cli add <owner/repo@skill>`);
 		console.log();
 		for (const skill of results.slice(0, 6)) {
 			const pkg = skill.source || skill.slug;
 			const installs = formatInstalls(skill.installs);
-			console.log(`${TEXT$1}${pkg}@${skill.name}${RESET$2}${installs ? ` ${CYAN$1}${installs}${RESET$2}` : ""}`);
-			console.log(`${DIM$2}└ https://skpm.sh/${skill.slug}${RESET$2}`);
+			console.log(`${TEXT$3}${pkg}@${skill.name}${RESET$4}${installs ? ` ${CYAN$1}${installs}${RESET$4}` : ""}`);
+			console.log(`${DIM$4}└ https://skpm.sh/${skill.slug}${RESET$4}`);
 			console.log();
 		}
 		return;
@@ -3168,14 +3217,14 @@ ${DIM$2}  2) npx skpm-cli add <owner/repo@skill>${RESET$2}`;
 		interactive: "1"
 	});
 	if (!selected) {
-		console.log(`${DIM$2}Search cancelled${RESET$2}`);
+		console.log(`${DIM$4}Search cancelled${RESET$4}`);
 		console.log();
 		return;
 	}
 	const pkg = selected.source || selected.slug;
 	const skillName = selected.name;
 	console.log();
-	console.log(`${TEXT$1}Installing ${BOLD$2}${skillName}${RESET$2} from ${DIM$2}${pkg}${RESET$2}...`);
+	console.log(`${TEXT$3}Installing ${BOLD$4}${skillName}${RESET$4} from ${DIM$4}${pkg}${RESET$4}...`);
 	console.log();
 	const { source, options } = parseAddOptions([
 		pkg,
@@ -3185,8 +3234,8 @@ ${DIM$2}  2) npx skpm-cli add <owner/repo@skill>${RESET$2}`;
 	await runAdd(source, options);
 	console.log();
 	const info = getOwnerRepoFromString(pkg);
-	if (info && await isRepoPublic(info.owner, info.repo)) console.log(`${DIM$2}View the skill at${RESET$2} ${TEXT$1}https://skpm.sh/${selected.slug}${RESET$2}`);
-	else console.log(`${DIM$2}Discover more skills at${RESET$2} ${TEXT$1}https://skpm.sh${RESET$2}`);
+	if (info && await isRepoPublic(info.owner, info.repo)) console.log(`${DIM$4}View the skill at${RESET$4} ${TEXT$3}https://skpm.sh/${selected.slug}${RESET$4}`);
+	else console.log(`${DIM$4}Discover more skills at${RESET$4} ${TEXT$3}https://skpm.sh${RESET$4}`);
 	console.log();
 }
 const isCancelled = (value) => typeof value === "symbol";
@@ -3523,9 +3572,9 @@ async function runInstallFromLock(args) {
 		}
 	}
 }
-const RESET$1 = "\x1B[0m";
-const BOLD$1 = "\x1B[1m";
-const DIM$1 = "\x1B[38;5;102m";
+const RESET$3 = "\x1B[0m";
+const BOLD$3 = "\x1B[1m";
+const DIM$3 = "\x1B[38;5;102m";
 const CYAN = "\x1B[36m";
 const YELLOW = "\x1B[33m";
 function shortenPath(fullPath, cwd) {
@@ -3561,8 +3610,8 @@ async function runList(args) {
 		const validAgents = Object.keys(agents);
 		const invalidAgents = options.agent.filter((a) => !validAgents.includes(a));
 		if (invalidAgents.length > 0) {
-			console.log(`${YELLOW}Invalid agents: ${invalidAgents.join(", ")}${RESET$1}`);
-			console.log(`${DIM$1}Valid agents: ${validAgents.join(", ")}${RESET$1}`);
+			console.log(`${YELLOW}Invalid agents: ${invalidAgents.join(", ")}${RESET$3}`);
+			console.log(`${DIM$3}Valid agents: ${validAgents.join(", ")}${RESET$3}`);
 			process.exit(1);
 		}
 		agentFilter = options.agent;
@@ -3589,20 +3638,20 @@ async function runList(args) {
 			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}`);
+		console.log(`${DIM$3}No ${scopeLabel.toLowerCase()} skills found.${RESET$3}`);
+		if (scope) console.log(`${DIM$3}Try listing project skills without -g${RESET$3}`);
+		else console.log(`${DIM$3}Try listing global skills with -g${RESET$3}`);
 		return;
 	}
 	function printSkill(skill, indent = false) {
 		const prefix = indent ? "  " : "";
 		const shortPath = shortenPath(skill.canonicalPath, cwd);
 		const agentNames = skill.agents.map((a) => agents[a].displayName);
-		const agentInfo = skill.agents.length > 0 ? formatList(agentNames) : `${YELLOW}not linked${RESET$1}`;
-		console.log(`${prefix}${CYAN}${skill.name}${RESET$1} ${DIM$1}${shortPath}${RESET$1}`);
-		console.log(`${prefix}  ${DIM$1}Agents:${RESET$1} ${agentInfo}`);
+		const agentInfo = skill.agents.length > 0 ? formatList(agentNames) : `${YELLOW}not linked${RESET$3}`;
+		console.log(`${prefix}${CYAN}${skill.name}${RESET$3} ${DIM$3}${shortPath}${RESET$3}`);
+		console.log(`${prefix}  ${DIM$3}Agents:${RESET$3} ${agentInfo}`);
 	}
-	console.log(`${BOLD$1}${scopeLabel} Skills${RESET$1}`);
+	console.log(`${BOLD$3}${scopeLabel} Skills${RESET$3}`);
 	console.log();
 	const groupedSkills = {};
 	const ungroupedSkills = [];
@@ -3618,13 +3667,13 @@ async function runList(args) {
 		const sortedGroups = Object.keys(groupedSkills).sort();
 		for (const group of sortedGroups) {
 			const title = group.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
-			console.log(`${BOLD$1}${title}${RESET$1}`);
+			console.log(`${BOLD$3}${title}${RESET$3}`);
 			const skills = groupedSkills[group];
 			if (skills) for (const skill of skills) printSkill(skill, true);
 			console.log();
 		}
 		if (ungroupedSkills.length > 0) {
-			console.log(`${BOLD$1}General${RESET$1}`);
+			console.log(`${BOLD$3}General${RESET$3}`);
 			for (const skill of ungroupedSkills) printSkill(skill, true);
 			console.log();
 		}
@@ -3823,6 +3872,218 @@ function parseRemoveOptions(args) {
 		options
 	};
 }
+const RESET$2 = "\x1B[0m";
+const BOLD$2 = "\x1B[1m";
+const DIM$2 = "\x1B[38;5;102m";
+const TEXT$2 = "\x1B[38;5;145m";
+async function buildDependencyTree(skill, resolving, cloneCache, tempDirs) {
+	const nodes = [];
+	for (const depRef of skill.dependsOn) {
+		if (resolving.has(depRef)) {
+			nodes.push({
+				name: `${depRef} (circular)`,
+				ref: depRef,
+				children: []
+			});
+			continue;
+		}
+		const parsed = parseDependencyRef(depRef);
+		if (!parsed) {
+			nodes.push({
+				name: `${depRef} (invalid ref)`,
+				ref: depRef,
+				children: []
+			});
+			continue;
+		}
+		resolving.add(depRef);
+		try {
+			const parsedSource = parseSource(parsed.source);
+			let depDir;
+			const cacheKey = parsedSource.url;
+			if (cloneCache.has(cacheKey)) depDir = cloneCache.get(cacheKey);
+			else if (parsedSource.type === "local") depDir = parsedSource.localPath;
+			else {
+				depDir = await cloneRepo(parsedSource.url, parsedSource.ref);
+				tempDirs.add(depDir);
+				cloneCache.set(cacheKey, depDir);
+			}
+			const depSkills = await discoverSkills(depDir, parsedSource.subpath, { includeInternal: true });
+			const targetSkills = parsed.skillName ? depSkills.filter((s) => s.name.toLowerCase() === parsed.skillName.toLowerCase()) : depSkills;
+			for (const depSkill of targetSkills) {
+				const children = await buildDependencyTree(depSkill, resolving, cloneCache, tempDirs);
+				nodes.push({
+					name: depRef,
+					ref: depRef,
+					children
+				});
+			}
+			if (targetSkills.length === 0) nodes.push({
+				name: `${depRef} (not found)`,
+				ref: depRef,
+				children: []
+			});
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			nodes.push({
+				name: `${depRef} (error: ${msg})`,
+				ref: depRef,
+				children: []
+			});
+		}
+	}
+	return nodes;
+}
+function printTree(nodes, prefix = "") {
+	for (let i = 0; i < nodes.length; i++) {
+		const node = nodes[i];
+		const isLast = i === nodes.length - 1;
+		const connector = isLast ? "└── " : "├── ";
+		const childPrefix = isLast ? "    " : "│   ";
+		console.log(`${prefix}${connector}${TEXT$2}${node.name}${RESET$2}`);
+		if (node.children.length > 0) printTree(node.children, prefix + childPrefix);
+	}
+}
+async function runDeps(args) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(`
+${BOLD$2}Usage:${RESET$2} skpm deps <package>
+
+${BOLD$2}Description:${RESET$2}
+  Show the dependency tree for a skill without installing it.
+
+${BOLD$2}Arguments:${RESET$2}
+  package           Skill reference (e.g., owner/repo@skill-name)
+
+${BOLD$2}Examples:${RESET$2}
+  ${DIM$2}$${RESET$2} skpm deps jonmumm/skills@swarm
+  ${DIM$2}$${RESET$2} skpm deps vercel-labs/agent-skills@pr-review
+`);
+		return;
+	}
+	const source = args[0];
+	if (!source) {
+		console.log(`${RESET$2}Missing required argument: package`);
+		console.log(`${DIM$2}Usage: skpm deps <package>${RESET$2}`);
+		process.exit(1);
+	}
+	const tempDirs = /* @__PURE__ */ new Set();
+	const cloneCache = /* @__PURE__ */ new Map();
+	try {
+		const parsed = parseSource(source);
+		let skillsDir;
+		if (parsed.type === "local") skillsDir = parsed.localPath;
+		else {
+			console.log(`${DIM$2}Cloning repository...${RESET$2}`);
+			skillsDir = await cloneRepo(parsed.url, parsed.ref);
+			tempDirs.add(skillsDir);
+			cloneCache.set(parsed.url, skillsDir);
+		}
+		const skills = await discoverSkills(skillsDir, parsed.subpath, { includeInternal: true });
+		const targetSkills = parsed.skillFilter ? skills.filter((s) => s.name.toLowerCase() === parsed.skillFilter.toLowerCase()) : skills;
+		if (targetSkills.length === 0) {
+			console.log(`No skills found matching: ${source}`);
+			process.exit(1);
+		}
+		for (const skill of targetSkills) {
+			console.log(`${BOLD$2}${skill.name}${RESET$2}`);
+			if (skill.dependsOn.length === 0) {
+				console.log(`${DIM$2}  (no dependencies)${RESET$2}`);
+				continue;
+			}
+			printTree(await buildDependencyTree(skill, /* @__PURE__ */ new Set(), cloneCache, tempDirs));
+		}
+	} finally {
+		for (const dir of tempDirs) await cleanupTempDir(dir).catch(() => {});
+	}
+}
+const RESET$1 = "\x1B[0m";
+const BOLD$1 = "\x1B[1m";
+const DIM$1 = "\x1B[38;5;102m";
+const TEXT$1 = "\x1B[38;5;145m";
+function parseRunScriptsOptions(args) {
+	const options = {};
+	let skillName;
+	for (const arg of args) if (arg === "--trust-scripts") options.trustScripts = true;
+	else if (!arg.startsWith("-")) skillName = arg;
+	return {
+		skillName,
+		options
+	};
+}
+async function runRunScripts(args) {
+	if (args.includes("--help") || args.includes("-h")) {
+		console.log(`
+${BOLD$1}Usage:${RESET$1} skpm run-scripts <skill-name> [options]
+
+${BOLD$1}Description:${RESET$1}
+  Execute postInstall commands for an already-installed skill.
+
+${BOLD$1}Arguments:${RESET$1}
+  skill-name        Name of the installed skill
+
+${BOLD$1}Options:${RESET$1}
+  --trust-scripts   Auto-accept without prompting
+
+${BOLD$1}Examples:${RESET$1}
+  ${DIM$1}$${RESET$1} skpm run-scripts swarm
+  ${DIM$1}$${RESET$1} skpm run-scripts swarm --trust-scripts
+`);
+		return;
+	}
+	const { skillName, options } = parseRunScriptsOptions(args);
+	if (!skillName) {
+		console.log(`Missing required argument: skill-name`);
+		console.log(`${DIM$1}Usage: skpm run-scripts <skill-name>${RESET$1}`);
+		process.exit(1);
+	}
+	const skillMdPath = join(join(homedir(), ".agents", "skills", skillName), "SKILL.md");
+	if (!existsSync(skillMdPath)) {
+		console.log(`Skill not found: ${skillName}`);
+		console.log(`${DIM$1}Expected at: ${skillMdPath}${RESET$1}`);
+		process.exit(1);
+	}
+	const skill = await parseSkillMd(skillMdPath, { includeInternal: true });
+	if (!skill) {
+		console.log(`Failed to parse SKILL.md for: ${skillName}`);
+		process.exit(1);
+	}
+	if (skill.postInstall.length === 0) {
+		console.log(`${TEXT$1}No postInstall commands defined for ${skillName}${RESET$1}`);
+		return;
+	}
+	console.log(`${TEXT$1}Post-install commands for ${BOLD$1}${skillName}${RESET$1}${TEXT$1}:${RESET$1}`);
+	console.log(formatPostInstallCommands(skill.postInstall));
+	console.log();
+	let shouldRun = options.trustScripts === true;
+	if (!shouldRun) {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout
+		});
+		const answer = await new Promise((resolve) => {
+			rl.question("Run these commands? [y/N] ", (ans) => {
+				rl.close();
+				resolve(ans);
+			});
+		});
+		shouldRun = answer.toLowerCase() === "y" || answer.toLowerCase() === "yes";
+	}
+	if (shouldRun) {
+		const result = await executePostInstallCommands(skill.postInstall, (cmd) => {
+			console.log(`${DIM$1}$ ${cmd}${RESET$1}`);
+			execSync(cmd, { stdio: "inherit" });
+		});
+		if (result.failed.length > 0) {
+			for (const f of result.failed) {
+				console.log(`${RESET$1}Command failed: ${f.command}`);
+				console.log(`${DIM$1}${f.error}${RESET$1}`);
+			}
+			process.exit(1);
+		}
+		console.log(`${TEXT$1}All commands completed successfully${RESET$1}`);
+	} else console.log(`${DIM$1}Skipped.${RESET$1}`);
+}
 const __dirname = dirname(fileURLToPath(import.meta.url));
 function getVersion() {
 	try {
@@ -3898,6 +4159,10 @@ ${BOLD}Updates:${RESET}
   check                Check for available skill updates
   update               Update all skills to latest versions
 
+${BOLD}Inspect:${RESET}
+  deps <package>       Show dependency tree for a skill
+  run-scripts <name>   Execute postInstall for an installed skill
+
 ${BOLD}Project:${RESET}
   experimental_install Restore skills from skills-lock.json
   init [name]          Initialize a skill (creates <name>/SKILL.md or ./SKILL.md)
@@ -4318,6 +4583,12 @@ async function main() {
 			await runSync(restArgs, syncOptions);
 			break;
 		}
+		case "deps":
+			await runDeps(restArgs);
+			break;
+		case "run-scripts":
+			await runRunScripts(restArgs);
+			break;
 		case "list":
 		case "ls":
 			await runList(restArgs);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skpm-cli",
-  "version": "1.4.7",
+  "version": "1.4.8",
   "description": "The Skill Package Manager for AI Agents",
   "type": "module",
   "bin": {