@anytio/pspm 0.8.0 → 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 +33 -0
  2. package/README.md +370 -187
  3. package/dist/index.js +1033 -69
  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
12
34
 
13
- ## Why PSPM?
35
+ # Well-known URL (RFC 8615 discovery)
36
+ pspm add https://acme.com
14
37
 
15
- **Easy Sharing** - Share your prompt skills with teammates or the community. Publish to the registry and let others install with a single command.
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
16
63
 
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.
64
+ # Install to specific agents only
65
+ pspm add @user/alice/my-skill --agent claude-code,cursor
18
66
 
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.
67
+ # Install globally (available across all projects)
68
+ pspm add vercel-labs/agent-skills -g
69
+
70
+ # Skip prompts (CI-friendly)
71
+ pspm add @user/alice/my-skill -y --agent claude-code
72
+
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,272 +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`
97
191
 
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
192
+ ```bash
193
+ # Check for outdated skills
194
+ pspm outdated
195
+
196
+ # Include up-to-date packages
197
+ pspm outdated --all
198
+
199
+ # Check specific packages
200
+ pspm outdated @user/alice/skill1
201
+
202
+ # Output as JSON
203
+ pspm outdated --json
204
+ ```
103
205
 
104
- **Local directory specifiers (for development):**
105
- - `file:../path/to/skill` - Install from local directory
106
- - `file:./subdir/skill` - Relative path from current directory
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
270
+ # Install for specific agents
271
+ pspm add <specifier> --agent claude-code,cursor
272
+
273
+ # Skip symlink creation
274
+ pspm install --agent none
275
+
276
+ # Recreate symlinks for a specific agent
277
+ pspm link --agent codex
278
+
279
+ # Interactive agent selection (default without -y)
280
+ pspm add <specifier>
155
281
  ```
156
282
 
157
- ### Self-Update
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
158
332
 
159
333
  ```bash
160
- pspm upgrade # Update pspm to the latest version
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
161
338
  ```
162
339
 
163
- Automatically detects your package manager (pnpm, npm, yarn, bun). The CLI also checks for updates in the background every 24 hours and notifies you when a newer version is available.
164
-
165
- ## Configuration
340
+ ### Versioning
166
341
 
167
- PSPM uses a simple npm-like INI configuration format.
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
+ ```
168
348
 
169
- ### User Config (`~/.pspmrc`)
349
+ ### Publishing
170
350
 
171
- ```ini
172
- ; PSPM Configuration
173
- registry = https://registry.pspm.dev
174
- authToken = sk_...
175
- username = myuser
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
176
355
  ```
177
356
 
178
- ### Project Config (`.pspmrc`)
357
+ `--access` is required. Before uploading, `pspm publish` shows a preview of included files and package size. Max package size is **10MB**.
179
358
 
180
- Project-specific configuration (optional):
359
+ ### Managing Published Skills
181
360
 
182
- ```ini
183
- ; Project-specific PSPM configuration
184
- registry = https://custom-registry.example.com
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
185
367
  ```
186
368
 
187
- ### Lockfile (`pspm-lock.json`)
369
+ ## Creating a Skill
188
370
 
189
- ```json
190
- {
191
- "lockfileVersion": 4,
192
- "registryUrl": "https://registry.pspm.dev",
193
- "packages": {
194
- "@user/username/skillname": {
195
- "version": "1.0.0",
196
- "resolved": "https://registry.pspm.dev/@user/username/skillname/1.0.0",
197
- "integrity": "sha256-..."
198
- }
199
- },
200
- "githubPackages": {
201
- "github:owner/repo/path": {
202
- "version": "abc1234",
203
- "resolved": "https://github.com/owner/repo",
204
- "integrity": "sha256-...",
205
- "gitCommit": "abc1234567890...",
206
- "gitRef": "main"
207
- }
208
- },
209
- "localPackages": {
210
- "file:../my-local-skill": {
211
- "version": "local",
212
- "path": "../my-local-skill",
213
- "resolvedPath": "/absolute/path/to/my-local-skill",
214
- "name": "my-local-skill"
215
- }
216
- }
217
- }
218
- ```
371
+ A skill is a directory containing at minimum a `SKILL.md`:
219
372
 
220
- ## Environment Variables
373
+ ```markdown
374
+ ---
375
+ name: my-skill
376
+ description: A helpful skill that does X
377
+ ---
221
378
 
222
- | Variable | Description |
223
- |----------|-------------|
224
- | `PSPM_API_KEY` | Override API key |
225
- | `PSPM_DEBUG` | Enable debug logging |
226
- | `GITHUB_TOKEN` | GitHub token for private repos and higher rate limits |
379
+ # My Skill
227
380
 
228
- ## Directory Structure
381
+ Instructions for the agent to follow when this skill is activated.
382
+
383
+ ## When to Use
384
+
385
+ Describe when this skill applies.
386
+
387
+ ## Steps
229
388
 
389
+ 1. First, do this
390
+ 2. Then, do that
230
391
  ```
231
- project/
232
- ├── .pspmrc # Project config (optional)
233
- ├── pspm.json # Manifest with dependencies
234
- ├── pspm-lock.json # Lockfile
235
- ├── .pspm/
236
- │ ├── skills/ # Installed skills
237
- │ │ ├── username/ # Registry skills
238
- │ │ │ └── skillname/
239
- │ │ │ └── SKILL.md
240
- │ │ ├── _github/ # GitHub skills
241
- │ │ │ └── owner/
242
- │ │ │ └── repo/
243
- │ │ │ └── path/
244
- │ │ │ └── SKILL.md
245
- │ │ └── _local/ # Local skill symlinks
246
- │ │ └── skillname -> ../../../path/to/local/skill
247
- │ └── cache/ # Tarball cache
248
- ├── .claude/
249
- │ └── skills/ # Symlinks for claude-code agent
250
- │ ├── skillname -> ../../.pspm/skills/username/skillname
251
- │ └── repo -> ../../.pspm/skills/_github/owner/repo
252
- └── .cursor/
253
- └── skills/ # Symlinks for cursor agent (if configured)
254
-
255
- ~/
256
- └── .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
+ }
257
402
  ```
258
403
 
259
404
  ## Ignoring Files (.pspmignore)
260
405
 
261
- Control which files are excluded when publishing with a `.pspmignore` file:
406
+ Control which files are excluded when publishing:
262
407
 
263
408
  ```
264
- # .pspmignore - exclude files from publish
409
+ # .pspmignore
265
410
  *.test.ts
266
411
  __tests__/
267
412
  .env*
268
413
  *.log
269
414
  ```
270
415
 
271
- **Behavior:**
272
416
  - If `.pspmignore` exists, use it for ignore patterns
273
417
  - Otherwise, fall back to `.gitignore` if present
274
- - Always ignores `node_modules`, `.git`, and `.pspm-publish` regardless
418
+ - Always ignores `node_modules`, `.git`, and `.pspm-publish`
275
419
 
276
- ## 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
451
+
452
+ # Install with frozen lockfile (fails if lockfile is outdated)
453
+ pspm install --frozen-lockfile
454
+
455
+ # Audit installed skills
456
+ pspm audit --json
457
+ ```
277
458
 
278
- A skill is a directory containing at minimum a `pspm.json` and `SKILL.md`:
459
+ ## Configuration
279
460
 
461
+ ### User Config (`~/.pspmrc`)
462
+
463
+ ```ini
464
+ registry = https://registry.pspm.dev
465
+ authToken = sk_...
466
+ username = myuser
280
467
  ```
281
- my-skill/
282
- ├── pspm.json # Required: name, version
283
- ├── SKILL.md # Required: skill instructions
284
- ├── runtime/ # Optional: runtime files
285
- ├── scripts/ # Optional: scripts
286
- └── data/ # Optional: data files
468
+
469
+ ### Project Config (`.pspmrc`)
470
+
471
+ ```ini
472
+ registry = https://custom-registry.example.com
287
473
  ```
288
474
 
289
- **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
+
290
479
  ```json
291
480
  {
292
- "name": "@user/myusername/my-skill",
293
- "version": "1.0.0",
294
- "description": "A helpful skill for...",
295
- "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": { ... }
296
487
  }
297
488
  ```
298
489
 
299
- **SKILL.md:**
300
- ```markdown
301
- ---
302
- name: my-skill
303
- description: A helpful skill that does X
304
- ---
305
-
306
- # Instructions
490
+ ## Environment Variables
307
491
 
308
- When activated, this skill helps you...
309
- ```
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 |
310
497
 
311
- ## CI/CD Integration
498
+ ## Self-Update
312
499
 
313
500
  ```bash
314
- # Use environment variable for authentication
315
- export PSPM_API_KEY=sk_ci_key
316
-
317
- # Install with frozen lockfile (fails if lockfile is outdated)
318
- pspm install --frozen-lockfile
501
+ pspm upgrade
319
502
  ```
320
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
+
321
506
  ## License
322
507
 
323
508
  This project is licensed under [The Artistic License 2.0](LICENSE), the same license used by npm.
324
-
325
- <!-- @doc-sync: 17484e41aef17ad72e470bb5511876ce0bdfcbb4 | 2026-02-20 15:00 -->