skills-package-manager 0.6.2 → 0.6.3

package/README.md

@@ -1,42 +1,59 @@
-# spm
+# skills-package-manager
 
 Core library and CLI for managing agent skills.
 
 ## CLI Usage
 
+For one-off usage, `npx skills-package-manager add ...` is the low-friction migration path for teams already familiar with `npx skills add ...`.
+
 ```bash
-spm --help
-spm --version
-spm add <specifier> [--skill <name>]
-spm install
-spm update [skill...]
-spm init [--yes]
+npx skills-package-manager --help
+npx skills-package-manager --version
+npx skills-package-manager add <specifier> [--skill <name>]
+npx skills-package-manager install
+npx skills-package-manager update [skill...]
+npx skills-package-manager init [--yes]
 ```
 
-- `spm` with no command shows top-level help
-- `spm --help` prints top-level help
-- `spm --version` prints the package version
+- `npx skills-package-manager` with no command shows top-level help
+- `npx skills-package-manager --help` prints top-level help
+- `npx skills-package-manager --version` prints the package version
 
-### `spm add`
+### `npx skills-package-manager add`
 
 Add skills to your project.
 
+For teams already familiar with `npx skills add ...`, the headline migration message is:
+
+```bash
+npx skills add owner/repo
+# becomes
+npx skills-package-manager add owner/repo
+```
+
 ```bash
 # Interactive — clone repo, discover skills, select via multiselect prompt
-spm add owner/repo
-spm add https://github.com/owner/repo
+npx skills-package-manager add owner/repo
+npx skills-package-manager add https://github.com/owner/repo
 
 # Non-interactive — add a specific skill by name
-spm add owner/repo --skill find-skills
+npx skills-package-manager add owner/repo --skill find-skills
+npx skills-package-manager add owner/repo@find-skills
+npx skills-package-manager add owner/repo#main@find-skills
+
+# Direct repo subpath
+npx skills-package-manager add owner/repo/skills/my-skill
+npx skills-package-manager add https://github.com/owner/repo/tree/main/skills/my-skill#main
 
 # Direct specifier — skip discovery
-spm add https://github.com/owner/repo.git#path:/skills/my-skill
-spm add link:./local-source/skills/my-skill
-spm add file:./skills-package.tgz#path:/skills/my-skill
-spm add npm:@scope/skills-package#path:/skills/my-skill
+npx skills-package-manager add https://github.com/owner/repo.git#path:/skills/my-skill
+npx skills-package-manager add link:./local-source/skills/my-skill
+npx skills-package-manager add ./local-source
+npx skills-package-manager add file:./skills-package.tgz#path:/skills/my-skill
+npx skills-package-manager add npm:@scope/skills-package#path:/skills/my-skill
 ```
 
-After `spm add`, the newly added skills are resolved, materialized into `installDir`, and linked to each configured `linkTarget` immediately.
+After `npx skills-package-manager add`, the newly added skills are resolved, materialized into `installDir`, and linked to each configured `linkTarget` immediately.
 
 #### How it works
 
@@ -48,25 +65,25 @@ When given `owner/repo` or a GitHub URL:
 4. Writes selected skills to `skills.json` and resolves `skills-lock.yaml`
 5. Cleans up the temp directory
 
-### `spm init`
+### `npx skills-package-manager init`
 
 Create a new `skills.json` manifest in the current directory.
 
 ```bash
 # Interactive — prompt for installDir and linkTargets
-spm init
+npx skills-package-manager init
 
 # Non-interactive — write the default manifest immediately
-spm init --yes
+npx skills-package-manager init --yes
 ```
 
 Behavior:
 
-- `spm init` prompts for `installDir` and `linkTargets`, then writes `skills.json`
-- `spm init --yes` skips prompts and writes the default manifest
+- `npx skills-package-manager init` prompts for `installDir` and `linkTargets`, then writes `skills.json`
+- `npx skills-package-manager init --yes` skips prompts and writes the default manifest
 - If `skills.json` already exists, the command fails and does not overwrite it
 
-Default `skills.json` written by `spm init --yes`:
+Default `skills.json` written by `npx skills-package-manager init --yes`:
 
 ```json
 {
@@ -77,24 +94,24 @@ Default `skills.json` written by `spm init --yes`:
 }
 ```
 
-### `spm install`
+### `npx skills-package-manager install`
 
 Install all skills declared in `skills.json`:
 
 ```bash
-spm install
+npx skills-package-manager install
 ```
 
 This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
-When `selfSkill` is `true`, `spm install` also installs the bundled `skills-package-manager-cli` skill so users get guidance for `skills.json`, `skills-lock.yaml`, and the `spm` workflow. This helper skill is not written to `skills-lock.yaml`.
+When `selfSkill` is `true`, `npx skills-package-manager install` also installs the bundled `skills-package-manager-cli` skill so users get guidance for `skills.json`, `skills-lock.yaml`, and `npx skills-package-manager` commands. This helper skill is not written to `skills-lock.yaml`.
 
-### `spm update`
+### `npx skills-package-manager update`
 
 Refresh resolvable skills declared in `skills.json` without changing the manifest:
 
 ```bash
-spm update
-spm update find-skills rspress-custom-theme
+npx skills-package-manager update
+npx skills-package-manager update find-skills rspress-custom-theme
 ```
 
 Behavior:
@@ -153,7 +170,7 @@ link: link:<path-to-skill-dir>
 
 ```
 src/
-├── bin/           # CLI entry points (spm, skills)
+├── bin/           # CLI entry points
 ├── cli/           # CLI runner and interactive prompts
 ├── commands/      # add, install command implementations
 ├── config/        # skills.json / skills-lock.yaml read/write

package/dist/index.js

@@ -1,21 +1,302 @@
 import { cac } from "cac";
+import { accessSync, createReadStream, existsSync } from "node:fs";
+import node_path, { basename, join } from "node:path";
 import picocolors from "picocolors";
+import { homedir, tmpdir } from "node:os";
 import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat as promises_stat, symlink, writeFile } from "node:fs/promises";
-import node_path, { basename, join } from "node:path";
 import yaml from "yaml";
 import { z } from "zod";
 import { execFile } from "node:child_process";
-import { homedir, tmpdir } from "node:os";
 import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import semver from "semver";
-import { accessSync, createReadStream } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { x } from "tar";
 import * as __rspack_external__clack_prompts_3cae1695 from "@clack/prompts";
 var package_namespaceObject = {
-    rE: "0.6.2"
+    rE: "0.6.3"
 };
+function getHomeDir() {
+    return homedir();
+}
+function getConfigHome() {
+    return process.env.XDG_CONFIG_HOME?.trim() || node_path.join(getHomeDir(), '.config');
+}
+function getCodexHome() {
+    return process.env.CODEX_HOME?.trim() || node_path.join(getHomeDir(), '.codex');
+}
+function getClaudeHome() {
+    return process.env.CLAUDE_CONFIG_DIR?.trim() || node_path.join(getHomeDir(), '.claude');
+}
+function getOpenClawGlobalSkillsDir(homeDir = getHomeDir()) {
+    if (existsSync(node_path.join(homeDir, '.openclaw'))) return node_path.join(homeDir, '.openclaw/skills');
+    if (existsSync(node_path.join(homeDir, '.clawdbot'))) return node_path.join(homeDir, '.clawdbot/skills');
+    if (existsSync(node_path.join(homeDir, '.moltbot'))) return node_path.join(homeDir, '.moltbot/skills');
+    return node_path.join(homeDir, '.openclaw/skills');
+}
+const COMPATIBLE_ADD_AGENTS = {
+    adal: {
+        displayName: 'Adal',
+        projectPath: '.adal/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.adal/skills')
+    },
+    amp: {
+        displayName: 'Amp',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getConfigHome(), 'agents/skills')
+    },
+    antigravity: {
+        displayName: 'Antigravity',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.gemini/antigravity/skills')
+    },
+    augment: {
+        displayName: 'Augment',
+        projectPath: '.augment/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.augment/skills')
+    },
+    bob: {
+        displayName: 'IBM Bob',
+        projectPath: '.bob/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.bob/skills')
+    },
+    'claude-code': {
+        displayName: 'Claude Code',
+        projectPath: '.claude/skills',
+        globalPath: ()=>node_path.join(getClaudeHome(), 'skills')
+    },
+    cline: {
+        displayName: 'Cline',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.agents/skills')
+    },
+    codebuddy: {
+        displayName: 'CodeBuddy',
+        projectPath: '.codebuddy/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.codebuddy/skills')
+    },
+    codex: {
+        displayName: 'Codex',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getCodexHome(), 'skills')
+    },
+    'command-code': {
+        displayName: 'Command Code',
+        projectPath: '.commandcode/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.commandcode/skills')
+    },
+    continue: {
+        displayName: 'Continue',
+        projectPath: '.continue/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.continue/skills')
+    },
+    cortex: {
+        displayName: 'Cortex Code',
+        projectPath: '.cortex/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.snowflake/cortex/skills')
+    },
+    crush: {
+        displayName: 'Crush',
+        projectPath: '.crush/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.config/crush/skills')
+    },
+    cursor: {
+        displayName: 'Cursor',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.cursor/skills')
+    },
+    deepagents: {
+        displayName: 'Deep Agents',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.deepagents/agent/skills')
+    },
+    droid: {
+        displayName: 'Droid',
+        projectPath: '.factory/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.factory/skills')
+    },
+    firebender: {
+        displayName: 'Firebender',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.firebender/skills')
+    },
+    'gemini-cli': {
+        displayName: 'Gemini CLI',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.gemini/skills')
+    },
+    'github-copilot': {
+        displayName: 'GitHub Copilot',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.copilot/skills')
+    },
+    goose: {
+        displayName: 'Goose',
+        projectPath: '.goose/skills',
+        globalPath: ()=>node_path.join(getConfigHome(), 'goose/skills')
+    },
+    'iflow-cli': {
+        displayName: 'iFlow CLI',
+        projectPath: '.iflow/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.iflow/skills')
+    },
+    junie: {
+        displayName: 'Junie',
+        projectPath: '.junie/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.junie/skills')
+    },
+    kilo: {
+        displayName: 'Kilo Code',
+        projectPath: '.kilocode/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.kilocode/skills')
+    },
+    'kimi-cli': {
+        displayName: 'Kimi Code CLI',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.config/agents/skills')
+    },
+    'kiro-cli': {
+        displayName: 'Kiro CLI',
+        projectPath: '.kiro/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.kiro/skills')
+    },
+    kode: {
+        displayName: 'Kode',
+        projectPath: '.kode/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.kode/skills')
+    },
+    mcpjam: {
+        displayName: 'MCPJam',
+        projectPath: '.mcpjam/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.mcpjam/skills')
+    },
+    'mistral-vibe': {
+        displayName: 'Mistral Vibe',
+        projectPath: '.vibe/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.vibe/skills')
+    },
+    mux: {
+        displayName: 'Mux',
+        projectPath: '.mux/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.mux/skills')
+    },
+    neovate: {
+        displayName: 'Neovate',
+        projectPath: '.neovate/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.neovate/skills')
+    },
+    opencode: {
+        displayName: 'OpenCode',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getConfigHome(), 'opencode/skills')
+    },
+    openclaw: {
+        displayName: 'OpenClaw',
+        projectPath: 'skills',
+        globalPath: ()=>getOpenClawGlobalSkillsDir()
+    },
+    openhands: {
+        displayName: 'OpenHands',
+        projectPath: '.openhands/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.openhands/skills')
+    },
+    pi: {
+        displayName: 'PI',
+        projectPath: '.pi/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.pi/agent/skills')
+    },
+    pochi: {
+        displayName: 'Pochi',
+        projectPath: '.pochi/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.pochi/skills')
+    },
+    qoder: {
+        displayName: 'Qoder',
+        projectPath: '.qoder/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.qoder/skills')
+    },
+    'qwen-code': {
+        displayName: 'Qwen Code',
+        projectPath: '.qwen/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.qwen/skills')
+    },
+    replit: {
+        displayName: 'Replit',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getConfigHome(), 'agents/skills')
+    },
+    roo: {
+        displayName: 'Roo',
+        projectPath: '.roo/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.roo/skills')
+    },
+    trae: {
+        displayName: 'Trae',
+        projectPath: '.trae/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.trae/skills')
+    },
+    'trae-cn': {
+        displayName: 'Trae CN',
+        projectPath: '.trae/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.trae-cn/skills')
+    },
+    universal: {
+        displayName: 'Universal',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getConfigHome(), 'agents/skills')
+    },
+    warp: {
+        displayName: 'Warp',
+        projectPath: '.agents/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.agents/skills')
+    },
+    windsurf: {
+        displayName: 'Windsurf',
+        projectPath: '.windsurf/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.codeium/windsurf/skills')
+    },
+    zencoder: {
+        displayName: 'Zencoder',
+        projectPath: '.zencoder/skills',
+        globalPath: ()=>node_path.join(getHomeDir(), '.zencoder/skills')
+    }
+};
+function dedupePreserveOrder(values) {
+    return [
+        ...new Set(values)
+    ];
+}
+function listCompatibleAddAgentNames() {
+    return Object.keys(COMPATIBLE_ADD_AGENTS).sort();
+}
+function getCompatibleAddAgent(name) {
+    return COMPATIBLE_ADD_AGENTS[name] ?? null;
+}
+function resolveCompatibleAddAgentTargets(agentNames, options) {
+    if (!agentNames || 0 === agentNames.length) return {
+        invalidAgents: [],
+        linkTargets: []
+    };
+    const expandedAgentNames = agentNames.includes('*') ? listCompatibleAddAgentNames() : agentNames;
+    const linkTargets = [];
+    const invalidAgents = [];
+    for (const agentName of dedupePreserveOrder(expandedAgentNames)){
+        const target = getCompatibleAddAgent(agentName);
+        if (!target) {
+            invalidAgents.push(agentName);
+            continue;
+        }
+        const nextTarget = options.global ? target.globalPath() : target.projectPath;
+        if ('.agents/skills' !== nextTarget || '.agents/skills' !== options.installDir) linkTargets.push(nextTarget);
+    }
+    return {
+        invalidAgents,
+        linkTargets: dedupePreserveOrder(linkTargets)
+    };
+}
+function getSkillsPackageManagerHome() {
+    return process.env.SKILLS_PACKAGE_MANAGER_HOME?.trim() || node_path.join(getHomeDir(), '.skills-package-manager');
+}
 const UNIVERSAL_AGENT_NAMES = [
     'Amp',
     'Antigravity',
@@ -437,9 +718,6 @@ const skillsManifestSchema = z.object({
     installDir: z.string().default('.agents/skills').describe('Directory where skills will be installed'),
     linkTargets: z.array(z.string()).default([]).describe('Directories where skill symlinks will be created'),
     selfSkill: z.boolean().optional().describe('Whether this project is itself a skill'),
-    pnpmPlugin: z.object({
-        removePnpmfileChecksum: z.boolean().optional().describe('Temporarily remove pnpmfileChecksum from pnpm lockfiles in pnpm-plugin-skills afterAllResolved')
-    }).optional().describe('pnpm-plugin-skills specific compatibility settings'),
     skills: z.record(z.string(), z.string()).default({}).describe('Map of skill names to their specifiers')
 }).strict();
 async function readSkillsManifest(rootDir) {
@@ -1005,7 +1283,6 @@ async function writeSkillsManifest(rootDir, manifest) {
         skills: manifest.skills
     };
     if (void 0 !== manifest.selfSkill) nextManifest.selfSkill = manifest.selfSkill;
-    if (void 0 !== manifest.pnpmPlugin) nextManifest.pnpmPlugin = manifest.pnpmPlugin;
     try {
         await writeFile(filePath, `${JSON.stringify(nextManifest, null, 2)}\n`, 'utf8');
     } catch (error) {
@@ -1023,6 +1300,11 @@ const SKIP_DIRS = new Set([
     'build',
     '__pycache__'
 ]);
+const ALLOWED_HIDDEN_DIRS = new Set([
+    '.agents',
+    '.claude',
+    '.github'
+]);
 function parseSkillFrontmatter(content) {
     const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
     if (!fmMatch) return {
@@ -1059,43 +1341,32 @@ async function parseSkillDir(dir, relativePath) {
         return null;
     }
 }
-async function scanForSkills(baseDir, subDir) {
+function shouldSkipDir(name) {
+    if (SKIP_DIRS.has(name)) return true;
+    return name.startsWith('.') && !ALLOWED_HIDDEN_DIRS.has(name);
+}
+async function scanForSkillsRecursive(baseDir, subDir = '') {
     const searchDir = subDir ? join(baseDir, subDir) : baseDir;
-    const skills = [];
     try {
         const entries = await readdir(searchDir, {
             withFileTypes: true
         });
-        const dirs = entries.filter((e)=>e.isDirectory() && !SKIP_DIRS.has(e.name));
-        const checks = dirs.map(async (entry)=>{
+        const dirs = entries.filter((entry)=>entry.isDirectory() && !shouldSkipDir(entry.name));
+        const results = await Promise.all(dirs.map(async (entry)=>{
+            const relativePath = subDir ? `${subDir}/${entry.name}` : entry.name;
             const fullPath = join(searchDir, entry.name);
             if (await hasSkillMd(fullPath)) {
-                const relativePath = subDir ? `/${subDir}/${entry.name}` : `/${entry.name}`;
-                return parseSkillDir(fullPath, relativePath);
+                const parsed = await parseSkillDir(fullPath, `/${relativePath}`);
+                return parsed ? [
+                    parsed
+                ] : [];
             }
-            return null;
-        });
-        const results = await Promise.all(checks);
-        for (const r of results)if (r) skills.push(r);
-    } catch  {}
-    return skills;
-}
-async function discoverSkillsInDirs(baseDir, commonDirs, options) {
-    if (options?.includeRoot ?? true) {
-        const rootSkills = await scanForSkills(baseDir, '');
-        if (rootSkills.length > 0) {
-            rootSkills.sort((a, b)=>a.name.localeCompare(b.name));
-            return rootSkills;
-        }
-    }
-    for (const dir of commonDirs){
-        const skills = await scanForSkills(baseDir, dir);
-        if (skills.length > 0) {
-            skills.sort((a, b)=>a.name.localeCompare(b.name));
-            return skills;
-        }
+            return scanForSkillsRecursive(baseDir, relativePath);
+        }));
+        return results.flat();
+    } catch  {
+        return [];
     }
-    return [];
 }
 async function cloneAndDiscover(gitUrl, ref) {
     const tempDir = await mkdtemp(join(tmpdir(), 'skills-pm-discover-'));
@@ -1141,12 +1412,9 @@ async function cloneAndDiscover(gitUrl, ref) {
     }
 }
 async function discoverSkillsInDir(baseDir) {
-    return discoverSkillsInDirs(baseDir, [
-        'skills',
-        '.agents/skills',
-        '.claude/skills',
-        '.github/skills'
-    ]);
+    const skills = await scanForSkillsRecursive(baseDir);
+    skills.sort((a, b)=>a.path.localeCompare(b.path) || a.name.localeCompare(b.name));
+    return skills;
 }
 async function listRepoSkills(owner, repo, ref) {
     const gitUrl = `https://github.com/${owner}/${repo}.git`;
@@ -1159,7 +1427,7 @@ function parseOwnerRepo(input) {
     if (!match) return null;
     return {
         owner: match[1],
-        repo: match[2]
+        repo: match[2].replace(/\.git$/, '')
     };
 }
 function parseGitHubUrl(input) {
@@ -1249,7 +1517,6 @@ function normalizeSkillsManifest(manifest) {
         installDir: manifest.installDir ?? '.agents/skills',
         linkTargets: manifest.linkTargets ?? [],
         selfSkill: manifest.selfSkill ?? false,
-        pnpmPlugin: manifest.pnpmPlugin,
         skills: manifest.skills ?? {}
     };
 }
@@ -1305,9 +1572,12 @@ async function writeInstallState(rootDir, installDir, value) {
     const filePath = node_path.join(dirPath, INSTALL_STATE_FILE);
     await writeJson(filePath, value);
 }
+function resolveTargetPath(rootDir, targetPath) {
+    return node_path.isAbsolute(targetPath) ? targetPath : node_path.join(rootDir, targetPath);
+}
 async function linkSkill(rootDir, installDir, linkTarget, skillName) {
     const absoluteTarget = node_path.join(rootDir, installDir, skillName);
-    const absoluteLink = node_path.join(rootDir, linkTarget, skillName);
+    const absoluteLink = node_path.join(resolveTargetPath(rootDir, linkTarget), skillName);
     await ensureDir(node_path.dirname(absoluteLink));
     await replaceSymlink(absoluteTarget, absoluteLink);
 }
@@ -1452,6 +1722,9 @@ async function materializePackedSkill(rootDir, skillName, tarballPath, sourcePat
         }).catch(()=>{});
     }
 }
+function pruneManagedSkills_resolveTargetPath(rootDir, targetPath) {
+    return node_path.isAbsolute(targetPath) ? targetPath : node_path.join(rootDir, targetPath);
+}
 async function isManagedSkillDir(dirPath) {
     try {
         const marker = JSON.parse(await readFile(node_path.join(dirPath, '.skills-pm.json'), 'utf8'));
@@ -1475,7 +1748,7 @@ async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillN
                         force: true
                     });
                     for (const linkTarget of linkTargets){
-                        const linkPath = node_path.join(rootDir, linkTarget, entry);
+                        const linkPath = node_path.join(pruneManagedSkills_resolveTargetPath(rootDir, linkTarget), entry);
                         try {
                             const stat = await lstat(linkPath);
                             if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await rm(linkPath, {
@@ -1632,10 +1905,277 @@ async function installSkills(rootDir, options) {
         installed: Object.keys(runtimeLock.skills)
     };
 }
-function buildGitHubSpecifier(owner, repo, skillPath) {
-    return `https://github.com/${owner}/${repo}.git#path:${skillPath}`;
+function buildGitSpecifier(repoUrl, skillPath, ref) {
+    return ref ? `${repoUrl}#${ref}&path:${skillPath}` : `${repoUrl}#path:${skillPath}`;
+}
+function buildLinkSpecifier(sourceRoot, skillPath) {
+    const absoluteSkillPath = node_path.join(sourceRoot, skillPath.replace(/^\//, ''));
+    return normalizeLinkSource(`link:${absoluteSkillPath}`);
+}
+function isDirectSkillSpecifier(specifier) {
+    return specifier.startsWith('link:') || specifier.startsWith('file:') || specifier.startsWith('npm:') || specifier.includes('#path:') || specifier.includes('&path:');
+}
+function isLocalPathSpecifier(specifier) {
+    return node_path.isAbsolute(specifier) || specifier.startsWith('./') || specifier.startsWith('../') || '.' === specifier || '..' === specifier || /^[a-zA-Z]:[/\\]/.test(specifier);
+}
+function sanitizeSourceSubpath(subpath) {
+    const normalizedSubpath = subpath.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '');
+    if (!normalizedSubpath) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Invalid add source: subpath cannot be empty',
+        content: subpath
+    });
+    if (normalizedSubpath.split('/').some((segment)=>'..' === segment)) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: `Invalid add source: unsafe subpath "${subpath}"`,
+        content: subpath
+    });
+    return normalizedSubpath;
+}
+function formatSourceWithRef(source, ref) {
+    return ref ? `${source}#${ref}` : source;
+}
+function parseTreeUrlSuffix(provider, input, treeSuffix, ref) {
+    const normalizedTreeSuffix = treeSuffix.replace(/\/+$/, '');
+    if (ref) {
+        if (normalizedTreeSuffix === ref) return {
+            ref
+        };
+        if (normalizedTreeSuffix.startsWith(`${ref}/`)) return {
+            ref,
+            subpath: sanitizeSourceSubpath(normalizedTreeSuffix.slice(ref.length + 1))
+        };
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `${provider} tree URL does not match explicit ref "${ref}": ${input}`,
+            content: input
+        });
+    }
+    if (normalizedTreeSuffix.includes('/')) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'GitHub' === provider ? `Ambiguous GitHub tree URL: ${input}. If the ref contains "/", specify it explicitly with "#<ref>" instead.` : `Ambiguous GitLab tree URL: ${input}. GitLab refs can contain slashes, so provide the ref explicitly via #<ref>.`,
+        content: input
+    });
+    return {
+        ref: normalizedTreeSuffix
+    };
+}
+function parseGitHubTreeSource(input, ref) {
+    const treeMatch = input.match(/^https?:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/tree\/(.+?)\/?$/);
+    if (!treeMatch) return null;
+    const [, owner, repo, treeSuffix] = treeMatch;
+    const cleanRepo = repo.replace(/\.git$/, '');
+    const parsedTree = parseTreeUrlSuffix('GitHub', input, treeSuffix, ref);
+    return {
+        type: 'repo',
+        cloneUrl: `https://github.com/${owner}/${cleanRepo}.git`,
+        displaySource: `${owner}/${cleanRepo}`,
+        ref: parsedTree.ref,
+        ...parsedTree.subpath ? {
+            subpath: parsedTree.subpath
+        } : {}
+    };
+}
+function parseGitLabSource(input, ref) {
+    const treeMatch = input.match(/^(https?):\/\/([^/]+)\/(.+?)\/-\/tree\/(.+?)\/?$/);
+    if (treeMatch) {
+        const [, protocol, hostname, repoPath, treeSuffix] = treeMatch;
+        if ('github.com' === hostname) return null;
+        const cleanRepoPath = repoPath.replace(/\.git$/, '');
+        const parsedTree = parseTreeUrlSuffix('GitLab', input, treeSuffix, ref);
+        return {
+            type: 'repo',
+            cloneUrl: `${protocol}://${hostname}/${cleanRepoPath}.git`,
+            displaySource: cleanRepoPath,
+            ref: parsedTree.ref,
+            ...parsedTree.subpath ? {
+                subpath: parsedTree.subpath
+            } : {}
+        };
+    }
+    const gitlabRepoMatch = input.match(/^https?:\/\/gitlab\.com\/(.+?)(?:\.git)?\/?$/);
+    if (!gitlabRepoMatch) return null;
+    const repoPath = gitlabRepoMatch[1];
+    if (!repoPath.includes('/')) return null;
+    const cleanRepoPath = repoPath.replace(/\.git$/, '');
+    return {
+        type: 'repo',
+        cloneUrl: `https://gitlab.com/${cleanRepoPath}.git`,
+        displaySource: cleanRepoPath,
+        ...ref ? {
+            ref
+        } : {}
+    };
+}
+function parseGitHubShorthandSource(input, ref) {
+    const match = input.match(/^([^/]+)\/([^/]+)(?:\/(.+?))?\/?$/);
+    if (!match || input.includes(':') || input.startsWith('.') || input.startsWith('/')) return null;
+    const [, owner, repo, subpath] = match;
+    const cleanRepo = repo.replace(/\.git$/, '');
+    return {
+        type: 'repo',
+        cloneUrl: `https://github.com/${owner}/${cleanRepo}.git`,
+        displaySource: `${owner}/${cleanRepo}`,
+        ...ref ? {
+            ref
+        } : {},
+        ...subpath ? {
+            subpath: sanitizeSourceSubpath(subpath)
+        } : {}
+    };
 }
-async function addSingleSkill(cwd, specifier) {
+function parseGenericGitSource(input, ref) {
+    if (!/^https?:\/\/.+\.git\/?$/i.test(input) && !/^git@[^:]+:.+\.git$/.test(input)) return null;
+    return {
+        type: 'repo',
+        cloneUrl: input.replace(/\/$/, ''),
+        displaySource: input.replace(/\/$/, ''),
+        ...ref ? {
+            ref
+        } : {}
+    };
+}
+function parseAddSourceBase(input, ref) {
+    if (isLocalPathSpecifier(input)) {
+        const resolvedPath = node_path.resolve(input);
+        const skillDocPath = node_path.join(resolvedPath, 'SKILL.md');
+        if (existsSync(skillDocPath)) return {
+            type: 'local',
+            localPath: node_path.dirname(resolvedPath),
+            displaySource: input,
+            subpath: node_path.basename(resolvedPath)
+        };
+        return {
+            type: 'local',
+            localPath: resolvedPath,
+            displaySource: input
+        };
+    }
+    const githubPrefixMatch = input.match(/^github:(.+)$/);
+    if (githubPrefixMatch) return parseAddSourceBase(githubPrefixMatch[1], ref);
+    const gitlabPrefixMatch = input.match(/^gitlab:(.+)$/);
+    if (gitlabPrefixMatch) {
+        const repoPath = gitlabPrefixMatch[1].replace(/^\/+/, '').replace(/\/+$/, '');
+        if (repoPath.split('/').length < 2) return null;
+        return {
+            type: 'repo',
+            cloneUrl: `https://gitlab.com/${repoPath.replace(/\.git$/, '')}.git`,
+            displaySource: repoPath.replace(/\.git$/, ''),
+            ...ref ? {
+                ref
+            } : {}
+        };
+    }
+    const githubTreeSource = parseGitHubTreeSource(input, ref);
+    if (githubTreeSource) return githubTreeSource;
+    const githubRepo = parseGitHubUrl(input);
+    if (githubRepo) return {
+        type: 'repo',
+        cloneUrl: `https://github.com/${githubRepo.owner}/${githubRepo.repo}.git`,
+        displaySource: `${githubRepo.owner}/${githubRepo.repo}`,
+        ...ref ? {
+            ref
+        } : {}
+    };
+    const gitlabSource = parseGitLabSource(input, ref);
+    if (gitlabSource) return gitlabSource;
+    const githubShorthand = parseGitHubShorthandSource(input, ref);
+    if (githubShorthand) return githubShorthand;
+    return parseGenericGitSource(input, ref);
+}
+function extractAddSource(input) {
+    if (isDirectSkillSpecifier(input)) return {
+        source: input
+    };
+    let source = input;
+    let ref;
+    let skill;
+    const hashIndex = input.indexOf('#');
+    if (hashIndex >= 0) {
+        source = input.slice(0, hashIndex);
+        const fragment = input.slice(hashIndex + 1);
+        const skillSeparatorIndex = fragment.indexOf('@');
+        if (skillSeparatorIndex >= 0) {
+            ref = fragment.slice(0, skillSeparatorIndex) || void 0;
+            skill = fragment.slice(skillSeparatorIndex + 1) || void 0;
+        } else ref = fragment || void 0;
+    }
+    if (!skill) {
+        const atIndex = source.lastIndexOf('@');
+        if (atIndex > 0 && atIndex < source.length - 1) {
+            const nextSource = source.slice(0, atIndex);
+            const nextSkill = source.slice(atIndex + 1);
+            if (parseAddSourceBase(nextSource, ref)?.type === 'repo') {
+                source = nextSource;
+                skill = nextSkill;
+            }
+        }
+    }
+    return {
+        source,
+        ref,
+        skill
+    };
+}
+function parseRepoSkillSpecifier(input) {
+    const extracted = extractAddSource(input);
+    if (!extracted.skill) return null;
+    return {
+        specifier: formatSourceWithRef(extracted.source, extracted.ref),
+        skill: extracted.skill
+    };
+}
+function normalizeAddCommandInput(specifier, skill) {
+    const parsedRepoSkill = parseRepoSkillSpecifier(specifier);
+    if (!parsedRepoSkill) return {
+        specifier,
+        skill
+    };
+    return {
+        specifier: parsedRepoSkill.specifier,
+        skill: skill ?? parsedRepoSkill.skill
+    };
+}
+function parseAddSourceSpecifier(specifier) {
+    if (isDirectSkillSpecifier(specifier)) return null;
+    const extracted = extractAddSource(specifier);
+    return parseAddSourceBase(extracted.source, extracted.ref);
+}
+function normalizeRequestedSkill(requestedSkill) {
+    return requestedSkill.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+function findRequestedSkill(skills, requestedSkill) {
+    const normalizedRequestedSkill = normalizeRequestedSkill(requestedSkill);
+    return skills.find((candidate)=>candidate.name === requestedSkill || normalizeRequestedSkill(candidate.path) === normalizedRequestedSkill) ?? null;
+}
+function formatAvailableSkills(skills) {
+    const preview = skills.slice(0, 10).map((candidate)=>`${candidate.name} (${candidate.path})`).join(', ');
+    if (skills.length <= 10) return preview;
+    return `${preview}, ...`;
+}
+function filterSkillsBySubpath(skills, subpath) {
+    if (!subpath) return skills;
+    const normalizedSubpath = normalizeRequestedSkill(subpath);
+    return skills.filter((candidate)=>{
+        const candidatePath = normalizeRequestedSkill(candidate.path);
+        return candidatePath === normalizedSubpath || candidatePath.startsWith(`${normalizedSubpath}/`);
+    });
+}
+async function discoverSkillsFromSource(source) {
+    if ('local' === source.type) {
+        if (!existsSync(source.localPath)) throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Local path does not exist: ${source.localPath}`,
+            content: source.displaySource
+        });
+        const skills = await discoverSkillsInDir(source.localPath);
+        return filterSkillsBySubpath(skills, source.subpath);
+    }
+    const { skills, cleanup } = await cloneAndDiscover(source.cloneUrl, source.ref);
+    await cleanup();
+    return filterSkillsBySubpath(skills, source.subpath);
+}
+async function addSingleSkill(cwd, specifier, manifestDefaults) {
     let normalized;
     try {
         normalized = normalizeSpecifier(specifier);
@@ -1648,11 +2188,16 @@ async function addSingleSkill(cwd, specifier) {
             cause: error
         });
     }
+    await ensureDir(cwd);
     const existingManifest = await readSkillsManifest(cwd) ?? {
-        installDir: '.agents/skills',
-        linkTargets: [],
+        installDir: manifestDefaults?.installDir ?? '.agents/skills',
+        linkTargets: manifestDefaults?.linkTargets ?? [],
         skills: {}
     };
+    if (manifestDefaults) {
+        existingManifest.installDir = manifestDefaults.installDir;
+        existingManifest.linkTargets = manifestDefaults.linkTargets;
+    }
     const existing = existingManifest.skills[normalized.skillName];
     if (existing && existing !== normalized.normalized) throw new SkillError({
         code: codes_ErrorCode.SKILL_EXISTS,
@@ -1669,57 +2214,107 @@ async function addSingleSkill(cwd, specifier) {
         specifier: normalized.normalized
     };
 }
+function normalizeStringArray(values) {
+    if (void 0 === values) return;
+    const arrayValues = Array.isArray(values) ? values : [
+        values
+    ];
+    const normalizedValues = arrayValues.map((value)=>value.trim()).filter(Boolean);
+    return normalizedValues.length > 0 ? normalizedValues : void 0;
+}
+function mergeUnique(existing, next) {
+    return [
+        ...new Set([
+            ...existing ?? [],
+            ...next ?? []
+        ])
+    ];
+}
+async function resolveAddManifestContext(options) {
+    const targetCwd = options.global ? getSkillsPackageManagerHome() : options.cwd;
+    const existingManifest = await readSkillsManifest(targetCwd);
+    const installDir = existingManifest?.installDir ?? '.agents/skills';
+    const requestedAgents = normalizeStringArray(options.agent);
+    if (requestedAgents) {
+        const resolvedTargets = resolveCompatibleAddAgentTargets(requestedAgents, {
+            global: true === options.global,
+            installDir
+        });
+        if (resolvedTargets.invalidAgents.length > 0) throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid agents: ${resolvedTargets.invalidAgents.join(', ')}. Valid agents: ${listCompatibleAddAgentNames().join(', ')}`,
+            content: requestedAgents.join(', ')
+        });
+        return {
+            cwd: targetCwd,
+            installDir,
+            linkTargets: mergeUnique(existingManifest?.linkTargets, resolvedTargets.linkTargets)
+        };
+    }
+    if (options.global && !(existingManifest?.linkTargets && existingManifest.linkTargets.length > 0)) throw new ParseError({
+        code: codes_ErrorCode.INVALID_SPECIFIER,
+        message: 'Global add requires at least one --agent on first use so skills-package-manager knows which global agent directories to link into',
+        content: options.specifier
+    });
+    return {
+        cwd: targetCwd,
+        installDir,
+        linkTargets: existingManifest?.linkTargets ?? []
+    };
+}
 async function addCommand(options) {
-    const { cwd, specifier, skill } = options;
-    const shorthand = parseOwnerRepo(specifier);
-    const githubUrl = shorthand ? null : parseGitHubUrl(specifier);
-    const parsed = shorthand ?? githubUrl;
-    if (parsed) {
-        const { owner, repo } = parsed;
-        const source = `${owner}/${repo}`;
+    const manifestContext = await resolveAddManifestContext(options);
+    const { cwd } = manifestContext;
+    const normalizedInput = normalizeAddCommandInput(options.specifier, options.skill);
+    const { specifier, skill } = normalizedInput;
+    const parsedSource = parseAddSourceSpecifier(specifier);
+    if (parsedSource) {
         __rspack_external__clack_prompts_3cae1695.intro(picocolors.bgCyan(picocolors.black(' spm ')));
         const spinner = __rspack_external__clack_prompts_3cae1695.spinner();
-        if (skill) {
-            spinner.start(`Cloning ${source}...`);
-            const skills = await listRepoSkills(owner, repo);
-            spinner.stop(`Found ${picocolors.green(String(skills.length))} skill${1 !== skills.length ? 's' : ''}`);
-            const found = skills.find((s)=>s.name === skill);
-            const skillPath = found?.path ?? `/${skill}`;
-            const gitSpecifier = buildGitHubSpecifier(owner, repo, skillPath);
-            const result = await addSingleSkill(cwd, gitSpecifier);
-            spinner.start('Installing skills...');
-            await installSkills(cwd);
-            spinner.stop('Installed skills');
-            __rspack_external__clack_prompts_3cae1695.outro(`Added ${picocolors.cyan(result.skillName)}`);
-            return result;
-        }
-        spinner.start(`Cloning ${source}...`);
-        const skills = await listRepoSkills(owner, repo);
-        if (0 === skills.length) {
+        const sourceLabel = parsedSource.displaySource;
+        if ('repo' === parsedSource.type) spinner.start(`Cloning ${sourceLabel}...`);
+        else spinner.start(`Scanning ${sourceLabel}...`);
+        const discoveredSkills = await discoverSkillsFromSource(parsedSource);
+        if (0 === discoveredSkills.length) {
             spinner.stop(picocolors.red('No skills found'));
-            __rspack_external__clack_prompts_3cae1695.outro(picocolors.red(`No valid skills found in ${source}`));
             throw new SkillError({
                 code: codes_ErrorCode.SKILL_NOT_FOUND,
-                skillName: source,
-                message: `No skills found in ${source}`
+                skillName: skill ?? sourceLabel,
+                message: `No valid skills found in ${sourceLabel}`
             });
         }
-        spinner.stop(`Found ${picocolors.green(String(skills.length))} skill${1 !== skills.length ? 's' : ''}`);
-        const selected = await promptSkillSelection(skills);
+        spinner.stop(`Found ${picocolors.green(String(discoveredSkills.length))} skill${1 !== discoveredSkills.length ? 's' : ''}`);
+        let selectedSkills;
+        if ('*' === skill) selectedSkills = discoveredSkills;
+        else if (skill) {
+            const found = findRequestedSkill(discoveredSkills, skill);
+            if (!found) throw new SkillError({
+                code: codes_ErrorCode.SKILL_NOT_FOUND,
+                skillName: skill,
+                message: `Skill ${skill} not found in ${sourceLabel}. Available skills: ${formatAvailableSkills(discoveredSkills)}`
+            });
+            selectedSkills = [
+                found
+            ];
+        } else selectedSkills = options.yes ? discoveredSkills : await promptSkillSelection(discoveredSkills);
         const results = [];
-        for (const s of selected){
-            const gitSpecifier = buildGitHubSpecifier(owner, repo, s.path);
-            const result = await addSingleSkill(cwd, gitSpecifier);
+        for (const selectedSkill of selectedSkills){
+            const nextSpecifier = 'repo' === parsedSource.type ? buildGitSpecifier(parsedSource.cloneUrl, selectedSkill.path, parsedSource.ref) : buildLinkSpecifier(parsedSource.localPath, selectedSkill.path);
+            const result = await addSingleSkill(cwd, nextSpecifier, manifestContext);
             results.push(result);
-            __rspack_external__clack_prompts_3cae1695.log.success(`Added ${picocolors.cyan(result.skillName)}`);
+            if (selectedSkills.length > 1) __rspack_external__clack_prompts_3cae1695.log.success(`Added ${picocolors.cyan(result.skillName)}`);
         }
         spinner.start('Installing skills...');
         await installSkills(cwd);
         spinner.stop('Installed skills');
+        if (1 === results.length) {
+            __rspack_external__clack_prompts_3cae1695.outro(`Added ${picocolors.cyan(results[0].skillName)}`);
+            return results[0];
+        }
         __rspack_external__clack_prompts_3cae1695.outro('Done');
-        return 1 === results.length ? results[0] : results;
+        return results;
     }
-    const result = await addSingleSkill(cwd, specifier);
+    const result = await addSingleSkill(cwd, specifier, manifestContext);
     const spinner = __rspack_external__clack_prompts_3cae1695.spinner();
     spinner.start('Installing skills...');
     await installSkills(cwd);
@@ -2040,13 +2635,19 @@ async function runCli(argv, context = {}) {
     cli.help();
     cli.version(packageVersion);
     cli.showVersionOnExit = false;
-    cli.command('add [...positionals]').option('--skill <name>', 'Select a skill').action(async (positionals = [], options)=>{
+    cli.command('add [...positionals]').option('-a, --agent <name>', 'Target agent').option('-g, --global', 'Install into the global skills workspace').option('--skill <name>', 'Select a skill').option('-y, --yes', 'Skip prompts and select defaults').action(async (positionals = [], options)=>{
         const specifier = positionals[0];
         if (!specifier) throw new Error('Missing required specifier');
+        const agent = Array.isArray(options.agent) ? options.agent : options.agent ? [
+            options.agent
+        ] : void 0;
         return handlers.addCommand({
             cwd,
             specifier,
-            skill: options.skill
+            skill: options.skill,
+            global: options.global,
+            yes: options.yes,
+            agent
         });
     });
     cli.command('install [...args]').option('--frozen-lockfile', 'Fail if lockfile is out of sync').action(async (_args, options)=>handlers.installCommand({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skills-package-manager",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "type": "module",
   "repository": {
     "type": "git",

package/skills/skills-package-manager-cli/SKILL.md

@@ -19,7 +19,7 @@ Use this skill for repositories that already use `skills-package-manager`, or wh
 ## What `selfSkill` Means
 
 - `selfSkill: true` adds the bundled `skills-package-manager-cli` skill during install.
-- It is meant to help users who see `skills.json`, `skills-lock.yaml`, and `spm` commands but do not yet know how they fit together.
+- It is meant to help users who see `skills.json`, `skills-lock.yaml`, and `npx skills-package-manager` commands but do not yet know how they fit together.
 - The bundled skill is injected automatically. It should not be added manually under `skills` unless there is a very specific reason.
 
 ## Command Guide

package/skills.schema.json

@@ -23,17 +23,6 @@
       "description": "Whether this project is itself a skill",
       "type": "boolean"
     },
-    "pnpmPlugin": {
-      "description": "pnpm-plugin-skills specific compatibility settings",
-      "type": "object",
-      "properties": {
-        "removePnpmfileChecksum": {
-          "description": "Temporarily remove pnpmfileChecksum from pnpm lockfiles in pnpm-plugin-skills afterAllResolved",
-          "type": "boolean"
-        }
-      },
-      "additionalProperties": false
-    },
     "skills": {
       "default": {},
       "description": "Map of skill names to their specifiers",