feat(core): split link, file, and npm skill protocols

[SoonIter]

Summary

This PR changes link: specifiers to point directly to a skill directory, adds packed install flows for local file: tarballs and npm: package sources, and updates lockfile resolution, install/update behavior, tests, and docs so the three protocols have distinct semantics.

Testing

• pnpm exec biome check --write packages/skills-package-manager/src/specifiers/normalizeSpecifier.ts packages/skills-package-manager/src/config/syncSkillsLock.ts packages/skills-package-manager/src/install/installSkills.ts packages/skills-package-manager/src/errors/index.ts packages/skills-package-manager/test/specifiers.test.ts packages/skills-package-manager/test/add.test.ts packages/skills-package-manager/test/install.test.ts packages/skills-package-manager/test/update.test.ts packages/pnpm-plugin-skills/test/index.test.ts packages/skills-package-manager/README.md website/docs/api/specifiers.mdx website/docs/architecture/manifest-and-lockfile.mdx website/docs/architecture/cli-commands.mdx
• pnpm dlx tsx <smoke script>
• Full pnpm test not run in this environment because Node is 20.13.1 and the repo toolchain requires Node 20.19+

Related Links

None

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	skills-package-manager	7796232	Commit Preview URL Branch Preview URL	Apr 08 2026, 08:25 PM

[Copilot]

Pull request overview

This PR refactors skill specifier semantics to support direct local link: skills (pointing at a skill directory) and adds “packed install” flows for file: tarballs and npm: sources, updating installer behavior, lockfile shape, tests, and documentation accordingly.

Changes:

• Introduce link: specifiers for direct local skill directories (no #path: fragment).
• Add install/update support for packed sources: file: .tgz and npm: package sources.
• Update docs and tests to reflect new specifier types and lockfile resolution records.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
website/docs/getting-started.mdx	Updates user guidance for updating git:/npm: skills.
website/docs/architecture/manifest-and-lockfile.mdx	Updates manifest/lockfile examples and describes new resolution types.
website/docs/architecture/how-it-works.mdx	Updates architecture overview to include link/file/npm flows.
website/docs/architecture/cli-commands.mdx	Updates CLI examples and spm update semantics.
website/docs/api/specifiers.mdx	Documents new specifier formats and resolution types.
website/docs/api/commands.mdx	Updates spm update description.
website/docs/_pnpm.mdx	Mirrors getting-started update guidance for pnpm docs.
packages/skills-package-manager/test/update.test.ts	Adds/updates update behavior tests for link, npm, and file tarballs.
packages/skills-package-manager/test/specifiers.test.ts	Adds parsing tests for link, file tarball, and npm specifiers.
packages/skills-package-manager/test/manifest.test.ts	Updates manifest IO expectations to use link:.
packages/skills-package-manager/test/install.test.ts	Adds install tests for link, packed file: tgz, and packed npm: sources.
packages/skills-package-manager/test/helpers.ts	Adds helper utilities to generate/pack test npm packages.
packages/skills-package-manager/test/github.test.ts	Updates protocol-specifier parsing expectations for link:.
packages/skills-package-manager/test/add.test.ts	Updates add flows for packed file tarballs, link:, and npm:.
packages/skills-package-manager/src/utils/hash.ts	Expands sha256 helper to accept Buffer-like inputs.
packages/skills-package-manager/src/specifiers/normalizeSpecifier.ts	Adds link: parsing/validation semantics.
packages/skills-package-manager/src/npm/packPackage.ts	Adds npm packing helper for npm: installs.
packages/skills-package-manager/src/install/materializePackedSkill.ts	Adds tarball extraction + materialization flow.
packages/skills-package-manager/src/install/installSkills.ts	Adds fetching/materialization for link, file tarball, and npm skills.
packages/skills-package-manager/src/errors/index.ts	Updates invalid-specifier help text to include new formats.
packages/skills-package-manager/src/config/types.ts	Extends lock entry types for link, packed file, and npm.
packages/skills-package-manager/src/config/syncSkillsLock.ts	Implements lock resolution for link, packed file, and npm.
packages/skills-package-manager/src/commands/update.ts	Updates update behavior to skip link and support packed file/npm.
packages/skills-package-manager/README.md	Updates README examples and protocol descriptions.
packages/pnpm-plugin-skills/test/index.test.ts	Updates plugin expectations to link: semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 5 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

Comments suppressed due to low confidence (1)

website/docs/api/commands.mdx:99

• The spm update description says “latest locked versions”, but update is the command that produces updated lock entries (new commits/versions/integrities). Wording it as “latest resolved versions” (or “update the lockfile to the latest resolvable versions”) would better match the actual behavior and avoid implying it just re-applies what’s already locked.

## `spm update`

Refresh the resolvable skills declared in the manifest to their latest locked versions, with the option to update only selected skills.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.