skills-package-manager 0.8.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

@@ -64,6 +64,7 @@ export declare enum ErrorCode {
     MANIFEST_VALIDATION_ERROR = "EMANIFESTVAL",
     NETWORK_ERROR = "ENETWORK",
     REPO_NOT_FOUND = "EREPONOTFOUND",
+    INSTALL_ERROR = "EINSTALL",
     UNKNOWN_ERROR = "EUNKNOWN",
     NOT_IMPLEMENTED = "ENOTIMPL",
     VALIDATION_ERROR = "EVALIDATION",
@@ -82,7 +83,7 @@ export declare function fetchSkillsFromLock(rootDir: string, manifest: SkillsMan
 } | {
     readonly status: "fetched";
     readonly fetched: string[];
-    readonly reason?: undefined;
+    reason?: undefined;
 }>;
 
 /**
@@ -144,13 +145,19 @@ declare type InitPromptResult = {
 };
 
 export declare function installCommand(options: InstallCommandOptions): Promise<{
-    readonly status: "installed";
-    readonly installed: string[];
+    status: "skipped";
+    reason: string;
+    installed?: undefined;
+} | {
+    status: "installed";
+    installed: string[];
+    reason?: undefined;
 }>;
 
 export declare type InstallCommandOptions = {
     cwd: string;
     frozenLockfile?: boolean;
+    onProgress?: InstallProgressListener;
 };
 
 declare type InstallPhase = 'resolving' | 'fetching' | 'linking' | 'finalizing' | 'done';
@@ -158,6 +165,12 @@ declare type InstallPhase = 'resolving' | 'fetching' | 'linking' | 'finalizing'
 export declare type InstallProgressEvent = {
     type: 'resolved';
     skillName: string;
+} | {
+    type: 'reused';
+    skillName: string;
+} | {
+    type: 'downloaded';
+    skillName: string;
 } | {
     type: 'added';
     skillName: string;
@@ -182,18 +195,20 @@ export declare function installSkills(rootDir: string, options?: {
 }): Promise<{
     readonly status: "skipped";
     readonly reason: "manifest-missing";
-    readonly installed?: undefined;
+    installed?: undefined;
 } | {
     readonly status: "installed";
     readonly installed: string[];
-    readonly reason?: undefined;
+    reason?: undefined;
 }>;
 
 export declare const installStageHooks: {
     beforeFetch: (_rootDir: string, _manifest: SkillsManifest, _lockfile: SkillsLock) => Promise<void>;
 };
 
-export declare function isLockInSync(rootDir: string, manifest: NormalizedSkillsManifest, lock: SkillsLock | null): Promise<boolean>;
+export declare function isLockInSync(rootDir: string, manifest: NormalizedSkillsManifest, lock: SkillsLock | null, manifestStat?: ManifestStat | null, installState?: {
+    manifestStat?: ManifestStat;
+} | null): Promise<boolean>;
 
 /**
  * Checks if an error is a known SPM error
@@ -226,6 +241,11 @@ export declare class ManifestError extends SpmError {
     });
 }
 
+declare interface ManifestStat {
+    mtimeMs: number;
+    size: number;
+}
+
 /**
  * Error thrown when network operations fail
  */
@@ -253,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;
@@ -376,6 +396,9 @@ export declare type SkillsLockEntry = {
     resolution: {
         type: 'link';
         path: string;
+    } | {
+        type: 'local';
+        path: string;
     } | {
         type: 'file';
         tarball: string;
@@ -451,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;
@@ -459,6 +482,8 @@ export declare type UpdateCommandResult = {
     }>;
 };
 
+export declare function withBundledSelfSkillLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock): Promise<SkillsLock>;
+
 export declare function writeSkillsLock(rootDir: string, lockfile: SkillsLock): Promise<void>;
 
 export declare function writeSkillsManifest(rootDir: string, manifest: SkillsManifest): Promise<void>;