#How it works

The installation flow is built around a unified pipeline with three concurrent task queues: resolve, fetch, and link. spm install resolves skills.json into an in-memory install plan, streams that plan through the pipeline, and records only lightweight install state for fast repeat installs.

#1. Load configuration

The pipeline starts by loading:

• skills.json
• .npmrc npm registry config
• .skills-pm-install-state.json from installDir, when present

#2. Resolve specifiers

The resolver turns manifest specifiers into install-plan entries:

• github: and git URL sources resolve to a concrete commit
• npm: sources resolve to package metadata and tarball details
• file: tarballs resolve to a local package path and skill subpath
• link: and local: sources resolve to local directories

#3. Fetch into installDir

Resolved skills are fetched into installDir. The npm fetcher uses a persistent tarball cache to avoid redundant downloads.

#4. Link to target directories

Fetched skills flow into the link queue, which creates symlinks from installDir to each linkTarget directory.

#5. Prune old skills

Before fetch begins, managed skills that are no longer declared in skills.json are removed from installDir and linkTargets.

#Pipeline architecture

#Design goals

• Declarative: skills.json is the single source of truth.
• Pinned: Git commits and npm versions live directly in skills.json.
• Linkable: One install can serve many agent directories.
• Updatable: spm update selectively refreshes git and npm pins.
• Concurrent: Pipeline parallelism minimizes install time.