@vibe-forge/workspace-assets 2.0.1 → 2.0.2

package/__tests__/prompt-builders.spec.ts

@@ -9,6 +9,7 @@ import {
   generateSkillsRoutePrompt,
   generateSpecRoutePrompt
 } from '#~/prompt-builders.js'
+import { generateWorkspaceRoutePrompt } from '#~/workspace-prompt.js'
 
 describe('workspace asset prompt builders', () => {
   it('builds skill prompts with stable names, descriptions, and relative paths', () => {
@@ -175,12 +176,50 @@ describe('workspace asset prompt builders', () => {
     expect(prompt).toContain('reviewer: 负责代码审查')
     expect(prompt).toContain('`VibeForge.StartTasks`')
     expect(prompt).toContain('`VibeForge.GetTaskInfo`')
+    expect(prompt).toContain('Task tool guide:')
+    expect(prompt).toContain('After starting a task')
+    expect(prompt).toContain('10 most recent log entries')
+    expect(prompt).toContain('`logLimit`')
+    expect(prompt).toContain('`logOrder`')
+    expect(prompt).toContain('`VibeForge.SendTaskMessage`')
+    expect(prompt).toContain('`{ taskId, message, mode }`')
+    expect(prompt).toContain('Choose `mode: "direct"`')
+    expect(prompt).toContain('Choose `mode: "steer"`')
+    expect(prompt).toContain('`VibeForge.SubmitTaskInput`')
+    expect(prompt).toContain('Do not use it for ordinary follow-up instructions or queued steer turns')
+    expect(prompt).toContain('If a task is `completed` or `failed`')
     expect(prompt).toContain('`wait`')
     expect(prompt).not.toContain('run-tasks')
     expect(prompt).not.toContain('需要关注变更风险')
     expect(prompt).not.toContain('hidden')
   })
 
+  it('builds workspace routes with managed task guidance', () => {
+    const cwd = '/tmp/project'
+
+    const prompt = generateWorkspaceRoutePrompt(cwd, [
+      {
+        id: 'billing',
+        cwd: join(cwd, 'packages/billing'),
+        path: join(cwd, '.ai/workspaces/billing.md'),
+        description: 'Billing workspace'
+      }
+    ])
+
+    expect(prompt).toContain('The project includes the following registered workspaces')
+    expect(prompt).toContain('Identifier: billing')
+    expect(prompt).toContain('`VibeForge.StartTasks`')
+    expect(prompt).toContain('type: "workspace"')
+    expect(prompt).toContain('Task tool guide:')
+    expect(prompt).toContain('`VibeForge.GetTaskInfo`')
+    expect(prompt).toContain('`VibeForge.ListTasks`')
+    expect(prompt).toContain('`VibeForge.SendTaskMessage`')
+    expect(prompt).toContain('`VibeForge.SubmitTaskInput`')
+    expect(prompt).toContain('Choose `mode: "direct"`')
+    expect(prompt).toContain('Choose `mode: "steer"`')
+    expect(prompt).toContain('Do not directly edit files inside a registered workspace')
+  })
+
   it('builds skill route prompts without preloading content', () => {
     const cwd = '/tmp/project'
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-forge/workspace-assets",
-  "version": "2.0.1",
+  "version": "2.0.2",
   "description": "Workspace asset resolution and adapter asset planning for Vibe Forge",
   "imports": {
     "#~/*.js": {
@@ -30,9 +30,9 @@
     "fast-glob": "^3.3.3",
     "front-matter": "^4.0.2",
     "js-yaml": "^4.1.1",
-    "@vibe-forge/utils": "^2.0.1",
-    "@vibe-forge/types": "^2.0.1",
-    "@vibe-forge/definition-core": "^2.0.1"
+    "@vibe-forge/definition-core": "^2.0.0",
+    "@vibe-forge/types": "^2.0.2",
+    "@vibe-forge/utils": "^2.0.3"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9"

package/src/bundle-internal.ts

@@ -9,12 +9,7 @@ import {
   resolveDefaultVibeForgeMcpServerConfig
 } from '@vibe-forge/config'
 import type { Config, Definition, Entity, PluginConfig, WorkspaceAsset, WorkspaceAssetKind } from '@vibe-forge/types'
-import {
-  isLegacySkillsConfig,
-  resolveProjectAiBaseDir,
-  resolveProjectAiEntitiesDir,
-  resolveRelativePath
-} from '@vibe-forge/utils'
+import { resolveProjectAiBaseDir, resolveProjectAiEntitiesDir, resolveRelativePath } from '@vibe-forge/utils'
 import { listManagedPluginInstalls, toManagedPluginConfig } from '@vibe-forge/utils/managed-plugin'
 import {
   flattenPluginInstances,
@@ -33,7 +28,6 @@ import {
   resolveSkillIdentifier,
   resolveSpecIdentifier
 } from '@vibe-forge/definition-core'
-import { ensureConfiguredProjectSkills } from './configured-skills'
 import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
 import { resolveConfiguredWorkspaceAssets } from './workspaces'
 
@@ -159,8 +153,8 @@ const warnInvalidHomeSkillRoot = (root: string) => {
 
 const resolveHomeBridgeConfig = (configs: [Config?, Config?]) => {
   const [config, userConfig] = configs
-  const projectHomeBridge = isLegacySkillsConfig(config?.skills) ? config.skills.homeBridge : undefined
-  const userHomeBridge = isLegacySkillsConfig(userConfig?.skills) ? userConfig.skills.homeBridge : undefined
+  const projectHomeBridge = config?.skills?.homeBridge
+  const userHomeBridge = userConfig?.skills?.homeBridge
 
   return {
     enabled: userHomeBridge?.enabled ?? projectHomeBridge?.enabled ?? true,
@@ -532,8 +526,6 @@ export async function collectWorkspaceAssets(params: {
   plugins?: PluginConfig
   overlaySource?: string
   includeManagedPlugins?: boolean
-  syncConfiguredSkills?: boolean
-  updateConfiguredSkills?: boolean
   useDefaultVibeForgeMcpServer?: boolean
 }): Promise<{
   assets: WorkspaceAsset[]
@@ -552,13 +544,6 @@ export async function collectWorkspaceAssets(params: {
   workspaces: Array<Extract<WorkspaceAsset, { kind: 'workspace' }>>
 }> {
   const [config, userConfig] = params.configs ?? await loadWorkspaceConfig(params.cwd)
-  if (params.syncConfiguredSkills === true) {
-    await ensureConfiguredProjectSkills({
-      configs: [config, userConfig],
-      updateInstalledSkills: params.updateConfiguredSkills,
-      workspaceFolder: params.cwd
-    })
-  }
   const managedPluginConfigs = params.includeManagedPlugins === false
     ? undefined
     : toManagedPluginConfig(await listManagedPluginInstalls(params.cwd))

package/src/bundle.ts

@@ -8,8 +8,6 @@ export async function resolveWorkspaceAssetBundle(params: {
   plugins?: PluginConfig
   overlaySource?: string
   includeManagedPlugins?: boolean
-  syncConfiguredSkills?: boolean
-  updateConfiguredSkills?: boolean
   useDefaultVibeForgeMcpServer?: boolean
 }): Promise<WorkspaceAssetBundle> {
   const collected = await collectWorkspaceAssets(params)

package/src/prompt-builders.ts

@@ -7,6 +7,8 @@ import {
 import type { Definition, Entity, Rule, Skill, Spec } from '@vibe-forge/types'
 import { CANONICAL_VIBE_FORGE_MCP_SERVER_NAME, resolvePromptPath } from '@vibe-forge/utils'
 
+import { buildManagedTaskToolGuidance } from './task-tool-guidance'
+
 const toMarkdownBlockquote = (content: string) => (
   content
     .trim()
@@ -165,6 +167,7 @@ export const generateSpecRoutePrompt = (
 }
 
 export const generateEntitiesRoutePrompt = (entities: Definition<Entity>[]) => {
+  const taskToolGuidance = buildManagedTaskToolGuidance(CANONICAL_VIBE_FORGE_MCP_SERVER_NAME)
   return (
     '<system-prompt>\n' +
     'The project includes the following entities:\n' +
@@ -179,6 +182,7 @@ export const generateEntitiesRoutePrompt = (entities: Definition<Entity>[]) => {
         .join('')
     }\n` +
     `When solving user problems, you may specify entities through \`${CANONICAL_VIBE_FORGE_MCP_SERVER_NAME}.StartTasks\` as needed and have them coordinate multiple entity types to complete the work; use \`${CANONICAL_VIBE_FORGE_MCP_SERVER_NAME}.GetTaskInfo\` and \`wait\` to track progress.\n` +
+    `${taskToolGuidance}\n` +
     '</system-prompt>\n'
   )
 }

package/src/prompt-selection.ts

@@ -35,7 +35,7 @@ import {
   resolveSelectedSkillAssetsWithDependencies,
   toDocumentDefinitions
 } from './selection-internal'
-import { expandSkillAssetDependenciesWithRemoteResolution } from './skill-dependencies'
+import { expandSkillAssetDependenciesWithRegistry } from './skill-dependencies'
 import { generateWorkspaceRoutePrompt } from './workspace-prompt'
 
 export async function resolvePromptAssetSelection(params: {
@@ -164,7 +164,7 @@ export async function resolvePromptAssetSelection(params: {
       resolveNamedAssets(effectiveBundle.skills, excludedRefs, targetInstancePath).map(asset => asset.id)
     )
 
-    const expandedTargetSkills = await expandSkillAssetDependenciesWithRemoteResolution({
+    const expandedTargetSkills = await expandSkillAssetDependenciesWithRegistry({
       allAssets: effectiveBundle.assets,
       configs: effectiveBundle.configs ?? [undefined, undefined],
       cwd: effectiveBundle.cwd,

package/src/selection-internal.ts

@@ -26,7 +26,7 @@ import {
   isRemoteRuleReference,
   parseScopedReference
 } from '@vibe-forge/definition-core'
-import { expandSkillAssetDependencies, expandSkillAssetDependenciesWithRemoteResolution } from './skill-dependencies'
+import { expandSkillAssetDependencies, expandSkillAssetDependenciesWithRegistry } from './skill-dependencies'
 
 type DocumentAssetKind = Extract<WorkspaceAssetKind, 'rule' | 'spec' | 'entity' | 'skill'>
 type DocumentAsset<TDefinition> = Extract<WorkspaceAsset, { kind: DocumentAssetKind }> & {
@@ -538,7 +538,7 @@ export const resolveSelectedSkillAssetsWithDependencies = async (
   const excluded = new Set(
     resolveNamedAssets(bundle.skills, selection?.exclude).map(asset => asset.id)
   )
-  return await expandSkillAssetDependenciesWithRemoteResolution({
+  return await expandSkillAssetDependenciesWithRegistry({
     allAssets: bundle.assets,
     configs: bundle.configs ?? [undefined, undefined],
     cwd: bundle.cwd,

package/src/skill-dependencies.ts

@@ -8,7 +8,7 @@ import type { Config, Definition, Skill, WorkspaceAsset } from '@vibe-forge/type
 import { resolveRelativePath } from '@vibe-forge/utils'
 
 import { HOME_BRIDGE_RESOLVED_BY } from './home-bridge'
-import { installSkillsCliDependency } from './skills-cli-dependency'
+import { installRegistrySkillDependency } from './skill-registry'
 
 type SkillAsset = Extract<WorkspaceAsset, { kind: 'skill' }>
 
@@ -16,6 +16,7 @@ export interface NormalizedSkillDependency {
   ref: string
   name: string
   source?: string
+  registry?: string
 }
 
 interface DependencyExpansionParams {
@@ -118,7 +119,7 @@ const parseFrontmatterSkill = async (path: string): Promise<Definition<Skill>> =
   }
 }
 
-const createResolvedSkillAsset = (params: {
+const createRegistrySkillAsset = (params: {
   cwd: string
   definition: Definition<Skill>
 }) => {
@@ -148,15 +149,12 @@ const parseStringDependency = (value: string): NormalizedSkillDependency => {
     }
   }
 
-  const sourcePathSegments = ref.split('/').filter(segment => segment.trim() !== '')
-  if (
-    sourcePathSegments.length >= 3 &&
-    sourcePathSegments.every(segment => !segment.includes(' '))
-  ) {
+  const sourcePathMatch = ref.match(/^([^/\s]+\/[^/\s]+)\/([^/\s]+)$/)
+  if (sourcePathMatch != null) {
     return {
       ref,
-      source: sourcePathSegments.slice(0, -1).join('/'),
-      name: sourcePathSegments[sourcePathSegments.length - 1]
+      source: sourcePathMatch[1],
+      name: sourcePathMatch[2]
     }
   }
 
@@ -179,7 +177,8 @@ export const normalizeSkillDependency = (value: unknown): NormalizedSkillDepende
   return {
     ref: source == null ? name : `${source}@${name}`,
     name,
-    ...(source == null ? {} : { source })
+    ...(source == null ? {} : { source }),
+    ...(asNonEmptyString(record.registry) == null ? {} : { registry: asNonEmptyString(record.registry) })
   }
 }
 
@@ -243,7 +242,7 @@ export const expandSkillAssetDependencies = (
   return selected
 }
 
-export const expandSkillAssetDependenciesWithRemoteResolution = async (
+export const expandSkillAssetDependenciesWithRegistry = async (
   params: DependencyExpansionParams
 ) => {
   const selected: SkillAsset[] = []
@@ -261,16 +260,16 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
     dependency: NormalizedSkillDependency,
     currentInstancePath?: string
   ) => {
-    const fetchKey = dependency.ref
+    const fetchKey = `${dependency.registry ?? ''}:${dependency.ref}`
     if (!fetchedDependencyRefs.has(fetchKey)) {
       fetchedDependencyRefs.add(fetchKey)
-      const installed = await installSkillsCliDependency({
+      const installed = await installRegistrySkillDependency({
         cwd: params.cwd,
         configs: params.configs,
         dependency
       })
       const definition = await parseFrontmatterSkill(installed.skillPath)
-      const dependencyAsset = createResolvedSkillAsset({
+      const dependencyAsset = createRegistrySkillAsset({
         cwd: params.cwd,
         definition
       })
@@ -335,13 +334,14 @@ export const expandSkillAssetDependenciesWithRemoteResolution = async (
       const dependencyAsset = await installDependencyAsset(dependency, asset.instancePath).catch((error: unknown) => {
         if (
           localOrBridgedDependency != null &&
-          dependency.source == null
+          dependency.source == null &&
+          dependency.registry == null
         ) {
           return localOrBridgedDependency
         }
         throw error
       }) ?? (
-        dependency.source == null
+        dependency.source == null && dependency.registry == null
           ? localOrBridgedDependency
           : undefined
       )

package/src/skill-registry.ts

@@ -0,0 +1,329 @@
+/* eslint-disable max-lines -- registry install logic keeps URL resolution, locking, and cache writes together */
+import { access, mkdir, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import process from 'node:process'
+import { setTimeout as delay } from 'node:timers/promises'
+
+import type { Config } from '@vibe-forge/types'
+import { resolveProjectSharedCachePath } from '@vibe-forge/utils/project-cache-path'
+
+import type { NormalizedSkillDependency } from './skill-dependencies'
+
+interface RegistryOptions {
+  enabled: boolean
+  searchBaseUrl: string
+  downloadBaseUrl: string
+}
+
+interface RegistrySearchSkill {
+  id?: string
+  name?: string
+  skillId?: string
+  source?: string
+}
+
+interface RegistryDownloadFile {
+  path?: string
+  contents?: string
+}
+
+interface RegistryDownloadResponse {
+  files?: RegistryDownloadFile[]
+}
+
+const DEFAULT_SKILL_REGISTRY_URL = 'https://skills.sh'
+const FETCH_TIMEOUT_MS = 10_000
+const INSTALL_LOCK_TIMEOUT_MS = 30_000
+const INSTALL_LOCK_RETRY_MS = 100
+
+const asNonEmptyString = (value: unknown) => (
+  typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined
+)
+
+const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '')
+
+const toSkillSlug = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, '-')
+    .replace(/[^a-z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+)
+
+const toCacheSegment = (value: string) => (
+  value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '') || 'registry'
+)
+
+const resolveConfiguredRegistry = (
+  projectConfig: Config | undefined,
+  userConfig: Config | undefined
+) => userConfig?.skills?.registry ?? projectConfig?.skills?.registry
+
+const resolveRegistryOptions = (params: {
+  configs: [Config?, Config?]
+  registry?: string
+}): RegistryOptions => {
+  const [projectConfig, userConfig] = params.configs
+  const configuredRegistry = params.registry ?? resolveConfiguredRegistry(projectConfig, userConfig)
+  const envSearchBaseUrl = asNonEmptyString(process.env.SKILLS_API_URL)
+  const envDownloadBaseUrl = asNonEmptyString(process.env.SKILLS_DOWNLOAD_URL)
+
+  if (typeof configuredRegistry === 'string' && configuredRegistry.trim() !== '') {
+    const baseUrl = normalizeBaseUrl(configuredRegistry.trim())
+    return {
+      enabled: true,
+      searchBaseUrl: baseUrl,
+      downloadBaseUrl: baseUrl
+    }
+  }
+
+  if (configuredRegistry != null && typeof configuredRegistry === 'object') {
+    const baseUrl = normalizeBaseUrl(
+      asNonEmptyString(configuredRegistry.url) ?? DEFAULT_SKILL_REGISTRY_URL
+    )
+    return {
+      enabled: configuredRegistry.enabled !== false,
+      searchBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.searchUrl) ?? baseUrl),
+      downloadBaseUrl: normalizeBaseUrl(asNonEmptyString(configuredRegistry.downloadUrl) ?? baseUrl)
+    }
+  }
+
+  const baseUrl = normalizeBaseUrl(envSearchBaseUrl ?? DEFAULT_SKILL_REGISTRY_URL)
+  return {
+    enabled: true,
+    searchBaseUrl: baseUrl,
+    downloadBaseUrl: normalizeBaseUrl(envDownloadBaseUrl ?? baseUrl)
+  }
+}
+
+const fetchJson = async <T>(url: string): Promise<T> => {
+  const response = await fetch(url, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  })
+  if (!response.ok) {
+    throw new Error(`Request failed with status ${response.status}`)
+  }
+  return await response.json() as T
+}
+
+const parseSourceAndSlugFromId = (id: string | undefined) => {
+  if (id == null) return undefined
+  const segments = id.split('/').filter(Boolean)
+  if (segments.length < 3) return undefined
+  return {
+    source: `${segments[0]}/${segments[1]}`,
+    slug: segments.slice(2).join('/')
+  }
+}
+
+const pickSearchResult = (
+  skills: RegistrySearchSkill[],
+  name: string
+) => {
+  const slug = toSkillSlug(name)
+  return skills.find(skill => (
+    skill.skillId === slug ||
+    skill.name === name ||
+    toSkillSlug(skill.name ?? '') === slug ||
+    parseSourceAndSlugFromId(skill.id)?.slug === slug
+  )) ?? skills[0]
+}
+
+const resolveRegistrySkillTarget = async (
+  dependency: NormalizedSkillDependency,
+  registry: RegistryOptions
+) => {
+  if (dependency.source != null) {
+    return {
+      source: dependency.source,
+      slug: toSkillSlug(dependency.name)
+    }
+  }
+
+  const searchUrl = `${registry.searchBaseUrl}/api/search?q=${encodeURIComponent(dependency.name)}&limit=10`
+  const searchResult = await fetchJson<{
+    skills?: RegistrySearchSkill[]
+  }>(searchUrl)
+  const skills = Array.isArray(searchResult.skills) ? searchResult.skills : []
+  const picked = pickSearchResult(skills, dependency.name)
+  if (picked == null) {
+    throw new Error(`Skill ${dependency.name} was not found in ${registry.searchBaseUrl}`)
+  }
+
+  const parsed = parseSourceAndSlugFromId(picked.id)
+  const source = asNonEmptyString(picked.source) ?? parsed?.source
+  const slug = asNonEmptyString(picked.skillId) ?? parsed?.slug ?? toSkillSlug(picked.name ?? dependency.name)
+  if (source == null || slug === '') {
+    throw new Error(`Registry search result for ${dependency.name} did not include a source and skill id`)
+  }
+
+  return {
+    source,
+    slug
+  }
+}
+
+const toSafeRelativePath = (filePath: string) => {
+  const normalized = filePath.replace(/\\/g, '/')
+  if (normalized.startsWith('/') || normalized.split('/').includes('..')) {
+    throw new Error(`Unsafe skill dependency file path ${filePath}`)
+  }
+  return normalized
+}
+
+const assertInside = (root: string, target: string) => {
+  const relativePath = relative(root, target)
+  if (
+    relativePath === '' ||
+    (
+      relativePath !== '..' &&
+      !relativePath.startsWith(`..${sep}`) &&
+      !isAbsolute(relativePath)
+    )
+  ) {
+    return
+  }
+  throw new Error(`Skill dependency file resolves outside ${root}`)
+}
+
+const pathExists = async (path: string) => {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+const withInstallLock = async <T>(lockDir: string, callback: () => Promise<T>) => {
+  const start = Date.now()
+  await mkdir(dirname(lockDir), { recursive: true })
+
+  while (true) {
+    try {
+      await mkdir(lockDir)
+      break
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      if (Date.now() - start > INSTALL_LOCK_TIMEOUT_MS) {
+        throw new Error(`Timed out waiting for skill dependency install lock ${lockDir}`)
+      }
+      await delay(INSTALL_LOCK_RETRY_MS)
+    }
+  }
+
+  try {
+    return await callback()
+  } finally {
+    await rm(lockDir, { recursive: true, force: true })
+  }
+}
+
+const buildInstallDir = (params: {
+  cwd: string
+  registry: RegistryOptions
+  source: string
+  slug: string
+}) => {
+  let registryKey = params.registry.downloadBaseUrl
+  try {
+    const parsed = new URL(params.registry.downloadBaseUrl)
+    registryKey = `${parsed.hostname}${parsed.pathname}`
+  } catch {
+  }
+
+  return resolveProjectSharedCachePath(
+    params.cwd,
+    process.env,
+    'skill-dependencies',
+    toCacheSegment(registryKey),
+    ...params.source.split('/').map(toCacheSegment),
+    toCacheSegment(params.slug)
+  )
+}
+
+export const installRegistrySkillDependency = async (params: {
+  cwd: string
+  configs: [Config?, Config?]
+  dependency: NormalizedSkillDependency
+}) => {
+  const registry = resolveRegistryOptions({
+    configs: params.configs,
+    registry: params.dependency.registry
+  })
+  if (!registry.enabled) {
+    throw new Error(`Skill dependency registry is disabled; cannot install ${params.dependency.ref}`)
+  }
+
+  const target = await resolveRegistrySkillTarget(params.dependency, registry)
+  const [owner, repo] = target.source.split('/')
+  if (owner == null || repo == null || owner === '' || repo === '') {
+    throw new Error(`Skill dependency source ${target.source} must use owner/repo format`)
+  }
+
+  const downloadUrl = `${registry.downloadBaseUrl}/api/download/${encodeURIComponent(owner)}/${
+    encodeURIComponent(repo)
+  }/${encodeURIComponent(target.slug)}`
+  const installDir = buildInstallDir({
+    cwd: params.cwd,
+    registry,
+    source: target.source,
+    slug: target.slug
+  })
+  const skillPath = resolve(installDir, 'SKILL.md')
+
+  return await withInstallLock(`${installDir}.lock`, async () => {
+    if (await pathExists(skillPath)) {
+      return {
+        installDir,
+        skillPath
+      }
+    }
+
+    const response = await fetchJson<RegistryDownloadResponse>(downloadUrl)
+    const files = Array.isArray(response.files) ? response.files : []
+    if (files.length === 0) {
+      throw new Error(`Skill dependency ${params.dependency.ref} did not include any files`)
+    }
+
+    const tempDir = `${installDir}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`
+    await rm(tempDir, { recursive: true, force: true })
+    await mkdir(tempDir, { recursive: true })
+
+    try {
+      let hasSkillMd = false
+      for (const file of files) {
+        const filePath = asNonEmptyString(file.path)
+        if (filePath == null || typeof file.contents !== 'string') continue
+        const relativePath = toSafeRelativePath(filePath)
+        if (relativePath.toLowerCase() === 'skill.md') hasSkillMd = true
+
+        const targetPath = resolve(tempDir, relativePath)
+        assertInside(tempDir, targetPath)
+        await mkdir(dirname(targetPath), { recursive: true })
+        await writeFile(targetPath, file.contents, 'utf8')
+      }
+
+      if (!hasSkillMd) {
+        throw new Error(`Skill dependency ${params.dependency.ref} did not include SKILL.md`)
+      }
+
+      await rm(installDir, { recursive: true, force: true })
+      await rename(tempDir, installDir)
+    } catch (error) {
+      await rm(tempDir, { recursive: true, force: true })
+      throw error
+    }
+
+    return {
+      installDir,
+      skillPath
+    }
+  })
+}

package/src/task-tool-guidance.ts

@@ -0,0 +1,15 @@
+export const buildManagedTaskToolGuidance = (serverName: string) => {
+  return [
+    'Task tool guide:',
+    `- Use \`${serverName}.StartTasks\` to start a new child task when the work should run in a separate entity or workspace, or when it needs to continue independently from the current turn.`,
+    `- After starting a task, use \`${serverName}.GetTaskInfo\` with \`{ taskId }\` to inspect one task. It is also the right tool when a task seems stalled, failed, or might be waiting for input.`,
+    '- By default, `GetTaskInfo` returns the 10 most recent log entries in descending order, so newer entries appear earlier in the `logs` array. Pass `logLimit` to inspect a different number of recent logs, and set `logOrder` to `"asc"` when you want the selected log window in oldest-to-newest order.',
+    `- Use \`${serverName}.ListTasks\` with the same \`logLimit\` and \`logOrder\` fields when you need to find a taskId or inspect multiple tasks at once.`,
+    `- Use \`${serverName}.SendTaskMessage\` with \`{ taskId, message, mode }\` when you want to continue the same task without starting a replacement task.`,
+    '- Choose `mode: "direct"` when the task is `running` and the new instruction should be delivered immediately into the current task.',
+    '- Choose `mode: "steer"` when the task should finish its current run naturally first, and the follow-up should be queued for the same task afterward.',
+    `- Use \`${serverName}.SubmitTaskInput\` only when \`${serverName}.GetTaskInfo\` or \`${serverName}.ListTasks\` shows \`pendingInput\` or \`pendingInteraction\`, or the task status is \`waiting_input\`. Do not use it for ordinary follow-up instructions or queued steer turns.`,
+    '- If a task is `completed` or `failed`, start a new task instead of trying to continue the old one.',
+    '- When a task is still making progress, use `wait` between checks instead of repeatedly restarting it.'
+  ].join('\n')
+}

package/src/workspace-prompt.ts

@@ -1,11 +1,14 @@
 import type { WorkspaceDefinitionPayload } from '@vibe-forge/types'
 import { CANONICAL_VIBE_FORGE_MCP_SERVER_NAME, resolvePromptPath } from '@vibe-forge/utils'
 
+import { buildManagedTaskToolGuidance } from './task-tool-guidance'
+
 export const generateWorkspaceRoutePrompt = (
   cwd: string,
   workspaces: WorkspaceDefinitionPayload[]
 ) => {
   if (workspaces.length === 0) return ''
+  const taskToolGuidance = buildManagedTaskToolGuidance(CANONICAL_VIBE_FORGE_MCP_SERVER_NAME)
 
   const workspaceList = workspaces
     .map((workspace) => {
@@ -24,6 +27,7 @@ export const generateWorkspaceRoutePrompt = (
     `${workspaceList}\n` +
     `When a user request targets one of these workspaces, start a child task with \`${CANONICAL_VIBE_FORGE_MCP_SERVER_NAME}.StartTasks\` using \`type: "workspace"\` and \`name\` set to the workspace identifier. ` +
     'Do not directly edit files inside a registered workspace from the current session unless the user explicitly asks this session to work in that directory.\n' +
+    `${taskToolGuidance}\n` +
     '</system-prompt>\n'
   )
 }