skills-package-manager 0.9.0 → 0.11.0

package/README.md

@@ -9,7 +9,7 @@ For one-off usage, `npx skills-package-manager add ...` is the low-friction migr
 ```bash
 npx skills-package-manager --help
 npx skills-package-manager --version
-npx skills-package-manager add <specifier> [--skill <name>]
+npx skills-package-manager add <specifier> [--skill <name>...]
 npx skills-package-manager install
 npx skills-package-manager patch <skill>
 npx skills-package-manager patch-commit <edit-dir>
@@ -37,25 +37,37 @@ npx skills-package-manager add owner/repo
 # Interactive — clone repo, discover skills, select via multiselect prompt
 npx skills-package-manager add owner/repo
 npx skills-package-manager add https://github.com/owner/repo
+npx skills-package-manager add https://gitlab.com/org/repo
+npx skills-package-manager add git@github.com:owner/repo.git
+npx skills-package-manager add ./my-local-skills
 
-# Non-interactive — add a specific skill by name
+# Non-interactive — add one or more specific skills by name
 npx skills-package-manager add owner/repo --skill find-skills
+npx skills-package-manager add owner/repo -s frontend-design -s skill-creator
 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
+npx skills-package-manager add https://github.com/owner/repo/tree/main/skills/my-skill
+
+# Inspect or target agents with skills CLI-compatible flags
+npx skills-package-manager add owner/repo --list
+npx skills-package-manager add owner/repo --all
+npx skills-package-manager add owner/repo -a claude-code -a opencode
 
 # Direct specifier — skip discovery
-npx skills-package-manager add https://github.com/owner/repo.git#path:/skills/my-skill
+npx skills-package-manager add 'github:owner/repo#abc1234&path:/skills/my-skill'
 npx skills-package-manager add link:./local-source/skills/my-skill
+npx skills-package-manager add 'local:*' --skill 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
+npx skills-package-manager add 'file:./skills-package.tgz&path:/skills/my-skill'
+npx skills-package-manager add 'npm:@scope/skills-package@1.0.0&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.
+GitHub sources are written back to `skills.json` as pinned `github:owner/repo#<commit>&path:<path>` specifiers.
+The `--copy` flag is accepted for `npx skills add` command-line compatibility; SPM still keeps one canonical install directory and links configured agent targets from there.
 
 #### How it works
 
@@ -64,7 +76,7 @@ When given `owner/repo` or a GitHub URL:
 1. Shallow-clones the repository into a temp directory
 2. Scans for `SKILL.md` files (checks root, then `skills/`, `.agents/skills/`, etc.)
 3. Presents an interactive multiselect prompt (powered by [@clack/prompts](https://github.com/bombshell-dev/clack))
-4. Writes selected skills to `skills.json` and resolves `skills-lock.yaml`
+4. Writes selected, pinned skill specifiers to `skills.json`
 5. Cleans up the temp directory
 
 ### `npx skills-package-manager init`
@@ -104,9 +116,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`.
-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.
+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` and `npx skills-package-manager` commands. This helper skill is injected at install time and is not written to `skills.json`.
+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`
 
@@ -119,7 +131,7 @@ npx skills-package-manager patch hello-skill --edit-dir ./tmp/hello-skill
 
 Behavior:
 
-- Resolves the currently locked content for the target skill
+- Resolves the current manifest content for the target skill
 - Extracts an editable copy into a temporary directory by default
 - Reapplies any committed patch for that skill unless `--ignore-existing` is passed
 - Writes patch edit metadata so `patch-commit` can generate a new patch file later
@@ -138,12 +150,11 @@ Behavior:
 - Compares the edited directory with the original resolved skill content
 - Writes a unified diff patch file to `patches/<skill>.patch` by default
 - Updates `skills.json` through the `patchedSkills` field
-- Updates `skills-lock.yaml` with patch path and digest metadata
 - Reinstalls and relinks the patched skill so the working tree reflects the committed patch
 
 ### `npx skills-package-manager update`
 
-Refresh resolvable skills declared in `skills.json` without changing the manifest:
+Refresh resolvable skills declared in `skills.json` and write the updated pins back to the manifest:
 
 ```bash
 npx skills-package-manager update
@@ -153,10 +164,10 @@ npx skills-package-manager update find-skills rspress-custom-theme
 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
+- Updates git skills to the latest `main` commit and npm skills to the registry `latest` version
+- Skips local `link:`, `local:`, and `file:` skills
 - Fails immediately for unknown skill names
-- Writes `skills-lock.yaml` only after fetch and link succeed
+- Writes `skills.json` only after the updated install succeeds
 
 ## Programmatic API
 
@@ -181,13 +192,15 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 ## Specifier Format
 
 ```text
-git/file/npm: <source>#[ref&]path:<skill-path>
+git/file/npm: <source>[#ref][&path:<skill-path>]
 link: link:<path-to-skill-dir>
+local: local:<path-to-existing-skill-dir>
+local shorthand: local:*
 ```
 
 | 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 or `github:` shorthand, direct `link:` or `local:` skill path, `file:` tarball, or `npm:` package name | `github:o/r`, `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `local:*`, `file:./skills.tgz`, `npm:@scope/pkg@1.0.0` |
 | `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD`, `6cb0992`, `6cb0992a176f2ca142e19f64dca8ac12025b035e` |
 | `path` | Path to skill directory within source | `/skills/my-skill` |
 
@@ -196,9 +209,10 @@ 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
+- **`npm`** — Resolves a package from the configured npm registry and installs from the downloaded tarball
 
 `npm:` reads `registry` and scoped `@scope:registry` values from `.npmrc`. Matching `:_authToken`, `:_auth`, or `username` + `:_password` entries are also used for private registry requests.
 
@@ -209,7 +223,7 @@ src/
 ├── bin/           # CLI entry points
 ├── cli/           # CLI runner and interactive prompts
 ├── commands/      # add, install, patch command implementations
-├── config/        # skills.json / skills-lock.yaml read/write
+├── config/        # skills.json read/write and in-memory install plan resolution
 ├── github/        # Git clone + skill discovery (listSkills)
 ├── install/       # Skill materialization, linking, pruning
 ├── patches/       # Patch edit state, diff generation, patch application
@@ -228,4 +242,3 @@ pnpm build    # Builds with Rslib (ESM output + DTS)
 ```bash
 pnpm test     # Runs tests with Rstest
 ```
-``

package/dist/index.d.ts

@@ -4,15 +4,21 @@ export declare function addCommand(options: AddCommandOptions): Promise<{
 } | {
     skillName: string;
     specifier: string;
-}[]>;
+}[] | {
+    status: "listed";
+    skills: SkillInfo[];
+}>;
 
 export declare type AddCommandOptions = {
     cwd: string;
     specifier: string;
-    skill?: string;
+    skill?: string | string[];
     global?: boolean;
     yes?: boolean;
     agent?: string[];
+    list?: boolean;
+    copy?: boolean;
+    all?: boolean;
 };
 
 /**
@@ -58,8 +64,6 @@ export declare enum ErrorCode {
     YAML_PARSE_ERROR = "EYAMLPARSE",
     INVALID_SPECIFIER = "EINVALIDSPEC",
     MANIFEST_NOT_FOUND = "EMANIFEST",
-    LOCKFILE_NOT_FOUND = "ELOCKFILE",
-    LOCKFILE_OUTDATED = "ELOCKOUTDATED",
     MANIFEST_EXISTS = "EMANIFESTEXISTS",
     MANIFEST_VALIDATION_ERROR = "EMANIFESTVAL",
     NETWORK_ERROR = "ENETWORK",
@@ -74,18 +78,6 @@ export declare enum ErrorCode {
 
 export declare function expandSkillsManifest(_rootDir: string, manifest: SkillsManifest): Promise<NormalizedSkillsManifest>;
 
-export declare function fetchSkillsFromLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock, options?: {
-    onProgress?: InstallProgressListener;
-}): Promise<{
-    readonly status: "skipped";
-    readonly reason: "up-to-date";
-    readonly fetched?: undefined;
-} | {
-    readonly status: "fetched";
-    readonly fetched: string[];
-    reason?: undefined;
-}>;
-
 /**
  * Error thrown when file system operations fail
  */
@@ -156,7 +148,6 @@ export declare function installCommand(options: InstallCommandOptions): Promise<
 
 export declare type InstallCommandOptions = {
     cwd: string;
-    frozenLockfile?: boolean;
     onProgress?: InstallProgressListener;
 };
 
@@ -190,38 +181,26 @@ declare type InstallProgressReporter = {
 };
 
 export declare function installSkills(rootDir: string, options?: {
-    frozenLockfile?: boolean;
     onProgress?: InstallProgressListener;
 }): Promise<{
-    readonly status: "skipped";
-    readonly reason: "manifest-missing";
+    status: "skipped";
+    reason: string;
     installed?: undefined;
 } | {
-    readonly status: "installed";
-    readonly installed: string[];
+    status: "installed";
+    installed: string[];
     reason?: undefined;
 }>;
 
 export declare const installStageHooks: {
-    beforeFetch: (_rootDir: string, _manifest: SkillsManifest, _lockfile: SkillsLock) => Promise<void>;
+    beforeFetch: (_rootDir: string, _manifest: SkillsManifest, _plan: ResolvedSkillsPlan) => Promise<void>;
 };
 
-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
  */
 export declare function isSpmError(error: unknown): error is SpmError;
 
-export declare function linkSkillsFromLock(rootDir: string, manifest: SkillsManifest, lockfile: SkillsLock, options?: {
-    onProgress?: InstallProgressListener;
-}): Promise<{
-    readonly status: "linked";
-    readonly linked: string[];
-}>;
-
 /**
  * List skills in a GitHub repo by cloning and scanning.
  * This avoids GitHub API rate limits.
@@ -229,23 +208,18 @@ export declare function linkSkillsFromLock(rootDir: string, manifest: SkillsMani
 export declare function listRepoSkills(owner: string, repo: string, ref?: string): Promise<SkillInfo[]>;
 
 /**
- * Error thrown when manifest or lockfile operations fail
+ * Error thrown when manifest operations fail
  */
 export declare class ManifestError extends SpmError {
     readonly filePath: string;
     constructor(options: {
-        code: ErrorCode.MANIFEST_NOT_FOUND | ErrorCode.LOCKFILE_NOT_FOUND | ErrorCode.LOCKFILE_OUTDATED | ErrorCode.MANIFEST_EXISTS | ErrorCode.MANIFEST_VALIDATION_ERROR;
+        code: ErrorCode.MANIFEST_NOT_FOUND | ErrorCode.MANIFEST_EXISTS | ErrorCode.MANIFEST_VALIDATION_ERROR;
         filePath: string;
         message?: string;
         cause?: Error;
     });
 }
 
-declare interface ManifestStat {
-    mtimeMs: number;
-    size: number;
-}
-
 /**
  * Error thrown when network operations fail
  */
@@ -273,7 +247,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;
@@ -283,7 +257,12 @@ export declare type NormalizedSpecifier = {
 
 export declare function normalizeSkillsManifest(manifest: Partial<SkillsManifest>): NormalizedSkillsManifest;
 
-export declare function normalizeSpecifier(specifier: string): NormalizedSpecifier;
+export declare function normalizeSpecifier(specifier: string, options?: NormalizeSpecifierOptions): NormalizedSpecifier;
+
+declare type NormalizeSpecifierOptions = {
+    installDir?: string;
+    skillName?: string;
+};
 
 /**
  * Error thrown when parsing fails (JSON, YAML, specifiers)
@@ -352,50 +331,16 @@ declare type ProgressReporterOptions = {
     info?: (text: string) => void;
 };
 
-export declare function readSkillsLock(rootDir: string): Promise<SkillsLock | null>;
-
 export declare function readSkillsManifest(rootDir: string): Promise<NormalizedSkillsManifest | null>;
 
-export declare function resolveLockEntry(cwd: string, specifier: string, skillName?: string): Promise<{
-    skillName: string;
-    entry: SkillsLockEntry;
-}>;
-
-export declare function runCli(argv: string[], context?: {
-    cwd?: string;
-}): Promise<unknown>;
-
-/**
- * Error thrown when a skill operation fails
- */
-export declare class SkillError extends SpmError {
-    readonly skillName: string;
-    constructor(options: {
-        code: ErrorCode.SKILL_NOT_FOUND | ErrorCode.SKILL_EXISTS | ErrorCode.VALIDATION_ERROR;
-        skillName: string;
-        message?: string;
-        cause?: Error;
-    });
-}
-
-export declare type SkillInfo = {
-    name: string;
-    description: string;
-    path: string;
-};
-
-export declare type SkillsLock = {
-    lockfileVersion: '0.1';
-    installDir: string;
-    linkTargets: string[];
-    skills: Record<string, SkillsLockEntry>;
-};
-
-export declare type SkillsLockEntry = {
+export declare type ResolvedSkillEntry = {
     specifier: string;
     resolution: {
         type: 'link';
         path: string;
+    } | {
+        type: 'local';
+        path: string;
     } | {
         type: 'file';
         tarball: string;
@@ -421,6 +366,46 @@ export declare type SkillsLockEntry = {
     };
 };
 
+export declare type ResolvedSkillsPlan = {
+    installDir: string;
+    linkTargets: string[];
+    skills: Record<string, ResolvedSkillEntry>;
+};
+
+export declare function resolveSkillEntry(cwd: string, specifier: string, skillName?: string, options?: {
+    installDir?: string;
+}): Promise<{
+    skillName: string;
+    entry: ResolvedSkillEntry;
+}>;
+
+export declare function resolveSkillsPlan(cwd: string, manifest: NormalizedSkillsManifest, options?: {
+    onProgress?: InstallProgressListener;
+}): Promise<ResolvedSkillsPlan>;
+
+export declare function runCli(argv: string[], context?: {
+    cwd?: string;
+}): Promise<unknown>;
+
+/**
+ * Error thrown when a skill operation fails
+ */
+export declare class SkillError extends SpmError {
+    readonly skillName: string;
+    constructor(options: {
+        code: ErrorCode.SKILL_NOT_FOUND | ErrorCode.SKILL_EXISTS | ErrorCode.VALIDATION_ERROR;
+        skillName: string;
+        message?: string;
+        cause?: Error;
+    });
+}
+
+export declare type SkillInfo = {
+    name: string;
+    description: string;
+    path: string;
+};
+
 /**
  * Skills manifest input type used for authoring/writing manifests.
  * This preserves optionality for fields with defaults.
@@ -471,7 +456,7 @@ export declare type UpdateCommandResult = {
     unchanged: string[];
     skipped: Array<{
         name: string;
-        reason: 'link-specifier';
+        reason: 'link-specifier' | 'local-specifier' | 'file-specifier';
     }>;
     failed: Array<{
         name: string;
@@ -479,10 +464,6 @@ 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>;
 
 export { }