skills-package-manager 0.9.0 → 0.10.0

package/README.md

@@ -50,12 +50,13 @@ npx skills-package-manager add https://github.com/owner/repo/tree/main/skills/my
 # Direct specifier — skip discovery
 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:./.agents/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 `npx skills-package-manager 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, installed or registered according to their protocol, and linked to each configured `linkTarget` immediately.
 
 #### How it works
 
@@ -104,9 +105,9 @@ Install all skills declared in `skills.json`:
 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`.
+This resolves each skill from its specifier, installs managed skills into `installDir` (default `.agents/skills/`), registers `local:` skills in place, and creates symlinks for each `linkTarget`.
 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`.
-If `patchedSkills` contains an entry for a skill, the corresponding patch file is applied after the skill is materialized.
+If `patchedSkills` contains an entry for a managed skill, the corresponding patch file is applied after the skill is materialized. `local:` skills cannot be patched because their source directories are user-owned.
 
 ### `npx skills-package-manager patch`
 
@@ -154,7 +155,7 @@ Behavior:
 
 - Uses `skills.json` as the source of truth
 - Re-resolves git refs and npm package targets
-- Skips `link:` skills, including the bundled self skill
+- Skips local `link:` and `local:` skills, including the bundled self skill
 - Fails immediately for unknown skill names
 - Writes `skills-lock.yaml` only after fetch and link succeed
 
@@ -183,11 +184,12 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 ```text
 git/file/npm: <source>#[ref&]path:<skill-path>
 link: link:<path-to-skill-dir>
+local: local:<path-to-existing-skill-dir>
 ```
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `source` | Git URL, direct `link:` skill path, `file:` tarball, or `npm:` package name | `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `file:./skills.tgz`, `npm:@scope/pkg` |
+| `source` | Git URL, direct `link:` or `local:` skill path, `file:` tarball, or `npm:` package name | `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `local:./.agents/skills/my-skill`, `file:./skills.tgz`, `npm:@scope/pkg` |
 | `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD`, `6cb0992`, `6cb0992a176f2ca142e19f64dca8ac12025b035e` |
 | `path` | Path to skill directory within source | `/skills/my-skill` |
 
@@ -196,7 +198,8 @@ link: link:<path-to-skill-dir>
 ### Resolution Types
 
 - **`git`** — Clones the repo, resolves commit hash, copies skill files
-- **`link`** — Reads from a local directory and copies the selected skill
+- **`link`** — Symlinks a local skill directory into `installDir`
+- **`local`** — Uses an existing user-owned skill directory in place
 - **`file`** — Extracts a local `tgz` package and copies the selected skill
 - **`npm`** — Resolves a package from the configured npm registry, locks the tarball URL/version/integrity, and installs from the downloaded tarball
 

package/dist/index.d.ts

@@ -273,7 +273,7 @@ declare type NormalizedSkillsManifest = {
 };
 
 export declare type NormalizedSpecifier = {
-    type: 'git' | 'link' | 'file' | 'npm';
+    type: 'git' | 'link' | 'local' | 'file' | 'npm';
     source: string;
     ref: string | null;
     path: string;
@@ -396,6 +396,9 @@ export declare type SkillsLockEntry = {
     resolution: {
         type: 'link';
         path: string;
+    } | {
+        type: 'local';
+        path: string;
     } | {
         type: 'file';
         tarball: string;
@@ -471,7 +474,7 @@ export declare type UpdateCommandResult = {
     unchanged: string[];
     skipped: Array<{
         name: string;
-        reason: 'link-specifier';
+        reason: 'link-specifier' | 'local-specifier';
     }>;
     failed: Array<{
         name: string;

package/dist/index.js

@@ -16,7 +16,7 @@ import { co } from "./npm-tar.js";
 import { cac } from "./npm-cac.js";
 import { Ct } from "./npm-clack_core.js";
 var package_namespaceObject = {
-    rE: "0.9.0"
+    rE: "0.10.0"
 };
 function getHomeDir() {
     return homedir();
@@ -660,6 +660,7 @@ function formatErrorForDisplay(error) {
                 output += `\n  - owner/repo (GitHub shorthand)`;
                 output += `\n  - https://github.com/owner/repo.git`;
                 output += `\n  - link:./path/to/skill-dir`;
+                output += `\n  - local:./path/to/existing-skill-dir`;
                 output += `\n  - file:./path/to/skill-package.tgz#path:/skills/my-skill`;
                 output += `\n  - npm:@scope/skill-package#path:/skills/my-skill`;
             }
@@ -899,6 +900,20 @@ async function resolveLinkEntry(cwd, source, skillName, specifier) {
         }
     };
 }
+async function resolveLocalEntry(cwd, source, skillName, specifier) {
+    const sourceRoot = node_path.resolve(cwd, source.slice(6));
+    return {
+        skillName,
+        entry: {
+            specifier,
+            resolution: {
+                type: 'local',
+                path: toPortableRelativePath(cwd, sourceRoot)
+            },
+            digest: ''
+        }
+    };
+}
 const node_modules_semver = __webpack_require__("../../node_modules/.pnpm/semver@7.7.4/node_modules/semver/index.js");
 var node_modules_semver_default = /*#__PURE__*/ __webpack_require__.n(node_modules_semver);
 const resolvedNpmPackageCache = new Map();
@@ -1159,6 +1174,8 @@ async function resolveEntry(cwd, normalized, skillName) {
     switch(normalized.type){
         case 'link':
             return resolveLinkEntry(cwd, normalized.source, finalSkillName, normalized.normalized);
+        case 'local':
+            return resolveLocalEntry(cwd, normalized.source, finalSkillName, normalized.normalized);
         case 'file':
             return resolveFileEntry(cwd, normalized.source, normalized.path, finalSkillName, normalized.normalized);
         case 'git':
@@ -1172,9 +1189,16 @@ async function resolveEntry(cwd, normalized, skillName) {
             }
     }
 }
+function normalizeProtocolPathSource(sourcePart, protocol) {
+    const prefix = `${protocol}:`;
+    const sourcePath = sourcePart.slice(prefix.length).replace(/\\/g, '/').replace(/\/+$/, '');
+    return `${prefix}${sourcePath}`;
+}
 function normalizeLinkSource(sourcePart) {
-    const linkPath = sourcePart.slice(5).replace(/\\/g, '/').replace(/\/+$/, '');
-    return `link:${linkPath}`;
+    return normalizeProtocolPathSource(sourcePart, 'link');
+}
+function normalizeLocalSource(sourcePart) {
+    return normalizeProtocolPathSource(sourcePart, 'local');
 }
 function parseSpecifier(specifier) {
     const firstHashIndex = specifier.indexOf('#');
@@ -1214,11 +1238,14 @@ function parseSpecifier(specifier) {
     };
 }
 function normalizeSpecifier(specifier) {
-    if (specifier.startsWith('link:') && specifier.includes('#')) throw new ParseError({
-        code: codes_ErrorCode.INVALID_SPECIFIER,
-        message: 'Invalid link specifier: link: must point directly to a skill directory',
-        content: specifier
-    });
+    if ((specifier.startsWith('link:') || specifier.startsWith('local:')) && specifier.includes('#')) {
+        const protocol = specifier.startsWith('link:') ? 'link' : 'local';
+        throw new ParseError({
+            code: codes_ErrorCode.INVALID_SPECIFIER,
+            message: `Invalid ${protocol} specifier: ${protocol}: must point directly to a skill directory`,
+            content: specifier
+        });
+    }
     let parsed;
     try {
         parsed = parseSpecifier(specifier);
@@ -1231,17 +1258,17 @@ function normalizeSpecifier(specifier) {
             cause: error
         });
     }
-    const type = parsed.sourcePart.startsWith('link:') ? 'link' : parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
-    if ('link' === type) {
-        const linkSource = normalizeLinkSource(parsed.sourcePart);
-        const linkPath = linkSource.slice(5);
-        const skillName = node_path.posix.basename(linkPath);
+    const type = parsed.sourcePart.startsWith('link:') ? 'link' : parsed.sourcePart.startsWith('local:') ? 'local' : parsed.sourcePart.startsWith('file:') ? 'file' : parsed.sourcePart.startsWith('npm:') ? 'npm' : 'git';
+    if ('link' === type || 'local' === type) {
+        const localSource = 'link' === type ? normalizeLinkSource(parsed.sourcePart) : normalizeLocalSource(parsed.sourcePart);
+        const localPath = localSource.slice(`${type}:`.length);
+        const skillName = node_path.posix.basename(localPath);
         return {
             type,
-            source: linkSource,
+            source: localSource,
             ref: null,
             path: '/',
-            normalized: linkSource,
+            normalized: localSource,
             skillName
         };
     }
@@ -1260,10 +1287,11 @@ function normalizeSpecifier(specifier) {
 function parseForComparison(specifier) {
     const parsed = parseSpecifier(specifier);
     const isLink = parsed.sourcePart.startsWith('link:');
+    const isLocal = parsed.sourcePart.startsWith('local:');
     return {
-        sourcePart: isLink ? normalizeLinkSource(parsed.sourcePart) : parsed.sourcePart,
-        ref: isLink ? null : parsed.ref,
-        path: isLink ? '/' : parsed.path || '/'
+        sourcePart: isLink ? normalizeLinkSource(parsed.sourcePart) : isLocal ? normalizeLocalSource(parsed.sourcePart) : parsed.sourcePart,
+        ref: isLink || isLocal ? null : parsed.ref,
+        path: isLink || isLocal ? '/' : parsed.path || '/'
     };
 }
 function isSpecifierCompatible(manifestSpecifier, lockSpecifier) {
@@ -1344,6 +1372,7 @@ async function resolveLockEntry(cwd, specifier, skillName) {
 async function attachManifestPatchToEntry(cwd, manifest, skillName, entry) {
     const patchPath = manifest.patchedSkills?.[skillName];
     if (!patchPath) return entry;
+    if ('local' === entry.resolution.type) throw new Error(`local: skill ${skillName} cannot be patched because its source is user-owned`);
     const absolutePatchPath = node_path.resolve(cwd, patchPath);
     return {
         ...entry,
@@ -1675,6 +1704,49 @@ async function writeInstallState(rootDir, installDir, value) {
     const filePath = node_path.join(dirPath, INSTALL_STATE_FILE);
     await writeJson(filePath, value);
 }
+function getLocalSkillDirs(rootDir, lockfiles) {
+    const dirs = [];
+    for (const lockfile of lockfiles)if (lockfile) {
+        for (const entry of Object.values(lockfile.skills))if ('local' === entry.resolution.type) dirs.push(node_path.resolve(rootDir, entry.resolution.path));
+    }
+    return Array.from(new Set(dirs));
+}
+function getSkillInstallPath(rootDir, installDir, skillName, entry) {
+    return 'local' === entry.resolution.type ? node_path.resolve(rootDir, entry.resolution.path) : node_path.join(rootDir, installDir, skillName);
+}
+function toRepoRelativePath(rootDir, absolutePath) {
+    const relativePath = node_path.relative(rootDir, absolutePath);
+    if (!relativePath || '..' === relativePath || relativePath.startsWith(`..${node_path.sep}`) || node_path.isAbsolute(relativePath)) return null;
+    return relativePath.split(node_path.sep).join('/');
+}
+function createUnignoreRules(relativePath) {
+    const parts = relativePath.split('/').filter(Boolean);
+    const rules = [];
+    for(let index = 0; index < parts.length; index += 1)rules.push(`!${parts.slice(0, index + 1).join('/')}/`);
+    rules.push(`!${relativePath}/**`);
+    return rules;
+}
+async function ensureLocalSkillGitignoreRules(rootDir, lockfile) {
+    const desiredRules = new Set();
+    for (const dir of getLocalSkillDirs(rootDir, [
+        lockfile
+    ])){
+        const relativePath = toRepoRelativePath(rootDir, dir);
+        if (relativePath) for (const rule of createUnignoreRules(relativePath))desiredRules.add(rule);
+    }
+    if (0 === desiredRules.size) return;
+    const gitignorePath = node_path.join(rootDir, '.gitignore');
+    let existing = '';
+    try {
+        existing = await promises_readFile(gitignorePath, 'utf8');
+    } catch  {}
+    const existingRules = new Set(existing.split(/\r?\n/).map((line)=>line.trim()));
+    const missingRules = Array.from(desiredRules).filter((rule)=>!existingRules.has(rule));
+    if (0 === missingRules.length) return;
+    const prefix = existing && !existing.endsWith('\n') ? '\n' : '';
+    const separator = existing.trim() ? '\n' : '';
+    await writeFile(gitignorePath, `${existing}${prefix}${separator}# Keep local skills tracked\n${missingRules.join('\n')}\n`, 'utf8');
+}
 function resolveTargetPath(rootDir, targetPath) {
     return node_path.isAbsolute(targetPath) ? targetPath : node_path.join(rootDir, targetPath);
 }
@@ -1693,29 +1765,32 @@ async function isManagedSkillDir(dirPath) {
         return false;
     }
 }
-async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillNames) {
+async function pruneManagedSkills(rootDir, installDir, linkTargets, wantedSkillNames, protectedSkillDirs = []) {
     const wanted = new Set(wantedSkillNames);
     const absoluteInstallDir = node_path.join(rootDir, installDir);
+    const protectedDirs = new Set(protectedSkillDirs.map((dir)=>node_path.resolve(dir)));
     try {
         const entries = await promises_readdir(absoluteInstallDir);
         for (const entry of entries){
             if (entry.startsWith('.')) continue;
             const skillDir = node_path.join(absoluteInstallDir, entry);
-            if (await isManagedSkillDir(skillDir)) {
-                if (!wanted.has(entry)) {
-                    await rm(skillDir, {
-                        recursive: true,
-                        force: true
-                    });
-                    for (const linkTarget of linkTargets){
-                        const linkPath = node_path.join(resolveTargetPath(rootDir, linkTarget), entry);
-                        try {
-                            const stat = await promises_lstat(linkPath);
-                            if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await rm(linkPath, {
-                                recursive: true,
-                                force: true
-                            });
-                        } catch  {}
+            if (!protectedDirs.has(node_path.resolve(skillDir))) {
+                if (await isManagedSkillDir(skillDir)) {
+                    if (!wanted.has(entry)) {
+                        await rm(skillDir, {
+                            recursive: true,
+                            force: true
+                        });
+                        for (const linkTarget of linkTargets){
+                            const linkPath = node_path.join(resolveTargetPath(rootDir, linkTarget), entry);
+                            try {
+                                const stat = await promises_lstat(linkPath);
+                                if (stat.isSymbolicLink() || stat.isDirectory() || stat.isFile()) await rm(linkPath, {
+                                    recursive: true,
+                                    force: true
+                                });
+                            } catch  {}
+                        }
                     }
                 }
             }
@@ -1946,6 +2021,16 @@ async function fetchLinkSkill(rootDir, skillName, entry, installDir) {
     await symlink(sourceRoot, targetDir);
     return targetDir;
 }
+async function fetchLocalSkill(rootDir, entry) {
+    if ('local' !== entry.resolution.type) throw new Error('Expected local resolution');
+    const sourceRoot = node_path.resolve(rootDir, entry.resolution.path);
+    try {
+        await access(node_path.join(sourceRoot, 'SKILL.md'));
+    } catch  {
+        throw new Error(`Invalid local skill at ${sourceRoot}: missing SKILL.md`);
+    }
+    return sourceRoot;
+}
 const inFlightDownloads = new Map();
 async function fetchNpmSkill(rootDir, skillName, entry, installDir, _cache) {
     if ('npm' !== entry.resolution.type) throw new Error('Expected npm resolution');
@@ -1979,6 +2064,10 @@ async function fetchSkill(rootDir, skillName, entry, installDir, cache) {
             return {
                 installPath: await fetchLinkSkill(rootDir, skillName, entry, installDir)
             };
+        case 'local':
+            return {
+                installPath: await fetchLocalSkill(rootDir, entry)
+            };
         case 'file':
             return {
                 installPath: await fetchFileSkill(rootDir, skillName, entry, installDir)
@@ -2257,6 +2346,10 @@ function createTaskQueue(processor, options) {
 async function isSkillUpToDate(rootDir, installDir, skillName, entry) {
     const skillDir = node_path.join(rootDir, installDir, skillName);
     try {
+        if ('local' === entry.resolution.type) {
+            await access(node_path.join(node_path.resolve(rootDir, entry.resolution.path), 'SKILL.md'));
+            return true;
+        }
         const stats = await promises_lstat(skillDir);
         if ('link' === entry.resolution.type) {
             if (!stats.isSymbolicLink()) return false;
@@ -2285,7 +2378,7 @@ function createFetchTaskQueue(ctx, bus, options) {
             const result = {
                 skillName: task.skillName,
                 entry: task.entry,
-                installPath: node_path.join(ctx.cwd, installDir, task.skillName),
+                installPath: getSkillInstallPath(ctx.cwd, installDir, task.skillName, task.entry),
                 skipped: true
             };
             bus.emitFetched(result);
@@ -2311,8 +2404,8 @@ function createFetchTaskQueue(ctx, bus, options) {
 function links_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);
+async function linkSkill(rootDir, installDir, linkTarget, skillName, sourcePath) {
+    const absoluteTarget = sourcePath ?? node_path.join(rootDir, installDir, skillName);
     const absoluteLink = node_path.join(links_resolveTargetPath(rootDir, linkTarget), skillName);
     await ensureDir(node_path.dirname(absoluteLink));
     await replaceSymlink(absoluteTarget, absoluteLink);
@@ -2322,7 +2415,7 @@ function createLinkTaskQueue(ctx, bus, options) {
     const linkTargets = ctx.lockfile?.linkTargets ?? ctx.manifest.linkTargets ?? [];
     async function processor(task) {
         try {
-            for (const linkTarget of linkTargets)await linkSkill(ctx.cwd, installDir, linkTarget, task.skillName);
+            for (const linkTarget of linkTargets)await linkSkill(ctx.cwd, installDir, linkTarget, task.skillName, task.installPath);
             const result = {
                 skillName: task.skillName
             };
@@ -2451,7 +2544,17 @@ async function runPipeline(input) {
         linkTargets,
         skills: entries
     });
-    await pruneManagedSkills(ctx.cwd, installDir, linkTargets, skillNames);
+    const runtimeLockfile = {
+        lockfileVersion: '0.1',
+        installDir,
+        linkTargets,
+        skills: entries
+    };
+    await ensureLocalSkillGitignoreRules(ctx.cwd, runtimeLockfile);
+    await pruneManagedSkills(ctx.cwd, installDir, linkTargets, skillNames, getLocalSkillDirs(ctx.cwd, [
+        runtimeLockfile,
+        ctx.lockfile
+    ]));
     if (skipResolve) for (const [skillName, entry] of Object.entries(entries))bus.emitResolved({
         skillName,
         entry
@@ -2608,7 +2711,7 @@ function buildLinkSpecifier(sourceRoot, skillPath) {
     return normalizeLinkSource(`link:${absoluteSkillPath}`);
 }
 function isDirectSkillSpecifier(specifier) {
-    return specifier.startsWith('link:') || specifier.startsWith('file:') || specifier.startsWith('npm:') || specifier.includes('#path:') || specifier.includes('&path:');
+    return specifier.startsWith('link:') || specifier.startsWith('local:') || 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);
@@ -3505,6 +3608,13 @@ async function updateCommand(options) {
                 });
                 continue;
             }
+            if ('local' === normalized.type) {
+                result.skipped.push({
+                    name: skillName,
+                    reason: 'local-specifier'
+                });
+                continue;
+            }
             const { entry } = await resolveLockEntry(options.cwd, specifier);
             const nextEntry = await attachManifestPatchToEntry(options.cwd, ctx.manifest, skillName, entry);
             const previous = ctx.lockfile?.skills[skillName];
@@ -3644,7 +3754,10 @@ async function installSkills_withBundledSelfSkillLock(rootDir, manifest, lockfil
 async function fetchSkillsFromLock(rootDir, manifest, lockfile, options) {
     const installDir = manifest.installDir ?? '.agents/skills';
     const linkTargets = manifest.linkTargets ?? [];
-    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills));
+    await ensureLocalSkillGitignoreRules(rootDir, lockfile);
+    await pruneManagedSkills(rootDir, installDir, linkTargets, Object.keys(lockfile.skills), getLocalSkillDirs(rootDir, [
+        lockfile
+    ]));
     const lockDigest = sha256(JSON.stringify(lockfile));
     const state = await readInstallState(rootDir, installDir);
     if (state?.lockDigest === lockDigest && await installSkills_areManagedSkillsInstalled(rootDir, installDir, Object.keys(lockfile.skills))) return {
@@ -3680,7 +3793,7 @@ async function linkSkillsFromLock(rootDir, manifest, lockfile, options) {
     const installDir = manifest.installDir ?? '.agents/skills';
     const linkTargets = manifest.linkTargets ?? [];
     for (const skillName of Object.keys(lockfile.skills)){
-        for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName);
+        for (const linkTarget of linkTargets)await linkSkill(rootDir, installDir, linkTarget, skillName, getSkillInstallPath(rootDir, installDir, skillName, lockfile.skills[skillName]));
         options?.onProgress?.({
             type: 'installed',
             skillName

package/package.json

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

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

@@ -40,7 +40,7 @@ Use this skill for repositories that already use `skills-package-manager`, or wh
 
 4. `npx skills-package-manager update [skill...]`
    - Refreshes resolvable entries in `skills-lock.yaml`.
-   - Skips `link:` skills, including the bundled `skills-package-manager-cli` self skill.
+   - Skips local `link:` and `local:` skills, including the bundled `skills-package-manager-cli` self skill.
 
 ## How To Triage User Questions
 
@@ -59,6 +59,7 @@ Use this skill for repositories that already use `skills-package-manager`, or wh
 ## Specifier Reminders
 
 - `link:./path/to/skill-dir` points to a local skill directory.
+- `local:./path/to/existing-skill-dir` keeps an existing user-owned skill directory in place.
 - `file:./pkg.tgz#path:/skills/name` points to a packaged tarball plus skill path.
 - `npm:@scope/pkg#path:/skills/name` resolves a package from the configured registry.
 - GitHub shorthand or Git URLs resolve remote repositories and may need `--skill` when multiple skills are available.