@vibe-forge/workspace-assets 3.2.1 → 3.2.2-alpha.0

package/__tests__/adapter-asset-plan.spec.ts

@@ -280,64 +280,6 @@ describe('buildAdapterAssetPlan', () => {
     ]))
   })
 
-  it('keeps explicit skills CLI dependencies ahead of preselected home-bridged skills in overlays', async () => {
-    const workspace = await createWorkspace()
-    const realHome = process.env.__VF_PROJECT_REAL_HOME__
-    const tempInstallDir = join(workspace, '.tmp-install-skills-cli-foo')
-    const installedSkillDir = join(tempInstallDir, '.agents', 'skills', 'foo')
-    await writeDocument(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: foo\ndescription: Registry foo\n---\nUse the registry definition.\n'
-    )
-    skillsCliMocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: tempInstallDir,
-      installedSkill: {
-        dirName: 'foo',
-        name: 'foo',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(realHome!, '.agents/skills/foo/SKILL.md'),
-      '---\ndescription: Home foo\n---\nUse the home definition.\n'
-    )
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - anthropics/skills@foo',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-    const plan = await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['foo', 'app-builder']
-        }
-      }
-    })
-
-    const fooOverlays = plan.overlays.filter(entry => entry.kind === 'skill' && entry.targetPath === 'skills/foo')
-    expect(fooOverlays).toHaveLength(1)
-    expect(fooOverlays[0]?.sourcePath).toContain(
-      '/.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/foo'
-    )
-    expect(fooOverlays[0]?.sourcePath).not.toBe(join(realHome!, '.agents/skills/foo'))
-  })
-
   it('prunes excluded skill dependency subtrees from selected native overlays', async () => {
     const workspace = await createWorkspace()
 

package/__tests__/bundle.spec.ts

@@ -386,79 +386,6 @@ describe('resolveWorkspaceAssetBundle', () => {
     }))
   })
 
-  it('installs selected missing skill dependencies from the skills CLI cache', async () => {
-    const workspace = await createWorkspace()
-    const realHome = process.env.__VF_PROJECT_REAL_HOME__
-    const tempInstallDir = join(workspace, '.tmp-install-skills-cli')
-    const installedSkillDir = join(tempInstallDir, '.agents', 'skills', 'frontend-design')
-    await writeDocument(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse strong visual hierarchy.\n'
-    )
-    skillsCliMocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: tempInstallDir,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(realHome!, '.agents/skills/frontend-design/SKILL.md'),
-      '---\ndescription: home frontend design\n---\nUse the home definition.'
-    )
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - anthropics/skills@frontend-design',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
-    expect(bundle.skills.find(asset => asset.name === 'frontend-design')).toEqual(expect.objectContaining({
-      resolvedBy: 'home-bridge',
-      sourcePath: join(realHome!, '.agents/skills/frontend-design/SKILL.md')
-    }))
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    const dependency = bundle.skills.find(asset => asset.name === 'frontend-design')
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
-    expect(dependency?.sourcePath).toContain(
-      '/.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/frontend-design/'
-    )
-    expect(bundle.skills.find(asset => (
-      asset.name === 'frontend-design' && asset.resolvedBy === 'home-bridge'
-    ))).toBeUndefined()
-    expect(skillsCliMocks.findSkillsCli).not.toHaveBeenCalled()
-    expect(skillsCliMocks.installSkillsCliSkillToTemp).toHaveBeenCalledWith({
-      config: undefined,
-      skill: 'frontend-design',
-      source: 'anthropics/skills'
-    })
-  })
-
   it('installs configured project skills before bundle resolution and rewrites renamed skill names', async () => {
     const workspace = await createWorkspace()
     const tempInstallDir = join(workspace, '.tmp-configured-install')
@@ -564,171 +491,6 @@ describe('resolveWorkspaceAssetBundle', () => {
     )
   })
 
-  it('installs skill dependencies into the primary workspace shared cache', async () => {
-    const primary = await createWorkspace()
-    const worktree = await createWorkspace()
-    const previousPrimaryWorkspace = process.env.__VF_PROJECT_PRIMARY_WORKSPACE_FOLDER__
-    const tempInstallDir = join(worktree, '.tmp-install-skills-cli')
-    const installedSkillDir = join(tempInstallDir, '.agents', 'skills', 'frontend-design')
-    await writeDocument(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse primary cache.\n'
-    )
-    skillsCliMocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: tempInstallDir,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    try {
-      process.env.__VF_PROJECT_PRIMARY_WORKSPACE_FOLDER__ = primary
-      await writeDocument(
-        join(worktree, '.ai/skills/app-builder/SKILL.md'),
-        [
-          '---',
-          'name: app-builder',
-          'description: Build apps',
-          'dependencies:',
-          '  - anthropics/skills@frontend-design',
-          '---',
-          'Build the app.'
-        ].join('\n')
-      )
-
-      const bundle = await resolveWorkspaceAssetBundle({
-        cwd: worktree,
-        configs: [undefined, undefined],
-        useDefaultVibeForgeMcpServer: false
-      })
-
-      await buildAdapterAssetPlan({
-        adapter: 'opencode',
-        bundle,
-        options: {
-          skills: {
-            include: ['app-builder']
-          }
-        }
-      })
-
-      const dependency = bundle.skills.find(asset => asset.name === 'frontend-design')
-      expect(dependency?.sourcePath).toContain(join(
-        primary,
-        '.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/frontend-design/'
-      ))
-      expect(dependency?.sourcePath).not.toContain(join(worktree, '.ai/caches'))
-    } finally {
-      if (previousPrimaryWorkspace == null) {
-        delete process.env.__VF_PROJECT_PRIMARY_WORKSPACE_FOLDER__
-      } else {
-        process.env.__VF_PROJECT_PRIMARY_WORKSPACE_FOLDER__ = previousPrimaryWorkspace
-      }
-    }
-  })
-
-  it('reuses complete skill dependency caches without deleting or downloading them again', async () => {
-    const workspace = await createWorkspace()
-
-    const cachedSkillPath = join(
-      workspace,
-      '.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/frontend-design/SKILL.md'
-    )
-    await writeDocument(
-      cachedSkillPath,
-      '---\nname: frontend-design\ndescription: Cached UI guidance\n---\nUse the cached copy.\n'
-    )
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - anthropics/skills@frontend-design',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    expect(skillsCliMocks.findSkillsCli).not.toHaveBeenCalled()
-    expect(skillsCliMocks.installSkillsCliSkillToTemp).not.toHaveBeenCalled()
-    expect(await readFile(cachedSkillPath, 'utf8')).toContain('Use the cached copy.')
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
-  })
-
-  it('parses registry/source/version dependency specs and forwards them to the skills CLI installer', async () => {
-    const workspace = await createWorkspace()
-    const tempInstallDir = join(workspace, '.tmp-install-skills-cli')
-    const installedSkillDir = join(tempInstallDir, '.agents', 'skills', 'frontend-design')
-    await writeDocument(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse internal design tokens.\n'
-    )
-    skillsCliMocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: tempInstallDir,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - https://registry.example.com@example-source/default/public@frontend-design@1.0.3',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    expect(skillsCliMocks.installSkillsCliSkillToTemp).toHaveBeenCalledWith({
-      registry: 'https://registry.example.com',
-      skill: 'frontend-design',
-      source: 'example-source/default/public',
-      version: '1.0.3'
-    })
-  })
-
   it('loads workspace entities from the env-configured entities dir', async () => {
     const workspace = await createWorkspace()
     const previousEntitiesDir = process.env.__VF_PROJECT_AI_ENTITIES_DIR__

package/__tests__/skill-dependencies-cli.spec.ts

@@ -1,9 +1,7 @@
 /* eslint-disable import/first -- hoisted vitest mocks must be declared before importing the bundle entrypoint */
-import { access, mkdir, mkdtemp, rm, utimes, writeFile } from 'node:fs/promises'
-import os from 'node:os'
-import path, { join } from 'node:path'
+import { join } from 'node:path'
 
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const mocks = vi.hoisted(() => ({
   findSkillsCli: vi.fn(),
@@ -23,54 +21,15 @@ vi.mock('@vibe-forge/utils/skills-cli', async () => {
 
 import { buildAdapterAssetPlan, resolveWorkspaceAssetBundle } from '#~/index.js'
 
-import { createWorkspace, writeDocument } from './test-helpers'
+import { createWorkspace, installPluginPackage, writeDocument } from './test-helpers'
 
-describe('skills CLI dependency resolution', () => {
-  let installWorkspace: string
-
-  const pathExists = async (targetPath: string) => {
-    try {
-      await access(targetPath)
-      return true
-    } catch {
-      return false
-    }
-  }
-
-  beforeEach(async () => {
-    installWorkspace = await mkdtemp(path.join(os.tmpdir(), 'vf-skills-cli-dependency-'))
+describe('materialized skill dependency resolution', () => {
+  beforeEach(() => {
     vi.clearAllMocks()
   })
 
-  afterEach(async () => {
-    await rm(installWorkspace, { recursive: true, force: true })
-  })
-
-  it('installs missing bare-name dependencies through skills CLI by default', async () => {
+  it('fails missing dependencies without downloading during runtime preparation', async () => {
     const workspace = await createWorkspace()
-    const installedSkillDir = join(installWorkspace, '.agents', 'skills', 'frontend-design')
-    await mkdir(installedSkillDir, { recursive: true })
-    await writeFile(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse strong visual hierarchy.\n'
-    )
-
-    mocks.findSkillsCli.mockResolvedValue([
-      {
-        installRef: 'anthropics/skills@frontend-design',
-        source: 'anthropics/skills',
-        skill: 'frontend-design'
-      }
-    ])
-    mocks.installSkillsCliRefToTemp.mockResolvedValue({
-      tempDir: installWorkspace,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
     await writeDocument(
       join(workspace, '.ai/skills/app-builder/SKILL.md'),
       [
@@ -90,57 +49,6 @@ describe('skills CLI dependency resolution', () => {
       useDefaultVibeForgeMcpServer: false
     })
 
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })
-
-    const dependency = bundle.skills.find(asset => asset.name === 'frontend-design')
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
-    expect(dependency?.sourcePath).toContain(
-      '/.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/frontend-design/'
-    )
-    expect(mocks.findSkillsCli).toHaveBeenCalledWith({
-      query: 'frontend-design'
-    })
-    expect(mocks.installSkillsCliRefToTemp).toHaveBeenCalledWith({
-      installRef: 'anthropics/skills@frontend-design'
-    })
-  })
-
-  it('blocks missing dependency installs when auto downloads are disabled', async () => {
-    const workspace = await createWorkspace()
-
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - name: frontend-design',
-        '    source: anthropics/skills',
-        '    registry: https://dependency-registry.example.test',
-        '---',
-        'Build the app.'
-      ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [{
-        skills: {
-          autoDownloadDependencies: false
-        }
-      }, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
     await expect(buildAdapterAssetPlan({
       adapter: 'opencode',
       bundle,
@@ -149,17 +57,15 @@ describe('skills CLI dependency resolution', () => {
           include: ['app-builder']
         }
       }
-    })).rejects.toThrow('Skill dependency automatic downloads are disabled; cache not found')
+    })).rejects.toThrow('Run vf skills install or vf skills update')
 
     expect(mocks.findSkillsCli).not.toHaveBeenCalled()
     expect(mocks.installSkillsCliRefToTemp).not.toHaveBeenCalled()
     expect(mocks.installSkillsCliSkillToTemp).not.toHaveBeenCalled()
-    expect(bundle.skills.map(asset => asset.name)).toEqual(['app-builder'])
   })
 
-  it('blocks bare-name dependency searches when auto downloads are disabled', async () => {
+  it('uses project-materialized dependencies from .ai/skills', async () => {
     const workspace = await createWorkspace()
-
     await writeDocument(
       join(workspace, '.ai/skills/app-builder/SKILL.md'),
       [
@@ -172,67 +78,17 @@ describe('skills CLI dependency resolution', () => {
         'Build the app.'
       ].join('\n')
     )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [{
-        skills: {
-          autoDownloadDependencies: false
-        }
-      }, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await expect(buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
-    })).rejects.toThrow(
-      'Skill dependency automatic downloads are disabled; cannot resolve frontend-design without a source'
-    )
-
-    expect(mocks.findSkillsCli).not.toHaveBeenCalled()
-    expect(mocks.installSkillsCliRefToTemp).not.toHaveBeenCalled()
-    expect(mocks.installSkillsCliSkillToTemp).not.toHaveBeenCalled()
-  })
-
-  it('reuses source-qualified dependency caches when auto downloads are disabled', async () => {
-    const workspace = await createWorkspace()
-    await writeDocument(
-      join(
-        workspace,
-        '.ai/caches/skill-dependencies/skills-cli/skills/latest/default/anthropics/skills/latest/frontend-design/SKILL.md'
-      ),
-      '---\nname: frontend-design\ndescription: Cached UI guidance\n---\nUse the cached dependency.\n'
-    )
     await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
-        '---',
-        'name: app-builder',
-        'description: Build apps',
-        'dependencies:',
-        '  - anthropics/skills@frontend-design',
-        '---',
-        'Build the app.'
-      ].join('\n')
+      join(workspace, '.ai/skills/frontend-design/SKILL.md'),
+      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse strong visual hierarchy.\n'
     )
 
     const bundle = await resolveWorkspaceAssetBundle({
       cwd: workspace,
-      configs: [{
-        skills: {
-          autoDownloadDependencies: false
-        }
-      }, undefined],
+      configs: [undefined, undefined],
       useDefaultVibeForgeMcpServer: false
     })
-
-    await buildAdapterAssetPlan({
+    const plan = await buildAdapterAssetPlan({
       adapter: 'opencode',
       bundle,
       options: {
@@ -242,128 +98,79 @@ describe('skills CLI dependency resolution', () => {
       }
     })
 
+    expect(plan.overlays.filter(entry => entry.kind === 'skill').map(entry => entry.targetPath).sort()).toEqual([
+      'skills/app-builder',
+      'skills/frontend-design'
+    ])
     expect(mocks.findSkillsCli).not.toHaveBeenCalled()
-    expect(mocks.installSkillsCliRefToTemp).not.toHaveBeenCalled()
-    expect(mocks.installSkillsCliSkillToTemp).not.toHaveBeenCalled()
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['app-builder', 'frontend-design'])
   })
 
-  it('parses registry and version from dependency specs', async () => {
+  it('loads plugin dependencies from .ai/skills/.plugins through the lockfile', async () => {
     const workspace = await createWorkspace()
-    const installedSkillDir = join(installWorkspace, '.agents', 'skills', 'frontend-design')
-    await mkdir(installedSkillDir, { recursive: true })
-    await writeFile(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: frontend-design\ndescription: UI design guidance\n---\nUse internal design system.\n'
-    )
-
-    mocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: installWorkspace,
-      installedSkill: {
-        dirName: 'frontend-design',
-        name: 'frontend-design',
-        sourcePath: installedSkillDir
-      }
-    })
-
-    await writeDocument(
-      join(workspace, '.ai/skills/app-builder/SKILL.md'),
-      [
+    await installPluginPackage(workspace, '@vibe-forge/plugin-review', {
+      'package.json': JSON.stringify({ name: '@vibe-forge/plugin-review', version: '1.0.0' }, null, 2),
+      'skills/review-helper/SKILL.md': [
         '---',
-        'name: app-builder',
-        'description: Build apps',
+        'name: review-helper',
+        'description: Review helper',
         'dependencies:',
-        '  - https://registry.example.com@example-source/default/public@frontend-design@1.0.3',
+        '  - shared-runtime',
         '---',
-        'Build the app.'
+        'Review code.'
       ].join('\n')
-    )
-
-    const bundle = await resolveWorkspaceAssetBundle({
-      cwd: workspace,
-      configs: [undefined, undefined],
-      useDefaultVibeForgeMcpServer: false
-    })
-
-    await buildAdapterAssetPlan({
-      adapter: 'opencode',
-      bundle,
-      options: {
-        skills: {
-          include: ['app-builder']
-        }
-      }
     })
-
-    expect(mocks.installSkillsCliSkillToTemp).toHaveBeenCalledWith({
-      registry: 'https://registry.example.com',
-      skill: 'frontend-design',
-      source: 'example-source/default/public',
-      version: '1.0.3'
-    })
-  })
-
-  it('clears stale dependency install locks before retrying a direct startup install', async () => {
-    const workspace = await createWorkspace()
-    const installedSkillDir = join(installWorkspace, '.agents', 'skills', 'lynx-cat')
-    await mkdir(installedSkillDir, { recursive: true })
-    await writeFile(
-      join(installedSkillDir, 'SKILL.md'),
-      '---\nname: lynx-cat\ndescription: Lynx helper\n---\nDebug Lynx apps.\n'
+    await writeDocument(
+      join(workspace, '.ai/skills/.plugins/review/shared-runtime/SKILL.md'),
+      '---\nname: shared-runtime\ndescription: Shared runtime\n---\nShared plugin dependency.\n'
     )
-
-    mocks.installSkillsCliSkillToTemp.mockResolvedValue({
-      tempDir: installWorkspace,
-      installedSkill: {
-        dirName: 'lynx-cat',
-        name: 'lynx-cat',
-        sourcePath: installedSkillDir
-      }
-    })
-
     await writeDocument(
-      join(workspace, '.ai/skills/lynx-miniapp/SKILL.md'),
+      join(workspace, '.ai/skills.lock.yaml'),
       [
-        '---',
-        'name: lynx-miniapp',
-        'description: lynx 调试使用',
-        'dependencies:',
-        '  - https://registry.example.com@example-source/lynx/skills@lynx-cat@latest',
-        '---',
-        '这是一个测试的 lynx 调试技能'
+        'version: 1',
+        'pluginSkills:',
+        '  review/shared-runtime:',
+        '    name: shared-runtime',
+        '    requested: false',
+        '    pluginInstance: review',
+        '    pluginInstancePath: "0"',
+        '    installPath: .ai/skills/.plugins/review/shared-runtime',
+        '    dependencyOf:',
+        '      - plugin:review/review-helper',
+        '    source: vendor/shared-skills',
+        '    version: 1.0.0',
+        '    hash: sha256:test',
+        '    installedAt: "2026-05-13T00:00:00.000Z"'
       ].join('\n')
     )
 
-    const lockDir = join(
-      workspace,
-      '.ai/caches/skill-dependencies/skills-cli/skills/latest/https-registry.example.com/example-source/lynx/skills/latest/lynx-cat.lock'
-    )
-    await mkdir(lockDir, { recursive: true })
-    await utimes(lockDir, new Date(Date.now() - 120_000), new Date(Date.now() - 120_000))
-
     const bundle = await resolveWorkspaceAssetBundle({
       cwd: workspace,
-      configs: [undefined, undefined],
+      configs: [{
+        plugins: [{
+          id: '@vibe-forge/plugin-review',
+          scope: 'review'
+        }]
+      }, undefined],
       useDefaultVibeForgeMcpServer: false
     })
-
-    await buildAdapterAssetPlan({
+    const plan = await buildAdapterAssetPlan({
       adapter: 'opencode',
       bundle,
       options: {
         skills: {
-          include: ['lynx-miniapp']
+          include: ['review/review-helper']
         }
       }
     })
 
-    expect(mocks.installSkillsCliSkillToTemp).toHaveBeenCalledWith({
-      registry: 'https://registry.example.com',
-      skill: 'lynx-cat',
-      source: 'example-source/lynx/skills',
-      version: 'latest'
-    })
-    await expect(pathExists(lockDir)).resolves.toBe(false)
-    expect(bundle.skills.map(asset => asset.name).sort()).toEqual(['lynx-cat', 'lynx-miniapp'])
+    expect(bundle.skills.map(asset => asset.displayName).sort()).toEqual([
+      'review/review-helper',
+      'review/shared-runtime'
+    ])
+    expect(plan.overlays.filter(entry => entry.kind === 'skill').map(entry => entry.targetPath).sort()).toEqual([
+      'skills/review__review-helper',
+      'skills/review__shared-runtime'
+    ])
+    expect(mocks.installSkillsCliSkillToTemp).not.toHaveBeenCalled()
   })
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-forge/workspace-assets",
-  "version": "3.2.1",
+  "version": "3.2.2-alpha.0",
   "description": "Workspace asset resolution and adapter asset planning for Vibe Forge",
   "imports": {
     "#~/*.js": {
@@ -29,10 +29,10 @@
     "fast-glob": "^3.3.3",
     "front-matter": "^4.0.2",
     "js-yaml": "^4.1.1",
+    "@vibe-forge/config": "3.2.3-alpha.0",
+    "@vibe-forge/types": "3.2.3-alpha.0",
     "@vibe-forge/definition-core": "3.2.0",
-    "@vibe-forge/config": "3.2.2",
-    "@vibe-forge/types": "3.2.2",
-    "@vibe-forge/utils": "3.2.2"
+    "@vibe-forge/utils": "3.2.3-alpha.0"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9"

package/src/bundle-internal.ts

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises'
+import { access, readFile } from 'node:fs/promises'
 import { basename, dirname, extname, isAbsolute, resolve } from 'node:path'
 import process from 'node:process'
 
@@ -11,6 +11,7 @@ import {
 import type { Config, Definition, Entity, PluginConfig, WorkspaceAsset, WorkspaceAssetKind } from '@vibe-forge/types'
 import {
   isObjectSkillsConfig,
+  readProjectSkillsLockfile,
   resolveProjectAiBaseDir,
   resolveProjectAiEntitiesDir,
   resolveRelativePath
@@ -35,6 +36,7 @@ import {
 } from '@vibe-forge/definition-core'
 import { ensureConfiguredProjectSkills } from './configured-skills'
 import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
+import { PLUGIN_SKILL_DEPENDENCY_RESOLVED_BY } from './plugin-skill-dependencies'
 import { resolveConfiguredWorkspaceAssets } from './workspaces'
 
 type DocumentAssetKind = Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>
@@ -440,6 +442,40 @@ const scanInstanceDocuments = async (instance: ResolvedPluginInstance) => {
   }
 }
 
+const pathExists = async (path: string) => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const scanPluginDependencySkillDocuments = async (
+  cwd: string,
+  instances: ResolvedPluginInstance[]
+) => {
+  const lockfile = await readProjectSkillsLockfile(cwd)
+  const documents: Array<{ instance: ResolvedPluginInstance; path: string }> = []
+  for (const entry of Object.values(lockfile.pluginSkills ?? {})) {
+    const instance = instances.find(candidate => (
+      candidate.instancePath === entry.pluginInstancePath ||
+      candidate.scope === entry.pluginInstance
+    ))
+    if (instance == null) continue
+
+    const skillPath = resolve(cwd, entry.installPath, 'SKILL.md')
+    if (await pathExists(skillPath)) {
+      documents.push({
+        instance,
+        path: skillPath
+      })
+    }
+  }
+
+  return documents
+}
+
 const toOpenCodeOverlayEntries = (
   kind: OpenCodeOverlayKind,
   targetDir: 'agents' | 'commands' | 'modes' | 'plugins',
@@ -578,6 +614,7 @@ export async function collectWorkspaceAssets(params: {
   ])
   const flattenedPluginInstances = flattenPluginInstances(pluginInstances)
   const pluginScans = await Promise.all(flattenedPluginInstances.map(instance => scanInstanceDocuments(instance)))
+  const pluginDependencySkillDocs = await scanPluginDependencySkillDocuments(params.cwd, flattenedPluginInstances)
   const pluginOverlayScans = await Promise.all(
     flattenedPluginInstances.map(instance => scanInstanceOpenCodeOverlays(instance))
   )
@@ -631,6 +668,16 @@ export async function collectWorkspaceAssets(params: {
     await pushDocumentAssets('entity', scan.entityDocPaths, 'plugin', instance, parseEntityMarkdownDocument)
     await pushDocumentAssets('entity', scan.entityJsonPaths, 'plugin', instance, parseEntityIndexJson)
   }
+  for (const entry of pluginDependencySkillDocs) {
+    await pushDocumentAssets(
+      'skill',
+      [entry.path],
+      'plugin',
+      entry.instance,
+      undefined,
+      PLUGIN_SKILL_DEPENDENCY_RESOLVED_BY
+    )
+  }
   await pushDocumentAssets('skill', homeSkillPaths, 'workspace', undefined, undefined, HOME_BRIDGE_RESOLVED_BY)
 
   const skills = mergeSkillAssets(skillAssets)

package/src/plugin-skill-dependencies.ts

@@ -0,0 +1 @@
+export const PLUGIN_SKILL_DEPENDENCY_RESOLVED_BY = 'plugin-skill-dependency-lock'

package/src/selection-internal.ts

@@ -26,6 +26,7 @@ import {
   isRemoteRuleReference,
   parseScopedReference
 } from '@vibe-forge/definition-core'
+import { PLUGIN_SKILL_DEPENDENCY_RESOLVED_BY } from './plugin-skill-dependencies'
 import { expandSkillAssetDependencies, expandSkillAssetDependenciesWithRemoteResolution } from './skill-dependencies'
 
 type DocumentAssetKind = Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>
@@ -359,6 +360,10 @@ const mergeEntityDefinitions = (
 
 const uniqueAssetIds = (values: string[]) => toUniqueValues(values, value => value)
 
+const isPluginSkillDependencyAsset = (asset: Extract<WorkspaceAsset, { kind: 'skill' }>) => (
+  asset.resolvedBy === PLUGIN_SKILL_DEPENDENCY_RESOLVED_BY
+)
+
 const formatEntityCycle = (stack: EntityAsset[], asset: EntityAsset) => (
   [...stack.slice(stack.findIndex(item => item.id === asset.id)), asset]
     .map(item => item.displayName)
@@ -517,9 +522,10 @@ export const resolveSelectedSkillAssets = (
 ): Array<Extract<WorkspaceAsset, { kind: 'skill' }>> => {
   if (selection == null) return assets
 
+  const rootAssets = assets.filter(asset => !isPluginSkillDependencyAsset(asset))
   const included = selection.include != null && selection.include.length > 0
     ? resolveNamedAssets(assets, selection.include)
-    : assets
+    : rootAssets
   const excluded = new Set(
     resolveNamedAssets(assets, selection.exclude).map(asset => asset.id)
   )
@@ -532,9 +538,10 @@ export const resolveSelectedSkillAssetsWithDependencies = async (
   bundle: WorkspaceAssetBundle,
   selection?: WorkspaceSkillSelection
 ): Promise<Array<Extract<WorkspaceAsset, { kind: 'skill' }>>> => {
+  const rootAssets = bundle.skills.filter(asset => !isPluginSkillDependencyAsset(asset))
   const included = selection?.include != null && selection.include.length > 0
     ? resolveNamedAssets(bundle.skills, selection.include)
-    : bundle.skills
+    : rootAssets
   const excluded = new Set(
     resolveNamedAssets(bundle.skills, selection?.exclude).map(asset => asset.id)
   )

package/src/skill-dependencies.ts

@@ -1,14 +1,9 @@
 /* eslint-disable max-lines -- dependency normalization and graph expansion share the same local helpers */
-import { readFile } from 'node:fs/promises'
-
-import fm from 'front-matter'
-
-import { parseScopedReference, resolveSkillIdentifier } from '@vibe-forge/definition-core'
-import type { Config, Definition, Skill, WorkspaceAsset } from '@vibe-forge/types'
-import { formatSkillsSpec, parseSkillsSpec, resolveRelativePath } from '@vibe-forge/utils'
+import { parseScopedReference } from '@vibe-forge/definition-core'
+import type { Config, Skill, WorkspaceAsset } from '@vibe-forge/types'
+import { formatSkillsSpec, parseSkillsSpec } from '@vibe-forge/utils'
 
 import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
-import { installSkillsCliDependency } from './skills-cli-dependency'
 
 type SkillAsset = Extract<WorkspaceAsset, { kind: 'skill' }>
 
@@ -106,39 +101,6 @@ const findSkillAssetByRef = (
   return resolveUniqueSkillByName(searchableAssets, ref)
 }
 
-const resolveDisplayName = (name: string, scope?: string) => (
-  scope != null && scope.trim() !== '' ? `${scope}/${name}` : name
-)
-
-const parseFrontmatterSkill = async (path: string): Promise<Definition<Skill>> => {
-  const content = await readFile(path, 'utf-8')
-  const { body, attributes } = fm<Skill>(content)
-  return {
-    path,
-    body,
-    attributes
-  }
-}
-
-const createResolvedSkillAsset = (params: {
-  cwd: string
-  definition: Definition<Skill>
-}) => {
-  const name = resolveSkillIdentifier(params.definition.path, params.definition.attributes.name)
-  const displayName = resolveDisplayName(name)
-  return {
-    id: `skill:workspace:workspace:${displayName}:${resolveRelativePath(params.cwd, params.definition.path)}`,
-    kind: 'skill',
-    name,
-    displayName,
-    origin: 'workspace',
-    sourcePath: params.definition.path,
-    payload: {
-      definition: params.definition
-    }
-  } satisfies SkillAsset
-}
-
 export const normalizeSkillDependency = (value: unknown): NormalizedSkillDependency | undefined => {
   const stringValue = asNonEmptyString(value)
   if (stringValue != null) return parseSkillsSpec(stringValue)
@@ -230,8 +192,6 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
 ) => {
   const selected: SkillAsset[] = []
   const seen = new Set<string>()
-  const fetchedDependencyRefs = new Set<string>()
-
   const removeSupersededHomeBridgeSkill = (displayName: string) => {
     removeHomeBridgeSkillDuplicates(params.allAssets, displayName)
     removeHomeBridgeSkillDuplicates(params.skillAssets, displayName)
@@ -239,54 +199,6 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
     removeHomeBridgeSkillDuplicates(selected, displayName)
   }
 
-  const installDependencyAsset = async (
-    dependency: NormalizedSkillDependency,
-    currentInstancePath?: string
-  ) => {
-    const fetchKey = dependency.ref
-    if (!fetchedDependencyRefs.has(fetchKey)) {
-      fetchedDependencyRefs.add(fetchKey)
-      const installed = await installSkillsCliDependency({
-        cwd: params.cwd,
-        configs: params.configs,
-        dependency
-      })
-      const definition = await parseFrontmatterSkill(installed.skillPath)
-      const dependencyAsset = createResolvedSkillAsset({
-        cwd: params.cwd,
-        definition
-      })
-      const existingAsset = findSkillDependencyAsset(
-        params.skillAssets,
-        dependency,
-        currentInstancePath,
-        { includeHomeBridge: false }
-      ) ??
-        params.skillAssets.find(existing => (
-          existing.resolvedBy !== HOME_BRIDGE_RESOLVED_BY &&
-          existing.displayName === dependencyAsset.displayName
-        ))
-      if (existingAsset != null) {
-        removeSupersededHomeBridgeSkill(existingAsset.displayName)
-        return existingAsset
-      }
-
-      removeSupersededHomeBridgeSkill(dependencyAsset.displayName)
-      params.allAssets.push(dependencyAsset)
-      params.skillAssets.push(dependencyAsset)
-      return dependencyAsset
-    }
-
-    // After the first fetch attempt, reuse whichever asset is now visible in the
-    // skill set: a newly installed registry skill, or a home-bridge fallback
-    // that was accepted by an earlier plain-name dependency resolution.
-    const resolvedAsset = findSkillDependencyAsset(params.skillAssets, dependency, currentInstancePath)
-    if (resolvedAsset != null && resolvedAsset.resolvedBy !== HOME_BRIDGE_RESOLVED_BY) {
-      removeSupersededHomeBridgeSkill(resolvedAsset.displayName)
-    }
-    return resolvedAsset
-  }
-
   const addAsset = async (asset: SkillAsset): Promise<void> => {
     if (params.excludedIds?.has(asset.id)) return
     if (seen.has(asset.id)) return
@@ -311,25 +223,15 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
         continue
       }
 
-      // Keep registry-backed dependencies ahead of home-bridge skills. We only
-      // fall back to a bridged home skill for plain-name dependencies when the
-      // registry path is unavailable.
-      const dependencyAsset = await installDependencyAsset(dependency, asset.instancePath).catch((error: unknown) => {
-        if (
-          localOrBridgedDependency != null &&
-          dependency.source == null
-        ) {
-          return localOrBridgedDependency
-        }
-        throw error
-      }) ?? (
-        dependency.source == null
-          ? localOrBridgedDependency
-          : undefined
-      )
+      const dependencyAsset = dependency.source == null
+        ? localOrBridgedDependency
+        : undefined
 
       if (dependencyAsset == null) {
-        throw new Error(`Failed to resolve skill dependency ${dependency.ref} declared by ${asset.displayName}`)
+        throw new Error(
+          `Skill dependency ${dependency.ref} declared by ${asset.displayName} is missing. ` +
+            'Run vf skills install or vf skills update to materialize project skill dependencies.'
+        )
       }
       await addAsset(dependencyAsset)
     }

package/src/skills-cli-dependency-helpers.ts

@@ -1,94 +0,0 @@
-import { access, copyFile, lstat, mkdir, readdir } from 'node:fs/promises'
-import { dirname, resolve } from 'node:path'
-import process from 'node:process'
-
-import { withDirectoryInstallLock } from '@vibe-forge/utils/install-lock'
-import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
-import { toSkillSlug } from '@vibe-forge/utils/skills-cli'
-
-const toCacheSegment = (value: string) => (
-  value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, '-')
-    .replace(/^-+|-+$/g, '') || 'default'
-)
-
-export const pathExists = async (targetPath: string) => {
-  try {
-    await access(targetPath)
-    return true
-  } catch {
-    return false
-  }
-}
-
-export const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
-  try {
-    return await withDirectoryInstallLock({ lockDir }, callback)
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error)
-    throw new Error(
-      message.replace('Timed out waiting for install lock', 'Timed out waiting for skill dependency install lock')
-    )
-  }
-}
-
-export const copyRegularFiles = async (sourceDir: string, targetDir: string) => {
-  let fileCount = 0
-  const entries = await readdir(sourceDir, { withFileTypes: true })
-
-  await mkdir(targetDir, { recursive: true })
-
-  for (const entry of entries) {
-    const sourcePath = resolve(sourceDir, entry.name)
-    const targetPath = resolve(targetDir, entry.name)
-    const stat = await lstat(sourcePath)
-
-    if (stat.isDirectory()) {
-      fileCount += await copyRegularFiles(sourcePath, targetPath)
-      continue
-    }
-
-    if (!stat.isFile()) continue
-
-    await mkdir(dirname(targetPath), { recursive: true })
-    await copyFile(sourcePath, targetPath)
-    fileCount += 1
-  }
-
-  return fileCount
-}
-
-export const pickSearchResult = <T extends { skill: string }>(
-  results: T[],
-  name: string
-) => {
-  const slug = toSkillSlug(name)
-  return results.find(result => (
-    result.skill === name ||
-    toSkillSlug(result.skill) === slug
-  )) ?? results[0]
-}
-
-export const buildInstallDir = (params: {
-  cwd: string
-  registry?: string
-  skill: string
-  source: string
-  version?: string
-}) => {
-  const registry = params.registry ?? 'default'
-  return resolveProjectSharedCachePath(
-    params.cwd,
-    process.env,
-    'skill-dependencies',
-    'skills-cli',
-    toCacheSegment('skills'),
-    toCacheSegment('latest'),
-    toCacheSegment(registry),
-    ...params.source.split('/').map(toCacheSegment),
-    toCacheSegment(params.version ?? 'latest'),
-    toCacheSegment(params.skill)
-  )
-}

package/src/skills-cli-dependency.ts

@@ -1,133 +0,0 @@
-import { mkdir, rename, rm } from 'node:fs/promises'
-import { resolve } from 'node:path'
-import process from 'node:process'
-
-import type { Config } from '@vibe-forge/types'
-import { isObjectSkillsConfig, resolveSkillsRegistry } from '@vibe-forge/utils'
-import { findSkillsCli, installSkillsCliRefToTemp, installSkillsCliSkillToTemp } from '@vibe-forge/utils/skills-cli'
-
-import type { NormalizedSkillDependency } from './skill-dependencies'
-import {
-  buildInstallDir,
-  copyRegularFiles,
-  pathExists,
-  pickSearchResult,
-  withInstallLock
-} from './skills-cli-dependency-helpers'
-
-const resolveAutoDownloadDependenciesEnabled = (
-  projectConfig: Config | undefined,
-  userConfig: Config | undefined
-) => (
-  (isObjectSkillsConfig(userConfig?.skills) ? userConfig.skills.autoDownloadDependencies : undefined) ??
-    (isObjectSkillsConfig(projectConfig?.skills) ? projectConfig.skills.autoDownloadDependencies : undefined) ??
-    true
-)
-
-export const installSkillsCliDependency = async (params: {
-  cwd: string
-  configs: [Config?, Config?]
-  dependency: NormalizedSkillDependency
-}) => {
-  const [projectConfig, userConfig] = params.configs
-  const autoDownloadDependenciesEnabled = resolveAutoDownloadDependenciesEnabled(projectConfig, userConfig)
-  const defaultRegistry = resolveSkillsRegistry(params.configs[1]?.skills) ??
-    resolveSkillsRegistry(params.configs[0]?.skills)
-  const registry = params.dependency.registry ?? defaultRegistry
-  const resolvedTarget = await (async () => {
-    if (params.dependency.source != null) {
-      return {
-        skill: params.dependency.name,
-        source: params.dependency.source
-      }
-    }
-
-    if (!autoDownloadDependenciesEnabled) {
-      throw new Error(
-        `Skill dependency automatic downloads are disabled; cannot resolve ${params.dependency.ref} without a source`
-      )
-    }
-
-    return await (async () => {
-      const searchResults = await findSkillsCli({
-        registry,
-        query: params.dependency.name
-      })
-      const selected = pickSearchResult(searchResults, params.dependency.name)
-      if (selected == null) {
-        throw new Error(`Skill ${params.dependency.name} was not found by the skills CLI search.`)
-      }
-
-      return {
-        installRef: selected.installRef,
-        skill: selected.skill,
-        source: selected.source
-      }
-    })()
-  })()
-
-  const installDir = buildInstallDir({
-    cwd: params.cwd,
-    registry,
-    skill: resolvedTarget.skill,
-    source: resolvedTarget.source,
-    version: params.dependency.version
-  })
-  const skillPath = resolve(installDir, 'SKILL.md')
-
-  return await withInstallLock(`${installDir}.lock`, async () => {
-    if (await pathExists(skillPath)) {
-      return {
-        installDir,
-        skillPath
-      }
-    }
-
-    if (!autoDownloadDependenciesEnabled) {
-      throw new Error(`Skill dependency automatic downloads are disabled; cache not found for ${params.dependency.ref}`)
-    }
-
-    const tempInstallDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
-    await rm(tempInstallDir, { recursive: true, force: true })
-    await mkdir(tempInstallDir, { recursive: true })
-
-    const installResult = 'installRef' in resolvedTarget
-      ? params.dependency.version == null
-        ? await installSkillsCliRefToTemp({
-          installRef: resolvedTarget.installRef,
-          registry
-        })
-        : await installSkillsCliSkillToTemp({
-          registry,
-          skill: resolvedTarget.skill,
-          source: resolvedTarget.source,
-          version: params.dependency.version
-        })
-      : await installSkillsCliSkillToTemp({
-        registry,
-        skill: resolvedTarget.skill,
-        source: resolvedTarget.source,
-        version: params.dependency.version
-      })
-
-    try {
-      await copyRegularFiles(installResult.installedSkill.sourcePath, tempInstallDir)
-      if (!await pathExists(resolve(tempInstallDir, 'SKILL.md'))) {
-        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
-      }
-
-      await rm(installDir, { recursive: true, force: true })
-      await rename(tempInstallDir, installDir)
-    } catch (error) {
-      await rm(tempInstallDir, { recursive: true, force: true })
-      throw error
-    } finally {
-      await rm(installResult.tempDir, { recursive: true, force: true })
-    }
-
-    return {
-      installDir,
-      skillPath
-    }
-  })
-}