@anytio/pspm 0.7.3 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +374 -183
  3. package/dist/index.js +1193 -75
  4. package/dist/index.js.map +1 -1
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,22 +1,85 @@
1
1
  # PSPM - Prompt Skill Package Manager
2
2
 
3
- A CLI for managing prompt skills across AI coding agents.
3
+ The package manager for the open agent skills ecosystem.
4
4
 
5
- **Website:** [https://pspm.dev](https://pspm.dev)
5
+ Supports **Claude Code**, **Cursor**, **Codex**, **Gemini CLI**, **Windsurf**, and [30+ more agents](#supported-agents).
6
6
 
7
- ## What is PSPM?
7
+ **Website:** [pspm.dev](https://pspm.dev)
8
8
 
9
- PSPM (Prompt Skill Package Manager) is a package manager for prompt skills - small, discoverable capabilities packaged as `SKILL.md` files. Think of it as npm for AI agent skills.
9
+ ## Install a Skill
10
10
 
11
- Skills are designed to work with any AI coding agent that supports the SKILL.md format, including Claude Code, Cursor, Windsurf, and others.
11
+ ```bash
12
+ npx @anytio/pspm add vercel-labs/agent-skills
13
+ ```
14
+
15
+ ### Source Formats
16
+
17
+ ```bash
18
+ # GitHub shorthand (owner/repo)
19
+ pspm add vercel-labs/agent-skills
20
+
21
+ # Full GitHub URL
22
+ pspm add https://github.com/vercel-labs/agent-skills
23
+
24
+ # Direct path to a skill in a repo
25
+ pspm add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design
26
+
27
+ # GitHub with prefix (explicit format)
28
+ pspm add github:owner/repo
29
+ pspm add github:owner/repo/path/to/skill@v1.0.0
30
+
31
+ # Registry (with semver versioning)
32
+ pspm add @user/username/skill-name
33
+ pspm add @user/username/skill-name@^2.0.0
34
+
35
+ # Well-known URL (RFC 8615 discovery)
36
+ pspm add https://acme.com
37
+
38
+ # Local path (for development)
39
+ pspm add ./my-local-skills
40
+ pspm add ../shared-skills
41
+ pspm add file:../my-local-skills
42
+ ```
43
+
44
+ ### Options
45
+
46
+ | Option | Description |
47
+ |--------|-------------|
48
+ | `-g, --global` | Install to user home directory instead of project |
49
+ | `--agent <agents>` | Comma-separated agents for symlinks (e.g., `claude-code,cursor`) |
50
+ | `-y, --yes` | Skip agent selection prompt and use defaults |
51
+
52
+ ### Examples
53
+
54
+ ```bash
55
+ # Add multiple skills at once
56
+ pspm add @user/alice/skill1 @user/bob/skill2
57
+
58
+ # Add from GitHub URL (copy-paste from browser)
59
+ pspm add https://github.com/vercel-labs/agent-skills/tree/main/skills/web-design
60
+
61
+ # Add from GitHub shorthand
62
+ pspm add vercel-labs/agent-skills/skills/web-design
12
63
 
13
- ## Why PSPM?
64
+ # Install to specific agents only
65
+ pspm add @user/alice/my-skill --agent claude-code,cursor
14
66
 
15
- **Easy Sharing** - Share your prompt skills with teammates or the community. Publish to the registry and let others install with a single command.
67
+ # Install globally (available across all projects)
68
+ pspm add vercel-labs/agent-skills -g
16
69
 
17
- **Version Control** - Full semver support just like npm. Pin exact versions, use ranges (`^1.0.0`, `~1.2.0`), or reference GitHub tags directly. Lock versions with `pspm-lock.json` for reproducible installations.
70
+ # Skip prompts (CI-friendly)
71
+ pspm add @user/alice/my-skill -y --agent claude-code
18
72
 
19
- **Public & Private Skills** - Keep proprietary skills private within your organization, or publish them publicly for anyone to use. Private skills require authentication to download.
73
+ # Add from well-known endpoint
74
+ pspm add https://acme.com
75
+ ```
76
+
77
+ ### Installation Scope
78
+
79
+ | Scope | Flag | Skills Location | Symlink Location |
80
+ |-------|------|-----------------|------------------|
81
+ | **Project** | (default) | `.pspm/skills/` | `./<agent>/skills/` |
82
+ | **Global** | `-g` | `~/.pspm/skills/` | `~/<agent>/skills/` |
20
83
 
21
84
  ## Installation
22
85
 
@@ -24,7 +87,7 @@ Skills are designed to work with any AI coding agent that supports the SKILL.md
24
87
  npm install -g @anytio/pspm
25
88
  ```
26
89
 
27
- Or use with npx:
90
+ Or use with npx (no install needed):
28
91
 
29
92
  ```bash
30
93
  npx @anytio/pspm <command>
@@ -33,9 +96,6 @@ npx @anytio/pspm <command>
33
96
  ## Quick Start
34
97
 
35
98
  ```bash
36
- # Login with your API key
37
- pspm login
38
-
39
99
  # Initialize a new skill project
40
100
  pspm init
41
101
 
@@ -54,264 +114,395 @@ pspm install
54
114
 
55
115
  ## Commands
56
116
 
57
- ### Authentication
117
+ | Command | Description |
118
+ |---------|-------------|
119
+ | `pspm add <specifiers...>` | Add skills from registry, GitHub, local paths, or well-known URLs |
120
+ | `pspm install [specifiers...]` | Install from lockfile, or add specific packages (alias: `i`) |
121
+ | `pspm remove <name>` | Remove an installed skill (alias: `rm`) |
122
+ | `pspm list` | List installed skills (alias: `ls`) |
123
+ | `pspm update` | Update skills to latest compatible versions |
124
+ | `pspm outdated [packages...]` | Check for outdated skills |
125
+ | `pspm search [query]` | Search and discover skills from the registry (alias: `find`) |
126
+ | `pspm audit` | Verify integrity of installed skills |
127
+ | `pspm link` | Recreate agent symlinks without reinstalling |
128
+ | `pspm init` | Create pspm.json manifest |
129
+ | `pspm publish` | Publish skill to registry |
130
+ | `pspm login` | Authenticate via browser or API key |
131
+ | `pspm upgrade` | Update pspm itself to the latest version |
132
+
133
+ ### `pspm install`
134
+
135
+ Install all skills from the lockfile, or add and install specific packages.
58
136
 
59
137
  ```bash
60
- pspm login --api-key <key> # Authenticate with API key
61
- pspm login # Authenticate via browser
62
- pspm logout # Clear stored credentials
63
- pspm whoami # Show current user info
138
+ # Install all from lockfile
139
+ pspm install
140
+
141
+ # Install with frozen lockfile (CI/CD - fails if lockfile is outdated)
142
+ pspm install --frozen-lockfile
143
+
144
+ # Install to a custom directory
145
+ pspm install --dir ./custom-path
146
+
147
+ # Install specific packages
148
+ pspm install @user/alice/skill1 github:org/repo
64
149
  ```
65
150
 
66
- ### Project Initialization
151
+ ### `pspm search`
152
+
153
+ Search and discover skills from the registry.
67
154
 
68
155
  ```bash
69
- pspm init # Create pspm.json manifest (interactive)
70
- pspm init -y # Create pspm.json with defaults
71
- pspm migrate # Migrate from old directory structure
156
+ # Search by keyword
157
+ pspm search typescript
158
+
159
+ # Output as JSON
160
+ pspm search react --json
161
+
162
+ # Sort by recent or name
163
+ pspm search --sort recent --limit 10
72
164
  ```
73
165
 
74
- ### Skill Management
166
+ ### `pspm audit`
167
+
168
+ Verify integrity of installed skills and check for issues.
75
169
 
76
170
  ```bash
77
- pspm add <specifiers...> # Add and install one or more skills
78
- pspm remove <name> # Remove an installed skill (alias: rm)
79
- pspm list # List installed skills (alias: ls)
80
- pspm install [specifiers...] # Install from lockfile, or add specific packages (alias: i)
81
- pspm link # Recreate agent symlinks without reinstalling
82
- pspm update # Update skills to latest compatible versions
83
- pspm outdated # Check for outdated packages
171
+ # Run audit
172
+ pspm audit
173
+
174
+ # Output as JSON (for CI)
175
+ pspm audit --json
84
176
  ```
85
177
 
86
- **Multiple package support (like npm):**
178
+ Checks for: missing packages, deprecated versions, corrupted installations (missing SKILL.md).
179
+
180
+ ### `pspm list`
181
+
87
182
  ```bash
88
- pspm add @user/alice/skill1 @user/bob/skill2 # Add multiple packages
89
- pspm install @user/alice/skill1 github:org/repo # Install specific packages
90
- pspm install # Install all from lockfile
183
+ # List all installed skills
184
+ pspm list
185
+
186
+ # Output as JSON
187
+ pspm list --json
91
188
  ```
92
189
 
93
- **Registry specifier formats:**
94
- - `@user/username/skillname` - Latest version
95
- - `@user/username/skillname@2.0.0` - Specific version
96
- - `@user/username/skillname@^2.0.0` - Semver range
190
+ ### `pspm outdated`
191
+
192
+ ```bash
193
+ # Check for outdated skills
194
+ pspm outdated
195
+
196
+ # Include up-to-date packages
197
+ pspm outdated --all
97
198
 
98
- **GitHub specifier formats:**
99
- - `github:owner/repo` - Entire repository (default branch)
100
- - `github:owner/repo@main` - Entire repository (specific branch/tag)
101
- - `github:owner/repo/path/to/skill` - Subdirectory within repo
102
- - `github:owner/repo/path/to/skill@v1.0.0` - Subdirectory with tag
199
+ # Check specific packages
200
+ pspm outdated @user/alice/skill1
103
201
 
104
- **Local directory specifiers (for development):**
105
- - `file:../path/to/skill` - Install from local directory
106
- - `file:./subdir/skill` - Relative path from current directory
202
+ # Output as JSON
203
+ pspm outdated --json
204
+ ```
205
+
206
+ ### `pspm update`
107
207
 
108
- **Agent symlink options:**
109
208
  ```bash
110
- pspm add <specifier> --agent claude-code,cursor # Link to multiple agents
111
- pspm install --agent none # Skip symlink creation
112
- pspm link --agent codex # Recreate symlinks for specific agent
209
+ # Update all skills to latest compatible versions
210
+ pspm update
211
+
212
+ # Preview what would change
213
+ pspm update --dry-run
113
214
  ```
114
215
 
115
- Default is all agents (`claude-code`, `codex`, `cursor`, `gemini`, `kiro`, `opencode`). Use `--agent claude-code` to install for a single agent.
216
+ ## Source Formats
116
217
 
117
- ### Versioning
218
+ ### Registry Specifiers
219
+
220
+ PSPM has a built-in registry with full semver support, just like npm.
118
221
 
119
222
  ```bash
120
- pspm version major # Bump major version (1.0.0 → 2.0.0)
121
- pspm version minor # Bump minor version (1.0.0 → 1.1.0)
122
- pspm version patch # Bump patch version (1.0.0 → 1.0.1)
123
- pspm version patch --dry-run # Preview changes without writing
223
+ @user/username/skillname # Latest version
224
+ @user/username/skillname@2.0.0 # Exact version
225
+ @user/username/skillname@^2.0.0 # Compatible range (>=2.0.0 <3.0.0)
226
+ @user/username/skillname@~2.1.0 # Patch range (>=2.1.0 <2.2.0)
124
227
  ```
125
228
 
126
- ### Publishing
229
+ ### GitHub Specifiers
230
+
231
+ All of these formats are supported:
127
232
 
128
233
  ```bash
129
- pspm publish --access private # Publish as private (requires Pro)
130
- pspm publish --access public # Publish as public (irreversible)
131
- pspm publish --access private --bump patch # Bump version and publish
132
- pspm unpublish <spec> --force # Remove a published skill version
133
- pspm deprecate <spec> [msg] # Mark a version as deprecated
234
+ # Shorthand (most common)
235
+ owner/repo # Entire repo (default branch)
236
+ owner/repo/path/to/skill # Subdirectory within repo
237
+
238
+ # Full GitHub URL (copy-paste from browser)
239
+ https://github.com/owner/repo
240
+ https://github.com/owner/repo/tree/main/path/to/skill
241
+
242
+ # Explicit prefix (with version/ref support)
243
+ github:owner/repo # Entire repo (default branch)
244
+ github:owner/repo@main # Specific branch or tag
245
+ github:owner/repo/path/to/skill # Subdirectory within repo
246
+ github:owner/repo/path/to/skill@v1.0.0 # Subdirectory with tag
134
247
  ```
135
248
 
136
- **`--access` is required.** You must specify `--access public` or `--access private` every time you publish. Private skills require a Pro subscription.
249
+ ### Local Specifiers
137
250
 
138
- **Publish preview:** Before uploading, `pspm publish` shows a preview of included files, package size, and requires confirmation. Max package size is **10MB**.
251
+ ```bash
252
+ ./my-local-skills # Relative path (no prefix needed)
253
+ ../shared-skills # Parent directory
254
+ file:../path/to/skill # Explicit file: prefix (also supported)
255
+ ```
139
256
 
257
+ ### Well-Known URLs
140
258
 
141
- ### Visibility
259
+ Any HTTPS URL serving a `/.well-known/skills/index.json` endpoint. See [Well-Known Skills Discovery](../../docs/well-known-skills-discovery.md).
142
260
 
143
261
  ```bash
144
- pspm access --public # Make current package public
145
- pspm access <spec> --public # Make specific package public
262
+ https://acme.com # Discovers skills at acme.com/.well-known/skills/
146
263
  ```
147
264
 
148
- **Note:** Making a package public is irreversible (like npm). Public packages cannot be made private again.
265
+ ## Agent Symlinks
149
266
 
150
- ### Configuration
267
+ PSPM installs skills to a central `.pspm/skills/` directory and creates symlinks in each agent's expected location.
151
268
 
152
269
  ```bash
153
- pspm config show # Show resolved configuration
154
- pspm config init # Create .pspmrc in current directory
155
- ```
270
+ # Install for specific agents
271
+ pspm add <specifier> --agent claude-code,cursor
156
272
 
157
- ## Configuration
273
+ # Skip symlink creation
274
+ pspm install --agent none
158
275
 
159
- PSPM uses a simple npm-like INI configuration format.
276
+ # Recreate symlinks for a specific agent
277
+ pspm link --agent codex
160
278
 
161
- ### User Config (`~/.pspmrc`)
279
+ # Interactive agent selection (default without -y)
280
+ pspm add <specifier>
281
+ ```
162
282
 
163
- ```ini
164
- ; PSPM Configuration
165
- registry = https://registry.pspm.dev
166
- authToken = sk_...
167
- username = myuser
283
+ ## Supported Agents
284
+
285
+ | Agent | `--agent` value | Skills Directory |
286
+ |-------|----------------|------------------|
287
+ | AdaL | `adal` | `.adal/skills/` |
288
+ | Amp | `amp` | `.agents/skills/` |
289
+ | Antigravity | `antigravity` | `.agent/skills/` |
290
+ | Augment | `augment` | `.augment/skills/` |
291
+ | Claude Code | `claude-code` | `.claude/skills/` |
292
+ | Cline | `cline` | `.agents/skills/` |
293
+ | CodeBuddy | `codebuddy` | `.codebuddy/skills/` |
294
+ | Codex | `codex` | `.agents/skills/` |
295
+ | Command Code | `command-code` | `.commandcode/skills/` |
296
+ | Continue | `continue` | `.continue/skills/` |
297
+ | Cortex Code | `cortex` | `.cortex/skills/` |
298
+ | Crush | `crush` | `.crush/skills/` |
299
+ | Cursor | `cursor` | `.agents/skills/` |
300
+ | Droid | `droid` | `.factory/skills/` |
301
+ | Gemini CLI | `gemini-cli` | `.agents/skills/` |
302
+ | GitHub Copilot | `github-copilot` | `.agents/skills/` |
303
+ | Goose | `goose` | `.goose/skills/` |
304
+ | iFlow CLI | `iflow-cli` | `.iflow/skills/` |
305
+ | Junie | `junie` | `.junie/skills/` |
306
+ | Kilo Code | `kilo` | `.kilocode/skills/` |
307
+ | Kimi Code CLI | `kimi-cli` | `.agents/skills/` |
308
+ | Kiro CLI | `kiro-cli` | `.kiro/skills/` |
309
+ | Kode | `kode` | `.kode/skills/` |
310
+ | MCPJam | `mcpjam` | `.mcpjam/skills/` |
311
+ | Mistral Vibe | `mistral-vibe` | `.vibe/skills/` |
312
+ | Mux | `mux` | `.mux/skills/` |
313
+ | Neovate | `neovate` | `.neovate/skills/` |
314
+ | OpenClaw | `openclaw` | `skills/` |
315
+ | OpenCode | `opencode` | `.agents/skills/` |
316
+ | OpenHands | `openhands` | `.openhands/skills/` |
317
+ | Pi | `pi` | `.pi/skills/` |
318
+ | Pochi | `pochi` | `.pochi/skills/` |
319
+ | Qoder | `qoder` | `.qoder/skills/` |
320
+ | Qwen Code | `qwen-code` | `.qwen/skills/` |
321
+ | Replit | `replit` | `.agents/skills/` |
322
+ | Roo Code | `roo` | `.roo/skills/` |
323
+ | Trae | `trae` | `.trae/skills/` |
324
+ | Trae CN | `trae-cn` | `.trae/skills/` |
325
+ | Universal | `universal` | `.agents/skills/` |
326
+ | Windsurf | `windsurf` | `.windsurf/skills/` |
327
+ | Zencoder | `zencoder` | `.zencoder/skills/` |
328
+
329
+ ## Publishing Skills
330
+
331
+ ### Authentication
332
+
333
+ ```bash
334
+ pspm login # Authenticate via browser
335
+ pspm login --api-key <key> # Authenticate with API key
336
+ pspm logout # Clear stored credentials
337
+ pspm whoami # Show current user info
168
338
  ```
169
339
 
170
- ### Project Config (`.pspmrc`)
340
+ ### Versioning
171
341
 
172
- Project-specific configuration (optional):
342
+ ```bash
343
+ pspm version major # 1.0.0 -> 2.0.0
344
+ pspm version minor # 1.0.0 -> 1.1.0
345
+ pspm version patch # 1.0.0 -> 1.0.1
346
+ pspm version patch --dry-run # Preview without writing
347
+ ```
173
348
 
174
- ```ini
175
- ; Project-specific PSPM configuration
176
- registry = https://custom-registry.example.com
349
+ ### Publishing
350
+
351
+ ```bash
352
+ pspm publish --access public # Publish as public (irreversible)
353
+ pspm publish --access private # Publish as private (requires Pro)
354
+ pspm publish --access private --bump patch # Bump and publish
177
355
  ```
178
356
 
179
- ### Lockfile (`pspm-lock.json`)
357
+ `--access` is required. Before uploading, `pspm publish` shows a preview of included files and package size. Max package size is **10MB**.
180
358
 
181
- ```json
182
- {
183
- "lockfileVersion": 4,
184
- "registryUrl": "https://registry.pspm.dev",
185
- "packages": {
186
- "@user/username/skillname": {
187
- "version": "1.0.0",
188
- "resolved": "https://registry.pspm.dev/@user/username/skillname/1.0.0",
189
- "integrity": "sha256-..."
190
- }
191
- },
192
- "githubPackages": {
193
- "github:owner/repo/path": {
194
- "version": "abc1234",
195
- "resolved": "https://github.com/owner/repo",
196
- "integrity": "sha256-...",
197
- "gitCommit": "abc1234567890...",
198
- "gitRef": "main"
199
- }
200
- },
201
- "localPackages": {
202
- "file:../my-local-skill": {
203
- "version": "local",
204
- "path": "../my-local-skill",
205
- "resolvedPath": "/absolute/path/to/my-local-skill",
206
- "name": "my-local-skill"
207
- }
208
- }
209
- }
359
+ ### Managing Published Skills
360
+
361
+ ```bash
362
+ pspm unpublish <spec> --force # Remove a version (within 72 hours)
363
+ pspm deprecate <spec> [message] # Mark as deprecated
364
+ pspm deprecate <spec> --undo # Remove deprecation
365
+ pspm access --public # Make package public (irreversible)
366
+ pspm access <spec> --private # Make package private
210
367
  ```
211
368
 
212
- ## Environment Variables
369
+ ## Creating a Skill
213
370
 
214
- | Variable | Description |
215
- |----------|-------------|
216
- | `PSPM_API_KEY` | Override API key |
217
- | `PSPM_DEBUG` | Enable debug logging |
218
- | `GITHUB_TOKEN` | GitHub token for private repos and higher rate limits |
371
+ A skill is a directory containing at minimum a `SKILL.md`:
219
372
 
220
- ## Directory Structure
373
+ ```markdown
374
+ ---
375
+ name: my-skill
376
+ description: A helpful skill that does X
377
+ ---
378
+
379
+ # My Skill
380
+
381
+ Instructions for the agent to follow when this skill is activated.
382
+
383
+ ## When to Use
384
+
385
+ Describe when this skill applies.
221
386
 
387
+ ## Steps
388
+
389
+ 1. First, do this
390
+ 2. Then, do that
222
391
  ```
223
- project/
224
- ├── .pspmrc # Project config (optional)
225
- ├── pspm.json # Manifest with dependencies
226
- ├── pspm-lock.json # Lockfile
227
- ├── .pspm/
228
- │ ├── skills/ # Installed skills
229
- │ │ ├── username/ # Registry skills
230
- │ │ │ └── skillname/
231
- │ │ │ └── SKILL.md
232
- │ │ ├── _github/ # GitHub skills
233
- │ │ │ └── owner/
234
- │ │ │ └── repo/
235
- │ │ │ └── path/
236
- │ │ │ └── SKILL.md
237
- │ │ └── _local/ # Local skill symlinks
238
- │ │ └── skillname -> ../../../path/to/local/skill
239
- │ └── cache/ # Tarball cache
240
- ├── .claude/
241
- │ └── skills/ # Symlinks for claude-code agent
242
- │ ├── skillname -> ../../.pspm/skills/username/skillname
243
- │ └── repo -> ../../.pspm/skills/_github/owner/repo
244
- └── .cursor/
245
- └── skills/ # Symlinks for cursor agent (if configured)
246
-
247
- ~/
248
- └── .pspmrc # User config
392
+
393
+ For publishing to the registry, also include `pspm.json` (created with `pspm init`):
394
+
395
+ ```json
396
+ {
397
+ "name": "@user/myusername/my-skill",
398
+ "version": "1.0.0",
399
+ "description": "A helpful skill for...",
400
+ "files": ["pspm.json", "SKILL.md"]
401
+ }
249
402
  ```
250
403
 
251
404
  ## Ignoring Files (.pspmignore)
252
405
 
253
- Control which files are excluded when publishing with a `.pspmignore` file:
406
+ Control which files are excluded when publishing:
254
407
 
255
408
  ```
256
- # .pspmignore - exclude files from publish
409
+ # .pspmignore
257
410
  *.test.ts
258
411
  __tests__/
259
412
  .env*
260
413
  *.log
261
414
  ```
262
415
 
263
- **Behavior:**
264
416
  - If `.pspmignore` exists, use it for ignore patterns
265
417
  - Otherwise, fall back to `.gitignore` if present
266
- - Always ignores `node_modules`, `.git`, and `.pspm-publish` regardless
418
+ - Always ignores `node_modules`, `.git`, and `.pspm-publish`
267
419
 
268
- ## Creating a Skill
420
+ ## Directory Structure
421
+
422
+ ```
423
+ project/
424
+ +-- pspm.json # Manifest with dependencies
425
+ +-- pspm-lock.json # Lockfile (version pinning + integrity)
426
+ +-- .pspmrc # Project config (optional)
427
+ +-- .pspm/
428
+ | +-- skills/ # Installed skills (central store)
429
+ | | +-- username/ # Registry skills
430
+ | | | +-- skillname/
431
+ | | | +-- SKILL.md
432
+ | | +-- _github/ # GitHub skills
433
+ | | | +-- owner/
434
+ | | | +-- repo/
435
+ | | +-- _wellknown/ # Well-known skills
436
+ | | | +-- acme.com/
437
+ | | | +-- skill-name/
438
+ | | +-- _local/ # Local skill symlinks
439
+ | +-- cache/ # Tarball cache
440
+ +-- .claude/
441
+ | +-- skills/ # Symlinks for Claude Code
442
+ +-- .cursor/
443
+ +-- skills/ # Symlinks for Cursor (if configured)
444
+ ```
445
+
446
+ ## CI/CD Integration
447
+
448
+ ```bash
449
+ # Set API key via environment variable
450
+ export PSPM_API_KEY=sk_ci_key
269
451
 
270
- A skill is a directory containing at minimum a `pspm.json` and `SKILL.md`:
452
+ # Install with frozen lockfile (fails if lockfile is outdated)
453
+ pspm install --frozen-lockfile
271
454
 
455
+ # Audit installed skills
456
+ pspm audit --json
272
457
  ```
273
- my-skill/
274
- ├── pspm.json # Required: name, version
275
- ├── SKILL.md # Required: skill instructions
276
- ├── runtime/ # Optional: runtime files
277
- ├── scripts/ # Optional: scripts
278
- └── data/ # Optional: data files
458
+
459
+ ## Configuration
460
+
461
+ ### User Config (`~/.pspmrc`)
462
+
463
+ ```ini
464
+ registry = https://registry.pspm.dev
465
+ authToken = sk_...
466
+ username = myuser
467
+ ```
468
+
469
+ ### Project Config (`.pspmrc`)
470
+
471
+ ```ini
472
+ registry = https://custom-registry.example.com
279
473
  ```
280
474
 
281
- **pspm.json** (created with `pspm init`):
475
+ ### Lockfile (`pspm-lock.json`)
476
+
477
+ Tracks exact versions, resolved URLs, and integrity hashes for reproducible installs:
478
+
282
479
  ```json
283
480
  {
284
- "name": "@user/myusername/my-skill",
285
- "version": "1.0.0",
286
- "description": "A helpful skill for...",
287
- "files": ["pspm.json", "SKILL.md", "runtime", "scripts", "data"]
481
+ "lockfileVersion": 5,
482
+ "registryUrl": "https://registry.pspm.dev",
483
+ "packages": { ... },
484
+ "githubPackages": { ... },
485
+ "localPackages": { ... },
486
+ "wellKnownPackages": { ... }
288
487
  }
289
488
  ```
290
489
 
291
- **SKILL.md:**
292
- ```markdown
293
- ---
294
- name: my-skill
295
- description: A helpful skill that does X
296
- ---
297
-
298
- # Instructions
490
+ ## Environment Variables
299
491
 
300
- When activated, this skill helps you...
301
- ```
492
+ | Variable | Description |
493
+ |----------|-------------|
494
+ | `PSPM_API_KEY` | Override API key for authentication |
495
+ | `PSPM_DEBUG` | Enable debug logging |
496
+ | `GITHUB_TOKEN` | GitHub token for private repos and higher rate limits |
302
497
 
303
- ## CI/CD Integration
498
+ ## Self-Update
304
499
 
305
500
  ```bash
306
- # Use environment variable for authentication
307
- export PSPM_API_KEY=sk_ci_key
308
-
309
- # Install with frozen lockfile (fails if lockfile is outdated)
310
- pspm install --frozen-lockfile
501
+ pspm upgrade
311
502
  ```
312
503
 
504
+ Auto-detects your package manager (pnpm, npm, yarn, bun). The CLI also checks for updates every 24 hours and notifies you when a newer version is available.
505
+
313
506
  ## License
314
507
 
315
508
  This project is licensed under [The Artistic License 2.0](LICENSE), the same license used by npm.
316
-
317
- <!-- @doc-sync: 17484e41aef17ad72e470bb5511876ce0bdfcbb4 | 2026-02-20 15:00 -->