feat: add local skill protocol (#32)

## Summary

- Add `local:` skill specifiers for existing user-owned skill
directories.
- Install `local:` skills in place without copying, replacing, patching,
or pruning their source directories.
- Link agent targets directly to the local source directory and maintain
`.gitignore` unignore rules for repo-local skills.
- Update tests, docs, and the bundled `skills-package-manager-cli`
guidance.

## Related Links

web-infra-dev/rsbuild#7565
<!-- Provide links to related issues, discussions, or design notes -->

## Checklist

<!-- Check and mark with an "x" -->

- [x] Tests updated (or not required).
- [x] Documentation updated (or not required).

Testing:

- `pnpm build`
- `pnpm test`
- `pnpm build:website`
- `pnpm check` (passes with existing warnings)

Author: SoonIter

packages/skills-package-manager/README.md

@@ -50,12 +50,13 @@ npx skills-package-manager add https://github.com/owner/repo/tree/main/skills/my
 # Direct specifier — skip discovery
 npx skills-package-manager add https://github.com/owner/repo.git#path:/skills/my-skill
 npx skills-package-manager add link:./local-source/skills/my-skill
+npx skills-package-manager add local:./.agents/skills/my-skill
 npx skills-package-manager add ./local-source
 npx skills-package-manager add file:./skills-package.tgz#path:/skills/my-skill
 npx skills-package-manager add npm:@scope/skills-package#path:/skills/my-skill
 ```
 
-After `npx skills-package-manager add`, the newly added skills are resolved, materialized into `installDir`, and linked to each configured `linkTarget` immediately.
+After `npx skills-package-manager add`, the newly added skills are resolved, installed or registered according to their protocol, and linked to each configured `linkTarget` immediately.
 
 #### How it works
 
@@ -104,9 +105,9 @@ Install all skills declared in `skills.json`:
 npx skills-package-manager install
 ```
 
-This resolves each skill from its specifier, materializes it into `installDir` (default `.agents/skills/`), and creates symlinks for each `linkTarget`.
+This resolves each skill from its specifier, installs managed skills into `installDir` (default `.agents/skills/`), registers `local:` skills in place, and creates symlinks for each `linkTarget`.
 When `selfSkill` is `true`, `npx skills-package-manager install` also installs the bundled `skills-package-manager-cli` skill so users get guidance for `skills.json`, `skills-lock.yaml`, and `npx skills-package-manager` commands. This helper skill is not written to `skills-lock.yaml`.
-If `patchedSkills` contains an entry for a skill, the corresponding patch file is applied after the skill is materialized.
+If `patchedSkills` contains an entry for a managed skill, the corresponding patch file is applied after the skill is materialized. `local:` skills cannot be patched because their source directories are user-owned.
 
 ### `npx skills-package-manager patch`
 
@@ -154,7 +155,7 @@ Behavior:
 
 - Uses `skills.json` as the source of truth
 - Re-resolves git refs and npm package targets
-- Skips `link:` skills, including the bundled self skill
+- Skips local `link:` and `local:` skills, including the bundled self skill
 - Fails immediately for unknown skill names
 - Writes `skills-lock.yaml` only after fetch and link succeed
 
@@ -183,11 +184,12 @@ const skills = await listRepoSkills('vercel-labs', 'skills')
 ```text
 git/file/npm: <source>#[ref&]path:<skill-path>
 link: link:<path-to-skill-dir>
+local: local:<path-to-existing-skill-dir>
 ```
 
 | Part | Description | Example |
 |------|-------------|---------|
-| `source` | Git URL, direct `link:` skill path, `file:` tarball, or `npm:` package name | `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `file:./skills.tgz`, `npm:@scope/pkg` |
+| `source` | Git URL, direct `link:` or `local:` skill path, `file:` tarball, or `npm:` package name | `https://github.com/o/r.git`, `link:./local/skills/my-skill`, `local:./.agents/skills/my-skill`, `file:./skills.tgz`, `npm:@scope/pkg` |
 | `ref` | Optional git ref | `main`, `v1.0.0`, `HEAD`, `6cb0992`, `6cb0992a176f2ca142e19f64dca8ac12025b035e` |
 | `path` | Path to skill directory within source | `/skills/my-skill` |
 
@@ -196,7 +198,8 @@ link: link:<path-to-skill-dir>
 ### Resolution Types
 
 - **`git`** — Clones the repo, resolves commit hash, copies skill files
-- **`link`** — Reads from a local directory and copies the selected skill
+- **`link`** — Symlinks a local skill directory into `installDir`
+- **`local`** — Uses an existing user-owned skill directory in place
 - **`file`** — Extracts a local `tgz` package and copies the selected skill
 - **`npm`** — Resolves a package from the configured npm registry, locks the tarball URL/version/integrity, and installs from the downloaded tarball
 

packages/skills-package-manager/skills/skills-package-manager-cli/SKILL.md

@@ -40,7 +40,7 @@ Use this skill for repositories that already use `skills-package-manager`, or wh
 
 4. `npx skills-package-manager update [skill...]`
    - Refreshes resolvable entries in `skills-lock.yaml`.
-   - Skips `link:` skills, including the bundled `skills-package-manager-cli` self skill.
+   - Skips local `link:` and `local:` skills, including the bundled `skills-package-manager-cli` self skill.
 
 ## How To Triage User Questions
 
@@ -59,6 +59,7 @@ Use this skill for repositories that already use `skills-package-manager`, or wh
 ## Specifier Reminders
 
 - `link:./path/to/skill-dir` points to a local skill directory.
+- `local:./path/to/existing-skill-dir` keeps an existing user-owned skill directory in place.
 - `file:./pkg.tgz#path:/skills/name` points to a packaged tarball plus skill path.
 - `npm:@scope/pkg#path:/skills/name` resolves a package from the configured registry.
 - GitHub shorthand or Git URLs resolve remote repositories and may need `--skill` when multiple skills are available.

packages/skills-package-manager/src/commands/add.ts

@@ -66,6 +66,7 @@ function buildLinkSpecifier(sourceRoot: string, skillPath: string): string {
 function isDirectSkillSpecifier(specifier: string): boolean {
   return (
     specifier.startsWith('link:') ||
+    specifier.startsWith('local:') ||
     specifier.startsWith('file:') ||
     specifier.startsWith('npm:') ||
     specifier.includes('#path:') ||

packages/skills-package-manager/src/commands/install.ts

@@ -83,8 +83,8 @@ export async function installCommand(options: InstallCommandOptions) {
     } else {
       // Normal mode: check install-dir lock copy for fast-path skip.
       // Only skip when there are no file: skills, because tarball contents
-      // may change without the lockfile being modified. link: skills use
-      // symlinks so they always reflect the current source.
+      // may change without the lockfile being modified. link: and local:
+      // skills always reflect the current source.
       const hasLocalSource = Object.values(ctx.manifest.skills).some((s) => s.startsWith('file:'))
       const installDirLock = await readInstallDirLock(options.cwd, installDir)
       if (

packages/skills-package-manager/src/commands/update.ts

@@ -70,6 +70,10 @@ export async function updateCommand(options: UpdateCommandOptions): Promise<Upda
         result.skipped.push({ name: skillName, reason: 'link-specifier' })
         continue
       }
+      if (normalized.type === 'local') {
+        result.skipped.push({ name: skillName, reason: 'local-specifier' })
+        continue
+      }
 
       const { entry } = await resolveLockEntry(options.cwd, specifier)
       const nextEntry = await attachManifestPatchToEntry(

packages/skills-package-manager/src/config/compareSkillsLock.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import type { ManifestStat } from '../pipeline/types'
-import { normalizeLinkSource } from '../specifiers/normalizeLinkSource'
+import { normalizeLinkSource, normalizeLocalSource } from '../specifiers/normalizeLinkSource'
 import { parseSpecifier } from '../specifiers/parseSpecifier'
 import { sha256File } from '../utils/hash'
 import { toPortableRelativePath } from '../utils/path'
@@ -15,10 +15,15 @@ interface ParsedSpecifier {
 function parseForComparison(specifier: string): ParsedSpecifier {
   const parsed = parseSpecifier(specifier)
   const isLink = parsed.sourcePart.startsWith('link:')
+  const isLocal = parsed.sourcePart.startsWith('local:')
   return {
-    sourcePart: isLink ? normalizeLinkSource(parsed.sourcePart) : parsed.sourcePart,
-    ref: isLink ? null : parsed.ref,
-    path: isLink ? '/' : parsed.path || '/',
+    sourcePart: isLink
+      ? normalizeLinkSource(parsed.sourcePart)
+      : isLocal
+        ? normalizeLocalSource(parsed.sourcePart)
+        : parsed.sourcePart,
+    ref: isLink || isLocal ? null : parsed.ref,
+    path: isLink || isLocal ? '/' : parsed.path || '/',
   }
 }
 

packages/skills-package-manager/src/config/syncSkillsLock.ts

@@ -48,6 +48,10 @@ export async function attachManifestPatchToEntry(
     return entry
   }
 
+  if (entry.resolution.type === 'local') {
+    throw new Error(`local: skill ${skillName} cannot be patched because its source is user-owned`)
+  }
+
   const absolutePatchPath = path.resolve(cwd, patchPath)
   return {
     ...entry,

packages/skills-package-manager/src/config/types.ts

@@ -25,7 +25,7 @@ export type NormalizedSkillsManifest = {
 }
 
 export type NormalizedSpecifier = {
-  type: 'git' | 'link' | 'file' | 'npm'
+  type: 'git' | 'link' | 'local' | 'file' | 'npm'
   source: string
   ref: string | null
   path: string
@@ -37,6 +37,7 @@ export type SkillsLockEntry = {
   specifier: string
   resolution:
     | { type: 'link'; path: string }
+    | { type: 'local'; path: string }
     | { type: 'file'; tarball: string; path: string }
     | { type: 'git'; url: string; commit: string; path: string }
     | {
@@ -111,7 +112,7 @@ export type UpdateCommandResult = {
   status: 'updated' | 'skipped' | 'failed'
   updated: string[]
   unchanged: string[]
-  skipped: Array<{ name: string; reason: 'link-specifier' }>
+  skipped: Array<{ name: string; reason: 'link-specifier' | 'local-specifier' }>
   failed: Array<{ name: string; reason: string }>
 }
 

packages/skills-package-manager/src/errors/index.ts

@@ -117,6 +117,7 @@ export function formatErrorForDisplay(error: unknown): string {
         output += `\n  - owner/repo (GitHub shorthand)`
         output += `\n  - https://github.com/owner/repo.git`
         output += `\n  - link:./path/to/skill-dir`
+        output += `\n  - local:./path/to/existing-skill-dir`
         output += `\n  - file:./path/to/skill-package.tgz#path:/skills/my-skill`
         output += `\n  - npm:@scope/skill-package#path:/skills/my-skill`
       }

packages/skills-package-manager/src/fetchers/index.ts

@@ -3,6 +3,7 @@ import type { CacheManager } from '../pipeline/types'
 import { fetchFileSkill } from './file'
 import { fetchGitSkill } from './git'
 import { fetchLinkSkill } from './link'
+import { fetchLocalSkill } from './local'
 import { fetchNpmSkill } from './npm'
 
 export async function fetchSkill(
@@ -15,6 +16,8 @@ export async function fetchSkill(
   switch (entry.resolution.type) {
     case 'link':
       return { installPath: await fetchLinkSkill(rootDir, skillName, entry, installDir) }
+    case 'local':
+      return { installPath: await fetchLocalSkill(rootDir, entry) }
     case 'file':
       return { installPath: await fetchFileSkill(rootDir, skillName, entry, installDir) }
     case 'git':