skills-package-manager 0.1.1 → 0.3.0

package/README.md

@@ -1,26 +1,41 @@
-# skills-pm
+# spm
 
 Core library and CLI for managing agent skills.
 
 ## CLI Usage
 
-### `skills add`
+```bash
+spm --help
+spm --version
+spm add <specifier> [--skill <name>]
+spm install
+spm update [skill...]
+spm init [--yes]
+```
+
+- `spm` with no command shows top-level help
+- `spm --help` prints top-level help
+- `spm --version` prints the package version
+
+### `spm add`
 
 Add skills to your project.
 
 ```bash
 # Interactive — clone repo, discover skills, select via multiselect prompt
-skills add owner/repo
-skills add https://github.com/owner/repo
+spm add owner/repo
+spm add https://github.com/owner/repo
 
 # Non-interactive — add a specific skill by name
-skills add owner/repo --skill find-skills
+spm add owner/repo --skill find-skills
 
 # Direct specifier — skip discovery
-skills add https://github.com/owner/repo.git#path:/skills/my-skill
-skills add file:./local-source#path:/skills/my-skill
+spm add https://github.com/owner/repo.git#path:/skills/my-skill
+spm add file:./local-source#path:/skills/my-skill
 ```
 
+After `spm add`, the newly added skills are resolved, materialized into `installDir`, and linked to each configured `linkTarget` immediately.
+
 #### How it works
 
 When given `owner/repo` or a GitHub URL:
@@ -31,20 +46,65 @@ 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
 
-### `skills install`
+### `spm init`
+
+Create a new `skills.json` manifest in the current directory.
+
+```bash
+# Interactive — prompt for installDir and linkTargets
+spm init
+
+# Non-interactive — write the default manifest immediately
+spm init --yes
+```
+
+Behavior:
+
+- `spm init` prompts for `installDir` and `linkTargets`, then writes `skills.json`
+- `spm 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`:
+
+```json
+{
+  "installDir": ".agents/skills",
+  "linkTargets": [],
+  "skills": {}
+}
+```
+
+### `spm install`
 
 Install all skills declared in `skills.json`:
 
 ```bash
-skills install
+spm install
 ```
 
 This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
 
+### `spm update`
+
+Refresh git-based skills declared in `skills.json` without changing the manifest:
+
+```bash
+spm update
+spm update find-skills rspress-custom-theme
+```
+
+Behavior:
+
+- Uses `skills.json` as the source of truth
+- Re-resolves git refs to the latest commit
+- Skips `file:` skills
+- Fails immediately for unknown skill names
+- Writes `skills-lock.yaml` only after fetch and link succeed
+
 ## Programmatic API
 
 ```typescript
-import { addCommand, installCommand, listRepoSkills } from 'skills-pm'
+import { addCommand, installCommand, listRepoSkills } from 'skills-package-manager'
 
 // Add a skill
 await addCommand({
@@ -70,9 +130,11 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 | Part | Description | Example |
 |------|-------------|---------|
 | `source` | Git URL or `file:` path | `https://github.com/o/r.git`, `file:./local` |
-| `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD` |
+| `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD`, `6cb0992`, `6cb0992a176f2ca142e19f64dca8ac12025b035e` |
 | `path` | Path to skill directory within source | `/skills/my-skill` |
 
+`ref` can point to a branch, tag, full commit SHA, or short commit SHA.
+
 ### Resolution Types
 
 - **`git`** — Clones the repo, resolves commit hash, copies skill files
@@ -82,7 +144,7 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 
 ```
 src/
-├── bin/           # CLI entry points (skills-pm, skills)
+├── bin/           # CLI entry points (spm, skills)
 ├── cli/           # CLI runner and interactive prompts
 ├── commands/      # add, install command implementations
 ├── config/        # skills.json / skills-lock.yaml read/write
@@ -103,3 +165,4 @@ pnpm build    # Builds with Rslib (ESM output + DTS)
 ```bash
 pnpm test     # Runs tests with Rstest
 ```
+``

package/bin/skills-package-manager.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { formatErrorForDisplay, getExitCode, isSpmError, runCli } from '../dist/index.js'
+
+runCli(process.argv).catch((error) => {
+  if (isSpmError(error)) {
+    console.error(formatErrorForDisplay(error))
+    process.exit(getExitCode(error))
+  }
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})

package/bin/spm.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { formatErrorForDisplay, getExitCode, isSpmError, runCli } from '../dist/index.js'
+
+runCli(process.argv).catch((error) => {
+  if (isSpmError(error)) {
+    console.error(formatErrorForDisplay(error))
+    process.exit(getExitCode(error))
+  }
+  console.error(error instanceof Error ? error.message : error)
+  process.exit(1)
+})