refactor(core): use native Cloudflare provider

Co-authored-by: Aiden Cline <aidenpcline@gmail.com>

packages/ai/src/providers/cloudflare-workers-ai.ts

@@ -0,0 +1,19 @@
+import type { ProviderPackage } from "../provider-package"
+import type { OpenAIProviderOptionsInput } from "./openai-options"
+import { CloudflareWorkersAI } from "./cloudflare"
+
+export interface Settings extends ProviderPackage.Settings {
+  readonly accountId?: string
+  readonly apiKey?: string
+  readonly providerOptions?: OpenAIProviderOptionsInput
+}
+
+export const model: ProviderPackage.Definition<Settings>["model"] = (modelID, settings) =>
+  CloudflareWorkersAI.configure({
+    ...(typeof settings.baseURL === "string" ? { baseURL: settings.baseURL } : { accountId: settings.accountId ?? "" }),
+    apiKey: settings.apiKey,
+    headers: settings.headers === undefined ? undefined : { ...settings.headers },
+    http: settings.body === undefined ? undefined : { body: { ...settings.body } },
+    limits: settings.limits,
+    providerOptions: settings.providerOptions,
+  }).model(modelID)

packages/ai/test/provider/cloudflare-workers-ai.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, test } from "bun:test"
+import { model } from "../../src/providers/cloudflare-workers-ai"
+
+describe("Cloudflare Workers AI provider package", () => {
+  test("derives the endpoint from accountId", () => {
+    const resolved = model("@cf/model", { accountId: "account", apiKey: "secret" })
+
+    expect(resolved.route.endpoint.baseURL).toBe("https://api.cloudflare.com/client/v4/accounts/account/ai/v1")
+  })
+
+  test("preserves an explicit endpoint", () => {
+    const resolved = model("@cf/model", { baseURL: "https://proxy.example/v1", apiKey: "secret" })
+
+    expect(resolved.route.endpoint.baseURL).toBe("https://proxy.example/v1")
+  })
+})

packages/app/src/pages/session/timeline/observe-element-offset.test.ts

@@ -1,6 +1,6 @@
 import { expect, test } from "bun:test"
 import { type Virtualizer } from "@tanstack/solid-virtual"
-import { Window } from "happy-dom"
+import { Node, Window } from "happy-dom"
 import { mutationNodesContainElement, observeElementOffsetReconnectAware } from "./observe-element-offset"
 
 test("matches only the scroll element or an ancestor containing it", () => {
@@ -18,6 +18,7 @@ test("matches only the scroll element or an ancestor containing it", () => {
 
 test("reports a divergent native offset once and ignores equal offsets and unrelated mutations", async () => {
   const targetWindow = new Window()
+  const mutations = controlledMutations(targetWindow)
   const route = targetWindow.document.createElement("section")
   const viewport = targetWindow.document.createElement("div")
   const unrelated = targetWindow.document.createElement("div")
@@ -40,24 +41,24 @@ test("reports a divergent native offset once and ignores equal offsets and unrel
     instance.scrollOffset = offset
   })
 
-  targetWindow.document.body.append(unrelated)
-  unrelated.remove()
-  await frames(2, targetWindow)
-  expect(calls).toEqual([])
+  try {
+    mutations.append(targetWindow.document.body, unrelated)
+    mutations.remove(unrelated)
+    expect(calls).toEqual([])
 
-  route.remove()
-  targetWindow.document.body.append(route)
-  await waitFor(() => calls.length === 1, targetWindow)
-  expect(calls).toEqual([[0, false]])
+    mutations.remove(route)
+    mutations.append(targetWindow.document.body, route)
+    await frames(2, targetWindow)
+    expect(calls).toEqual([[0, false]])
 
-  route.remove()
-  targetWindow.document.body.append(route)
-  await new Promise((resolve) => setTimeout(resolve, 0))
-  await frames(3, targetWindow)
-  expect(calls).toEqual([[0, false]])
-
-  cleanup?.()
-  await targetWindow.happyDOM.close()
+    mutations.remove(route)
+    mutations.append(targetWindow.document.body, route)
+    await frames(2, targetWindow)
+    expect(calls).toEqual([[0, false]])
+  } finally {
+    cleanup?.()
+    await targetWindow.happyDOM.close()
+  }
 })
 
 test("keeps checking until stale reset-delay callbacks can no longer win", async () => {
@@ -204,7 +205,33 @@ async function frames(count: number, targetWindow: FrameWindow = window) {
   }
 }
 
-async function waitFor(condition: () => boolean, targetWindow: FrameWindow = window) {
-  const deadline = targetWindow.performance.now() + 1_000
-  while (!condition() && targetWindow.performance.now() < deadline) await frames(1, targetWindow)
+function controlledMutations(targetWindow: Window) {
+  let emit: (record: MutationRecord) => void = () => {
+    throw new Error("Mutation observer is not active")
+  }
+  class ControlledMutationObserver {
+    constructor(callback: MutationCallback) {
+      emit = (record) => callback([record], this as unknown as MutationObserver)
+    }
+    observe() {}
+    disconnect() {}
+    takeRecords() {
+      return []
+    }
+  }
+  Object.defineProperty(targetWindow, "MutationObserver", { value: ControlledMutationObserver })
+  const record = (target: Node, addedNodes: Node[], removedNodes: Node[]) =>
+    ({ type: "childList", target, addedNodes, removedNodes }) as unknown as MutationRecord
+  return {
+    append(parent: Node, node: Node) {
+      parent.appendChild(node)
+      emit(record(parent, [node], []))
+    },
+    remove(node: Node) {
+      const parent = node.parentNode
+      if (!parent) throw new Error("Mutation target has no parent")
+      parent.removeChild(node)
+      emit(record(parent, [], [node]))
+    },
+  }
 }

packages/core/src/config/plugin/skill-file.ts

@@ -1,57 +0,0 @@
-export * as SkillFile from "./skill-file"
-
-import path from "path"
-import { Result, Schema, type SchemaIssue, SchemaParser } from "effect"
-import { ConfigMarkdown } from "../markdown"
-import { AbsolutePath } from "../../schema"
-import { Skill } from "../../skill"
-
-const Frontmatter = Schema.Struct({
-  name: Schema.String.pipe(Schema.optional),
-  description: Schema.String.pipe(Schema.optional),
-  slash: Schema.Boolean.pipe(Schema.optional),
-  metadata: Schema.Unknown.pipe(Schema.optional),
-})
-const decodeFrontmatter = SchemaParser.decodeUnknownResult(Frontmatter)
-
-export type ParseResult =
-  | { readonly _tag: "Parsed"; readonly skill: Skill.Info }
-  | { readonly _tag: "Skipped"; readonly reason: "markdown" }
-  | { readonly _tag: "Skipped"; readonly reason: "frontmatter"; readonly issue: SchemaIssue.Issue }
-
-const metadataBoolean = (metadata: unknown, key: string) => {
-  if (metadata === undefined || metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
-    return undefined
-  }
-  const value = Reflect.get(metadata, key)
-  if (typeof value === "boolean") return value
-  if (typeof value !== "string") return undefined
-  const normalized = value.trim().toLowerCase()
-  if (normalized === "true") return true
-  if (normalized === "false") return false
-  return undefined
-}
-
-export function parse(directory: string, filepath: string, content: string): ParseResult {
-  const markdown = ConfigMarkdown.parseOption(content)
-  if (!markdown) return { _tag: "Skipped", reason: "markdown" }
-  const decoded = decodeFrontmatter(markdown.data)
-  if (Result.isFailure(decoded)) return { _tag: "Skipped", reason: "frontmatter", issue: decoded.failure }
-  const frontmatter = decoded.success
-  const id =
-    path.dirname(filepath) === directory ? path.basename(filepath, ".md") : path.basename(path.dirname(filepath))
-  const slash = metadataBoolean(frontmatter.metadata, "opencode/slash") ?? frontmatter.slash
-  const autoinvoke = metadataBoolean(frontmatter.metadata, "opencode/autoinvoke")
-  return {
-    _tag: "Parsed",
-    skill: {
-      id: Skill.ID.make(id),
-      name: Skill.Name.make(frontmatter.name ?? id),
-      ...(frontmatter.description === undefined ? {} : { description: frontmatter.description }),
-      ...(slash === undefined ? {} : { slash }),
-      ...(autoinvoke === undefined ? {} : { autoinvoke }),
-      location: AbsolutePath.make(filepath),
-      content: markdown.content,
-    },
-  }
-}

packages/core/src/config/plugin/skill.ts

@@ -1,191 +1,64 @@
 export * as ConfigSkillPlugin from "./skill"
 
 import { define } from "@opencode-ai/plugin/effect/plugin"
-import type { Entry } from "@opencode-ai/schema/config"
-import { FSUtil } from "@opencode-ai/util/fs-util"
-import { Global } from "@opencode-ai/util/global"
 import path from "path"
-import { Effect, FiberMap, PubSub, Semaphore, Stream } from "effect"
+import { Effect, Stream } from "effect"
 import { Config } from "../../config"
-import { Watcher } from "../../filesystem/watcher"
-import { Location } from "../../location"
 import { AbsolutePath } from "../../schema"
 import { Skill } from "../../skill"
-import { SkillDiscovery } from "../../skill/discovery"
-import { SkillFile } from "./skill-file"
-
-type Source = Skill.DirectorySource | Skill.UrlSource
+import { Global } from "@opencode-ai/util/global"
+import { Location } from "../../location"
 
 export const Plugin = define({
   id: "opencode.config.skill",
   effect: Effect.fn(function* (ctx) {
     const config = yield* Config.Service
-    const discovery = yield* SkillDiscovery.Service
-    const fs = yield* FSUtil.Service
     const global = yield* Global.Service
     const location = yield* Location.Service
-    const watcher = yield* Watcher.Service
-    const loaded: { entries: Entry[]; skills: Skill.Info[] } = {
-      entries: yield* config.entries(),
-      skills: [],
-    }
-    const watches = yield* FiberMap.make<string>()
-    const changes = yield* PubSub.sliding<string>(1)
-    const lock = Semaphore.makeUnsafe(1)
-
-    const watch = Effect.fn("ConfigSkillPlugin.watch")(function* (directory: string, type: Watcher.WatchInput["type"]) {
-      const target = path.resolve(directory)
-      const updates = yield* watcher.subscribe({ path: target, type })
-      yield* FiberMap.run(
-        watches,
-        `${type}:${target}`,
-        updates.pipe(Stream.runForEach((update) => PubSub.publish(changes, update.path).pipe(Effect.asVoid))),
-        { onlyIfMissing: true, startImmediately: true },
-      )
-    })
-
-    function firstMissing(target: string): Effect.Effect<string | undefined> {
-      const parent = path.dirname(target)
-      if (parent === target) return Effect.succeed(undefined)
-      return fs.isDir(parent).pipe(Effect.flatMap((exists) => (exists ? Effect.succeed(target) : firstMissing(parent))))
-    }
-
-    const watchDirectory: (directory: string) => Effect.Effect<string[]> = Effect.fn(
-      "ConfigSkillPlugin.watchDirectory",
-    )(function* (directory: string) {
-      const target = path.resolve(directory)
-      const resolved = yield* fs.realPath(directory).pipe(Effect.catch(() => Effect.succeed(undefined)))
-      if (resolved) {
-        yield* watch(resolved, "directory")
-        if (resolved !== target) yield* watch(target, "file")
-        return resolved === target ? [target] : [target, resolved]
-      }
-      const missing = yield* firstMissing(target)
-      if (missing) yield* watch(missing, "file")
-      if (
-        yield* fs.realPath(directory).pipe(
-          Effect.as(true),
-          Effect.catch(() => Effect.succeed(false)),
-        )
-      ) {
-        if (missing) yield* FiberMap.remove(watches, `file:${path.resolve(missing)}`)
-        return yield* watchDirectory(directory)
-      }
-      return [target]
-    })
-
-    const sources = () => {
-      const result: Source[] = []
-      const add = (source: Source) => {
-        if (result.some((item) => Skill.Source.equals(item, source))) return
-        result.push(source)
-      }
+    const loaded = { entries: yield* config.entries() }
+    yield* ctx.skill.transform((draft) => {
       const claude = loaded.entries.flatMap((entry) => (entry.type === "claude" ? [entry.path] : []))
       const agents = loaded.entries.flatMap((entry) => (entry.type === "agents" ? [entry.path] : []))
       const directories = loaded.entries.flatMap((entry) => (entry.type === "directory" ? [entry.path] : []))
       const items = loaded.entries.flatMap((entry) => (entry.type === "document" ? (entry.info.skills ?? []) : []))
       for (const directory of [...claude, ...agents]) {
-        add(Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make(path.join(directory, "skills")) }))
+        draft.source(
+          Skill.DirectorySource.make({
+            type: "directory",
+            path: AbsolutePath.make(path.join(directory, "skills")),
+          }),
+        )
       }
       for (const directory of directories) {
-        add(Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make(path.join(directory, "skill")) }))
-        add(Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make(path.join(directory, "skills")) }))
+        draft.source(
+          Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make(path.join(directory, "skill")) }),
+        )
+        draft.source(
+          Skill.DirectorySource.make({
+            type: "directory",
+            path: AbsolutePath.make(path.join(directory, "skills")),
+          }),
+        )
       }
       for (const item of items) {
         if (URL.canParse(item) && /^(https?:)$/.test(new URL(item).protocol)) {
-          add(Skill.UrlSource.make({ type: "url", url: item }))
+          draft.source(Skill.UrlSource.make({ type: "url", url: item }))
           continue
         }
         const expanded = item.startsWith("~/") ? path.join(global.home, item.slice(2)) : item
-        add(
+        draft.source(
           Skill.DirectorySource.make({
             type: "directory",
             path: AbsolutePath.make(path.isAbsolute(expanded) ? expanded : path.join(location.directory, expanded)),
           }),
         )
       }
-      return result
-    }
-
-    const load = Effect.fn("ConfigSkillPlugin.load")(function* (source: Source) {
-      const directories =
-        source.type === "directory"
-          ? [source.path]
-          : yield* discovery.pull(source.url).pipe(
-              Effect.catchCause((cause) =>
-                Effect.logWarning("failed to load skill source", {
-                  source: Skill.Source.key(source),
-                  cause,
-                }).pipe(Effect.as([] as AbsolutePath[])),
-              ),
-            )
-      const roots = (yield* Effect.forEach(directories, watchDirectory)).flat()
-      const skills: Skill.Info[] = []
-      for (const directory of directories) {
-        const files = yield* fs
-          .scan("{*.md,**/SKILL.md}", { cwd: directory, absolute: true, include: "file", symlink: true, dot: true })
-          .pipe(Effect.catch(() => Effect.succeed([] as string[])))
-        for (const filepath of files.toSorted()) {
-          const resolved = yield* fs.realPath(filepath).pipe(Effect.catch(() => Effect.succeed(filepath)))
-          if (!roots.some((root) => FSUtil.contains(root, resolved))) yield* watch(path.dirname(resolved), "directory")
-          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
-          if (!content) continue
-          const parsed = SkillFile.parse(directory, filepath, content)
-          if (parsed._tag === "Skipped") {
-            yield* Effect.logDebug("skill file skipped", {
-              filepath,
-              reason: parsed.reason,
-              ...(parsed.reason === "frontmatter" ? { issue: parsed.issue } : {}),
-            })
-            continue
-          }
-          skills.push(parsed.skill)
-        }
-      }
-      yield* Effect.logDebug("skill source loaded", {
-        source: Skill.Source.key(source),
-        type: source.type,
-        directories,
-        skills: skills.map((skill) => skill.id),
-      })
-      return skills
-    })
-
-    const refresh = Effect.fn("ConfigSkillPlugin.refresh")(function* (file?: string) {
-      yield* lock.withPermit(
-        Effect.gen(function* () {
-          yield* FiberMap.clear(watches)
-          const skills = new Map<Skill.ID, Skill.Info>()
-          const current = sources()
-          for (const source of current) {
-            for (const skill of yield* load(source)) skills.set(skill.id, skill)
-          }
-          loaded.skills = Array.from(skills.values())
-          if (file) {
-            yield* Effect.logInfo("skills rescanned", {
-              file,
-              sources: current.map(Skill.Source.key),
-              skills: loaded.skills.map((skill) => skill.id),
-            })
-          }
-        }),
-      )
-    })
-
-    yield* Stream.fromPubSub(changes).pipe(
-      Stream.runForEach((file) => refresh(file).pipe(Effect.andThen(ctx.skill.reload()))),
-      Effect.forkScoped({ startImmediately: true }),
-    )
-    yield* refresh()
-    yield* ctx.skill.transform((draft) => {
-      for (const skill of loaded.skills) draft.add(skill)
     })
     yield* ctx.event.subscribe().pipe(
       Stream.filter((event) => event.type === "config.updated"),
       Stream.runForEach(() =>
         config.entries().pipe(
           Effect.tap((entries) => Effect.sync(() => (loaded.entries = entries))),
-          Effect.andThen(refresh()),
           Effect.andThen(ctx.skill.reload()),
         ),
       ),

packages/core/src/plugin/host.ts

@@ -290,10 +290,8 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: import("../p
       transform: (callback) =>
         skill.transform((draft) => {
           callback({
-            list: () => mutable(draft.list()),
-            add: (value) => draft.add(Schema.decodeUnknownSync(Skill.Info)(value)),
-            update: draft.update,
-            remove: draft.remove,
+            source: (source) => draft.source(Schema.decodeUnknownSync(Skill.Source)(source)),
+            list: draft.list,
           })
         }),
     },

packages/core/src/plugin/internal.ts

@@ -37,8 +37,6 @@ import { Ripgrep } from "../ripgrep"
 import { SessionInstructions } from "../session/instructions"
 import { Shell } from "../shell"
 import { Skill } from "../skill"
-import { SkillDiscovery } from "../skill/discovery"
-import { Watcher } from "../filesystem/watcher"
 import { PatchTool } from "../tool/plugin/patch"
 import { EditTool } from "../tool/plugin/edit"
 import { GlobTool } from "../tool/plugin/glob"
@@ -97,9 +95,7 @@ const services = Effect.fn("PluginInternal.services")(function* () {
   const instructions = yield* SessionInstructions.Service
   const shell = yield* Shell.Service
   const skill = yield* Skill.Service
-  const skillDiscovery = yield* SkillDiscovery.Service
   const tools = yield* Tool.Service
-  const watcher = yield* Watcher.Service
   const wellknown = yield* WellKnown.Service
   return Context.mergeAll(
     Context.make(Agent.Service, agent),
@@ -132,9 +128,7 @@ const services = Effect.fn("PluginInternal.services")(function* () {
     Context.make(SessionInstructions.Service, instructions),
     Context.make(Shell.Service, shell),
     Context.make(Skill.Service, skill),
-    Context.make(SkillDiscovery.Service, skillDiscovery),
     Context.make(Tool.Service, tools),
-    Context.make(Watcher.Service, watcher),
     Context.make(WellKnown.Service, wellknown),
   )
 })

packages/core/src/plugin/provider/cloudflare-workers-ai.ts

@@ -8,13 +8,14 @@ import { iife } from "../../util/iife"
 import { configuredSettings } from "./configured"
 
 const providerID = Provider.ID.make("cloudflare-workers-ai")
+const nativePackage = "@opencode-ai/ai/providers/cloudflare-workers-ai"
 
 export const CloudflareWorkersAIPlugin = define({
   id: "opencode.provider.cloudflare-workers-ai",
   effect: Effect.fn(function* (ctx) {
     const configured = yield* configuredSettings(providerID)
     const form = iife(() => {
-      if (typeof configured?.baseURL === "string" || resolveAccountId(configured ?? {})) return
+      if (hasExplicitEndpoint(configured?.baseURL) || resolveAccountId(configured ?? {})) return
       return Form.Fields.make([
         {
           type: "string",
@@ -38,12 +39,24 @@ export const CloudflareWorkersAIPlugin = define({
     yield* ctx.catalog.transform((evt) => {
       const item = evt.provider.get(providerID)
       if (!item) return
+      const compatible =
+        Provider.isAISDK(item.provider.package) &&
+        Provider.packageName(item.provider.package) === "@ai-sdk/openai-compatible"
       evt.provider.update(item.provider.id, (provider) => {
-        if (!Provider.isAISDK(provider.package)) return
-        if (typeof provider.settings?.baseURL === "string") return
-        const accountId = resolveAccountId(provider.settings ?? {})
-        if (accountId) provider.settings = { ...provider.settings, baseURL: workersEndpoint(accountId) }
+        if (!compatible) return
+        provider.package = nativePackage
+        provider.settings = nativeSettings(provider.settings)
       })
+      for (const model of item.models.values()) {
+        evt.model.update(item.provider.id, model.id, (draft) => {
+          if (!draft.package && !compatible) return
+          if (draft.package === nativePackage) return
+          if (draft.package && !Provider.isAISDK(draft.package)) return
+          if (draft.package && Provider.packageName(draft.package) !== "@ai-sdk/openai-compatible") return
+          if (draft.package) draft.package = nativePackage
+          draft.settings = nativeSettings(draft.settings)
+        })
+      }
     })
     yield* ctx.aisdk.hook(
       "sdk",
@@ -83,6 +96,17 @@ function workersEndpoint(accountId: string) {
   return `https://api.cloudflare.com/client/v4/accounts/${accountId}/ai/v1`
 }
 
+function hasExplicitEndpoint(baseURL: unknown) {
+  return typeof baseURL === "string" && !baseURL.includes("${CLOUDFLARE_ACCOUNT_ID}")
+}
+
+function nativeSettings(settings: Record<string, unknown> | undefined) {
+  const result = { ...settings }
+  if (process.env.CLOUDFLARE_ACCOUNT_ID) result.baseURL = workersEndpoint(process.env.CLOUDFLARE_ACCOUNT_ID)
+  else if (!hasExplicitEndpoint(result.baseURL)) delete result.baseURL
+  return result
+}
+
 function hasWorkersEndpoint(model: {
   readonly package?: string
   readonly settings?: Readonly<Record<string, unknown>>
@@ -93,7 +117,7 @@ function hasWorkersEndpoint(model: {
 function sdkOptions(options: Record<string, any>, app: App.Info) {
   return {
     ...options,
-    baseURL: expandAccountId(options.baseURL),
+    baseURL: expandAccountId(options.baseURL, resolveAccountId(options)),
     apiKey: process.env.CLOUDFLARE_API_KEY ?? options.apiKey,
     headers: {
       "User-Agent": `${App.useragent(app)} cloudflare-workers-ai (${os.platform()} ${os.release()}; ${os.arch()})`,
@@ -103,9 +127,9 @@ function sdkOptions(options: Record<string, any>, app: App.Info) {
   }
 }
 
-function expandAccountId(baseURL: unknown) {
+function expandAccountId(baseURL: unknown, accountId: string | undefined) {
   if (typeof baseURL !== "string") return baseURL
-  return baseURL.replaceAll("${CLOUDFLARE_ACCOUNT_ID}", process.env.CLOUDFLARE_ACCOUNT_ID ?? "${CLOUDFLARE_ACCOUNT_ID}")
+  return baseURL.replaceAll("${CLOUDFLARE_ACCOUNT_ID}", accountId ?? "${CLOUDFLARE_ACCOUNT_ID}")
 }
 
 function stringOption(options: Record<string, unknown>, key: string) {

packages/core/src/plugin/skill.ts

@@ -28,23 +28,29 @@ export const Plugin = define({
   effect: Effect.fn(function* (ctx) {
     const reportContent = yield* reportContentWithDiagnostics(ctx.app)
     yield* ctx.skill.transform((draft) => {
-      draft.add(
-        Skill.Info.make({
-          id: Skill.ID.make("opencode"),
-          name: Skill.Name.make("OpenCode"),
-          description: OpencodeDescription,
-          location: AbsolutePath.make("/builtin/opencode.md"),
-          content: OpencodeContent,
+      draft.source(
+        Skill.EmbeddedSource.make({
+          type: "embedded",
+          skill: Skill.Info.make({
+            id: Skill.ID.make("opencode"),
+            name: Skill.Name.make("OpenCode"),
+            description: OpencodeDescription,
+            location: AbsolutePath.make("/builtin/opencode.md"),
+            content: OpencodeContent,
+          }),
         }),
       )
-      draft.add(
-        Skill.Info.make({
-          id: Skill.ID.make("report"),
-          name: Skill.Name.make("Report"),
-          description: REPORT_DESCRIPTION,
-          slash: true,
-          location: AbsolutePath.make("/builtin/report.md"),
-          content: reportContent,
+      draft.source(
+        Skill.EmbeddedSource.make({
+          type: "embedded",
+          skill: Skill.Info.make({
+            id: Skill.ID.make("report"),
+            name: Skill.Name.make("Report"),
+            description: REPORT_DESCRIPTION,
+            slash: true,
+            location: AbsolutePath.make("/builtin/report.md"),
+            content: reportContent,
+          }),
         }),
       )
     })

packages/core/src/plugin/supervisor.ts

@@ -37,7 +37,6 @@ import { Ripgrep } from "../ripgrep"
 import { SessionInstructions } from "../session/instructions"
 import { Shell } from "../shell"
 import { Skill } from "../skill"
-import { SkillDiscovery } from "../skill/discovery"
 import { ReadToolFileSystem } from "../tool/read-filesystem"
 import { Tool } from "../tool"
 import { WebSearch } from "../websearch"
@@ -353,7 +352,6 @@ export const node = makeLocationNode({
     SessionInstructions.node,
     Shell.node,
     Skill.node,
-    SkillDiscovery.node,
     Tool.node,
     Watcher.node,
     WebSearch.node,

packages/core/src/skill.ts

@@ -2,12 +2,17 @@ export * as Skill from "./skill"
 
 import { makeLocationNode } from "@opencode-ai/util/effect/app-node"
 import path from "path"
-import { Context, Effect, Layer, Types } from "effect"
+import { Context, Effect, FiberMap, Layer, PubSub, Schema, Semaphore, Stream, Types } from "effect"
 import { Skill } from "@opencode-ai/schema/skill"
 import { Agent } from "./agent"
+import { ConfigMarkdown } from "./config/markdown"
 import { Bus } from "./bus"
+import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Permission } from "./permission"
+import { AbsolutePath } from "./schema"
+import { SkillDiscovery } from "./skill/discovery"
 import { State } from "./state"
+import { Watcher } from "./filesystem/watcher"
 
 export const DirectorySource = Skill.DirectorySource
 export type DirectorySource = Skill.DirectorySource
@@ -52,18 +57,38 @@ export const toModelOutput = (skill: Info, files: ReadonlyArray<string>) => {
   ].join("\n")
 }
 
+const Frontmatter = Schema.Struct({
+  name: Schema.String.pipe(Schema.optional),
+  description: Schema.String.pipe(Schema.optional),
+  slash: Schema.Boolean.pipe(Schema.optional),
+  metadata: Schema.Unknown.pipe(Schema.optional),
+})
+const decodeFrontmatter = Schema.decodeUnknownOption(Frontmatter)
+
+const metadataBoolean = (metadata: unknown, key: string) => {
+  if (metadata === undefined || metadata === null || typeof metadata !== "object" || Array.isArray(metadata)) {
+    return undefined
+  }
+  const value = (metadata as { readonly [key: string]: unknown })[key]
+  if (typeof value === "boolean") return value
+  if (typeof value !== "string") return undefined
+  const normalized = value.trim().toLowerCase()
+  if (normalized === "true") return true
+  if (normalized === "false") return false
+  return undefined
+}
+
 export type Data = {
-  skills: Map<ID, Types.DeepMutable<Info>>
+  sources: Types.DeepMutable<Source>[]
 }
 
 export type Draft = {
-  list: () => readonly Types.DeepMutable<Info>[]
-  add: (skill: Info) => void
-  update: (id: string, update: (skill: Types.DeepMutable<Info>) => void) => void
-  remove: (id: string) => void
+  source: (source: Source) => void
+  list: () => readonly Source[]
 }
 
 export interface Interface extends State.Transformable<Draft> {
+  readonly sources: () => Effect.Effect<Source[]>
   readonly list: () => Effect.Effect<Info[]>
 }
 
@@ -72,35 +97,179 @@ export class Service extends Context.Service<Service, Interface>()("@opencode/Sk
 const layer = Layer.effect(
   Service,
   Effect.gen(function* () {
+    const discovery = yield* SkillDiscovery.Service
+    const fs = yield* FSUtil.Service
     const bus = yield* Bus.Service
+    const watcher = yield* Watcher.Service
+    const cache = new Map<string, { skills: Info[]; paths: readonly string[] }>()
+    const watches = yield* FiberMap.make<string>()
+    const lock = Semaphore.makeUnsafe(1)
+    const changes = yield* PubSub.unbounded<string>()
+
+    const invalidate = Effect.fn("Skill.invalidateFromWatcher")(function* (file: string) {
+      const changed = yield* lock.withPermit(
+        Effect.gen(function* () {
+          const invalidated = Array.from(cache.entries()).filter(([, loaded]) =>
+            loaded.paths.some((item) => FSUtil.overlaps(item, file)),
+          )
+          if (invalidated.length === 0) return false
+          cache.clear()
+          yield* FiberMap.clear(watches)
+          yield* Effect.logInfo("skill cache invalidated", {
+            file,
+            sources: invalidated.map(([key]) => key),
+            skills: invalidated.flatMap(([, loaded]) => loaded.skills.map((skill) => skill.id)),
+          })
+          return true
+        }),
+      )
+      if (!changed) return
+      yield* bus.publish(Skill.Event.Updated, {}).pipe(Effect.asVoid)
+    })
+
+    yield* Stream.fromPubSub(changes).pipe(Stream.runForEach(invalidate), Effect.forkScoped({ startImmediately: true }))
+
+    const watch = Effect.fn("Skill.watch")(function* (directory: string, type: Watcher.WatchInput["type"]) {
+      const target = path.resolve(directory)
+      const updates = yield* watcher.subscribe(
+        type === "file" ? { path: target, type: "file" } : { path: target, type: "directory" },
+      )
+      yield* FiberMap.run(
+        watches,
+        `${type}:${target}`,
+        updates.pipe(Stream.runForEach((update) => PubSub.publish(changes, update.path).pipe(Effect.asVoid))),
+        {
+          onlyIfMissing: true,
+          startImmediately: true,
+        },
+      )
+    })
+
+    function firstMissing(target: string): Effect.Effect<string | undefined> {
+      const parent = path.dirname(target)
+      if (parent === target) return Effect.succeed(undefined)
+      return fs.isDir(parent).pipe(Effect.flatMap((exists) => (exists ? Effect.succeed(target) : firstMissing(parent))))
+    }
+
+    const watchDirectory: (directory: string) => Effect.Effect<string[]> = Effect.fn("Skill.watchDirectory")(function* (
+      directory: string,
+    ) {
+      const target = path.resolve(directory)
+      const resolved = yield* fs.realPath(directory).pipe(Effect.catch(() => Effect.succeed(undefined)))
+      if (resolved) {
+        yield* watch(resolved, "directory")
+        if (resolved !== target) {
+          yield* watch(target, "file")
+        }
+        return resolved === target ? [target] : [target, resolved]
+      }
+      const missing = yield* firstMissing(target)
+      if (missing) yield* watch(missing, "file")
+      if (
+        yield* fs.realPath(directory).pipe(
+          Effect.as(true),
+          Effect.catch(() => Effect.succeed(false)),
+        )
+      ) {
+        if (missing) yield* FiberMap.remove(watches, `file:${path.resolve(missing)}`)
+        return yield* watchDirectory(directory)
+      }
+      return [target]
+    })
 
     const state = State.create<Data, Draft>({
       name: "skill",
-      initial: () => ({ skills: new Map() }),
+      initial: () => ({ sources: [] }),
       draft: (draft) => ({
-        list: () => Array.from(draft.skills.values()),
-        add: (skill) => {
-          draft.skills.set(skill.id, { ...skill } as Types.DeepMutable<Info>)
-        },
-        update: (id, update) => {
-          const current = draft.skills.get(ID.make(id))
-          if (!current) return
-          update(current)
-          current.id = ID.make(id)
-        },
-        remove: (id) => {
-          draft.skills.delete(ID.make(id))
+        source: (source) => {
+          if (draft.sources.some((item) => Source.equals(item, source))) return
+          draft.sources.push(source as Types.DeepMutable<Source>)
         },
+        list: () => draft.sources as Source[],
       }),
-      finalize: () => bus.publish(Skill.Event.Updated, {}).pipe(Effect.asVoid),
+      finalize: () =>
+        lock
+          .withPermit(FiberMap.clear(watches).pipe(Effect.andThen(Effect.sync(() => cache.clear())), Effect.asVoid))
+          .pipe(Effect.andThen(bus.publish(Skill.Event.Updated, {})), Effect.asVoid),
+    })
+
+    const load = Effect.fn("Skill.load")(function* (source: Source) {
+      const skills: Info[] = []
+      if (source.type === "embedded") {
+        yield* Effect.logDebug("skill source loaded", {
+          source: Source.key(source),
+          type: source.type,
+          directories: [],
+          skills: [source.skill.id],
+        })
+        return { skills: [source.skill], paths: [] }
+      }
+      const directories = source.type === "directory" ? [source.path] : yield* discovery.pull(source.url)
+      const roots = (yield* Effect.forEach(directories, watchDirectory)).flat()
+      const paths = [...roots]
+      for (const directory of directories) {
+        const files = yield* fs
+          .scan("{*.md,**/SKILL.md}", { cwd: directory, absolute: true, include: "file", symlink: true, dot: true })
+          .pipe(Effect.catch(() => Effect.succeed([] as string[])))
+        for (const filepath of files.toSorted()) {
+          const resolved = yield* fs.realPath(filepath).pipe(Effect.catch(() => Effect.succeed(filepath)))
+          if (!roots.some((root) => FSUtil.contains(root, resolved))) {
+            const external = path.dirname(resolved)
+            paths.push(external)
+            yield* watch(external, "directory")
+          }
+          const content = yield* fs.readFileStringSafe(filepath).pipe(Effect.catch(() => Effect.succeed(undefined)))
+          if (!content) continue
+          const markdown = ConfigMarkdown.parseOption(content)
+          if (!markdown) continue
+          const frontmatter = decodeFrontmatter(markdown.data).valueOrUndefined
+          if (!frontmatter) continue
+          const id =
+            path.dirname(filepath) === directory
+              ? path.basename(filepath, ".md")
+              : path.basename(path.dirname(filepath))
+          skills.push({
+            id: ID.make(id),
+            name: Name.make(frontmatter.name ?? id),
+            description: frontmatter.description,
+            slash: metadataBoolean(frontmatter.metadata, "opencode/slash") ?? frontmatter.slash,
+            autoinvoke: metadataBoolean(frontmatter.metadata, "opencode/autoinvoke"),
+            location: AbsolutePath.make(filepath),
+            content: markdown.content,
+          })
+        }
+      }
+      yield* Effect.logDebug("skill source loaded", {
+        source: Source.key(source),
+        type: source.type,
+        directories,
+        skills: skills.map((skill) => skill.id),
+      })
+      return { skills, paths }
+    })
+
+    const list = Effect.fn("Skill.list")(function* () {
+      return yield* lock.withPermit(
+        Effect.gen(function* () {
+          const skills = new Map<ID, Info>()
+          for (const source of state.get().sources) {
+            const key = Source.key(source)
+            const loaded = cache.get(key) ?? (yield* load(source))
+            cache.set(key, loaded)
+            for (const skill of loaded.skills) skills.set(skill.id, skill)
+          }
+          return Array.from(skills.values())
+        }),
+      )
     })
 
     return Service.of({
       transform: state.transform,
       reload: state.reload,
-      list: Effect.fn("Skill.list")(function* () {
-        return Array.from(state.get().skills.values())
+      sources: Effect.fn("Skill.sources")(function* () {
+        return state.get().sources
       }),
+      list,
     })
   }),
 )
@@ -108,5 +277,5 @@ const layer = Layer.effect(
 export const node = makeLocationNode({
   service: Service,
   layer,
-  deps: [Bus.node],
+  deps: [SkillDiscovery.node, FSUtil.node, Bus.node, Watcher.node],
 })

packages/core/test/config/fixture/skills/first-source/first/SKILL.md

@@ -1,5 +0,0 @@
----
-name: first
-description: First skill
----
-# first

packages/core/test/config/fixture/skills/second-source/second/SKILL.md

@@ -1,5 +0,0 @@
----
-name: second
-description: Second skill
----
-# second

packages/core/test/config/reload.test.ts

@@ -46,7 +46,9 @@ describe("config plugin reloads", () => {
 
       expect((yield* agents.get(Agent.ID.make("first")))?.description).toBe("First agent")
       expect((yield* commands.get("first"))?.description).toBe("First command")
-      expect((yield* skills.list()).some((skill) => skill.id === "first")).toBe(true)
+      expect(
+        (yield* skills.sources()).some((source) => source.type === "directory" && source.path === "/skills/first"),
+      ).toBe(true)
       expect((yield* references.list()).map((reference) => reference.name)).toEqual(["first"])
       expect(yield* catalog.provider.get(Provider.ID.make("first"))).toBeDefined()
 
@@ -67,8 +69,12 @@ describe("config plugin reloads", () => {
         }),
       )
 
-      expect((yield* skills.list()).some((skill) => skill.id === "first")).toBe(false)
-      expect((yield* skills.list()).some((skill) => skill.id === "second")).toBe(true)
+      expect(
+        (yield* skills.sources()).some((source) => source.type === "directory" && source.path === "/skills/first"),
+      ).toBe(false)
+      expect(
+        (yield* skills.sources()).some((source) => source.type === "directory" && source.path === "/skills/second"),
+      ).toBe(true)
     }).pipe(
       Effect.provide(Config.testLayer([config("first")])),
       Effect.provideService(Global.Service, Global.Service.of(Global.make())),
@@ -83,7 +89,7 @@ function config(name: string) {
     info: decode({
       agents: { [name]: { description: `${title(name)} agent`, mode: "subagent" } },
       commands: { [name]: { template: `${title(name)} command`, description: `${title(name)} command` } },
-      skills: [path.join(import.meta.dir, "fixture", "skills", `${name}-source`)],
+      skills: [`/skills/${name}`],
       references: { [name]: `/references/${name}` },
       providers: { [name]: { models: { chat: { name: `${title(name)} model` } } } },
     }),

packages/core/test/config/skill.test.ts

@@ -1,252 +1,87 @@
-import fs from "fs/promises"
 import path from "path"
 import { describe, expect } from "bun:test"
-import { Deferred, Effect, Fiber, Layer, Schema, Stream } from "effect"
+import { Effect, Layer, Schema, Stream } from "effect"
 import { Config } from "@opencode-ai/core/config"
-import { Document, Info } from "@opencode-ai/schema/config"
+import { AgentsDirectory, ClaudeDirectory, Directory, Document, Info } from "@opencode-ai/schema/config"
 import { ConfigSkillPlugin } from "@opencode-ai/core/config/plugin/skill"
-import { SkillFile } from "@opencode-ai/core/config/plugin/skill-file"
-import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
-import { Watcher } from "@opencode-ai/core/filesystem/watcher"
-import { Bus } from "@opencode-ai/core/bus"
-import { FSUtil } from "@opencode-ai/util/fs-util"
 import { Global } from "@opencode-ai/util/global"
-import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Location } from "@opencode-ai/core/location"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { Skill } from "@opencode-ai/core/skill"
-import { SkillDiscovery } from "@opencode-ai/core/skill/discovery"
-import { tmpdir } from "../fixture/tmpdir"
 import { location } from "../fixture/location"
 import { testEffect } from "../lib/effect"
 import { host } from "../plugin/host"
 
-const urls = new Map<string, AbsolutePath[]>()
-const failedUrls = new Set<string>()
-let pulls = 0
-const discoveryLayer = Layer.succeed(
-  SkillDiscovery.Service,
-  SkillDiscovery.Service.of({
-    pull: (url) => {
-      pulls++
-      if (failedUrls.has(url)) return Effect.die(`failed to pull ${url}`)
-      return Effect.succeed(urls.get(url) ?? [])
-    },
-  }),
-)
-const watcherLayer = Watcher.testLayer
-const it = testEffect(
-  Layer.mergeAll(
-    AppNodeBuilder.build(LayerNode.group([Skill.node, Bus.node, FSUtil.node])),
-    discoveryLayer,
-    watcherLayer,
-  ),
-)
+const it = testEffect(Layer.empty)
 const decode = Schema.decodeUnknownSync(Info)
 
-function write(directory: string, name: string, description: string) {
-  return fs.writeFile(
-    path.join(directory, name, "SKILL.md"),
-    `---
-name: ${name}
-description: ${description}
----
-# ${name}`,
-  )
-}
-
-const configure = (skills: string[]) =>
-  Config.testLayer([
-    new Document({
-      type: "document",
-      info: decode({ skills }),
-    }),
-  ])
-
-const start = Effect.fnUntraced(function* (skills: string[], directory: string) {
-  const service = yield* Skill.Service
-  yield* ConfigSkillPlugin.Plugin.effect(
-    host({
-      skill: {
-        list: () => Effect.die("unused skill.list"),
-        transform: service.transform,
-        reload: service.reload,
-      },
-    }),
-  ).pipe(
-    Effect.provide(configure(skills)),
-    Effect.provideService(Global.Service, Global.Service.of({ ...Global.make(), home: directory })),
-    Effect.provideService(Location.Service, Location.Service.of(location({ directory: AbsolutePath.make(directory) }))),
-  )
-  return service
-})
-
-function emitAndWait(update: Watcher.Update) {
-  return Effect.gen(function* () {
-    const watcher = yield* Watcher.Test
-    const bus = yield* Bus.Service
-    const deferred = yield* Deferred.make<void>()
-    const fiber = yield* bus.subscribe(Skill.Event.Updated).pipe(
-      Stream.runForEach(() => Deferred.succeed(deferred, undefined).pipe(Effect.asVoid)),
-      Effect.forkScoped,
-    )
-    yield* Effect.yieldNow
-    yield* watcher.emit(update)
-    yield* Deferred.await(deferred).pipe(Effect.timeout("2 seconds"))
-    yield* Fiber.interrupt(fiber)
-  })
-}
-
-describe("SkillFile.parse", () => {
-  it.effect("parses root and nested skill ids and metadata flags", () =>
-    Effect.sync(() => {
-      const directory = "/repo/skills"
-      expect(
-        SkillFile.parse(
-          directory,
-          "/repo/skills/manual/SKILL.md",
-          `---
-name: Manual
-description: Manual only
-metadata:
-  opencode/slash: "true"
-  opencode/autoinvoke: false
----
-# manual`,
-        ),
-      ).toEqual({
-        _tag: "Parsed",
-        skill: {
-          id: Skill.ID.make("manual"),
-          name: Skill.Name.make("Manual"),
-          description: "Manual only",
-          slash: true,
-          autoinvoke: false,
-          location: AbsolutePath.make("/repo/skills/manual/SKILL.md"),
-          content: "# manual",
-        },
-      })
-      expect(SkillFile.parse(directory, "/repo/skills/foo.md", "---\nslash: true\n---\n# foo")).toMatchObject({
-        _tag: "Parsed",
-        skill: { id: Skill.ID.make("foo") },
-      })
-      expect(
-        SkillFile.parse(directory, "/repo/skills/broken.md", "---\ndescription: foo: bar\nmetadata: [\n---\n# broken"),
-      ).toEqual({ _tag: "Skipped", reason: "markdown" })
-      expect(SkillFile.parse(directory, "/repo/skills/broken.md", "---\nslash: nope\n---\n# broken")).toMatchObject({
-        _tag: "Skipped",
-        reason: "frontmatter",
-        issue: expect.anything(),
-      })
-    }),
-  )
-})
-
 describe("ConfigSkillPlugin.Plugin", () => {
-  it.live("loads directory and URL sources with later-source precedence", () =>
-    Effect.acquireRelease(
-      Effect.promise(() => tmpdir()),
-      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-    ).pipe(
-      Effect.flatMap((tmp) =>
-        Effect.gen(function* () {
-          const first = path.join(tmp.path, "first")
-          const second = path.join(tmp.path, "second")
-          yield* Effect.promise(async () => {
-            await fs.mkdir(path.join(first, "review"), { recursive: true })
-            await fs.mkdir(path.join(second, "review"), { recursive: true })
-            await write(first, "review", "First")
-            await write(second, "review", "Second")
-          })
-          pulls = 0
-          urls.set("https://example.test/skills/", [AbsolutePath.make(second)])
+  it.effect("registers configured skill directories and URLs", () =>
+    Effect.gen(function* () {
+      const directory = AbsolutePath.make("/repo/packages/app")
+      const sources: Skill.Source[] = []
+      const transform = Effect.fnUntraced(function* (update: (draft: Skill.Draft) => void | Effect.Effect<void>) {
+        const result = update({
+          source: (source) => {
+            sources.push(source)
+          },
+          list: () => sources,
+        })
+        if (Effect.isEffect(result)) yield* result
+        const dispose = Effect.sync(() => {
+          sources.length = 0
+        })
+        yield* Effect.addFinalizer(() => dispose)
+        return { dispose }
+      })
 
-          const skill = yield* start([first, "https://example.test/skills/"], tmp.path)
-          expect((yield* skill.list()).find((item) => item.id === "review")?.description).toBe("Second")
-          expect(pulls).toBe(1)
+      yield* ConfigSkillPlugin.Plugin.effect(
+        host({
+          skill: { list: () => Effect.die("unused skill.list"), transform, reload: () => Effect.void },
         }),
-      ),
-    ),
-  )
+      ).pipe(
+        Effect.provideService(Global.Service, Global.Service.of({ ...Global.make(), home: "/home/test" })),
+        Effect.provideService(Location.Service, Location.Service.of(location({ directory }))),
+        Effect.provide(
+          Config.testLayer([
+            new ClaudeDirectory({ type: "claude", path: AbsolutePath.make("/repo/.claude") }),
+            new AgentsDirectory({ type: "agents", path: AbsolutePath.make("/repo/.agents") }),
+            new Directory({ type: "directory", path: AbsolutePath.make("/repo/.opencode") }),
+            new Document({
+              type: "document",
+              info: decode({
+                skills: ["./skills", "~/shared-skills", "/opt/skills", "https://example.test/skills/"],
+              }),
+            }),
+          ]),
+        ),
+      )
 
-  it.live("keeps directory skills when a URL source fails", () =>
-    Effect.acquireRelease(
-      Effect.promise(() => tmpdir()),
-      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-    ).pipe(
-      Effect.flatMap((tmp) =>
-        Effect.gen(function* () {
-          yield* Effect.promise(async () => {
-            await fs.mkdir(path.join(tmp.path, "review"), { recursive: true })
-            await write(tmp.path, "review", "Available")
-          })
-          const url = "https://unreachable.example.test/skills/"
-          failedUrls.add(url)
-
-          const skill = yield* start([tmp.path, url], tmp.path)
-          expect((yield* skill.list()).find((item) => item.id === "review")?.description).toBe("Available")
-          failedUrls.delete(url)
+      expect(sources).toEqual([
+        Skill.DirectorySource.make({
+          type: "directory",
+          path: AbsolutePath.make(path.join("/repo/.claude", "skills")),
         }),
-      ),
-    ),
-  )
-
-  it.live("rescans directory sources when watched files change", () =>
-    Effect.acquireRelease(
-      Effect.promise(() => tmpdir()),
-      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-    ).pipe(
-      Effect.flatMap((tmp) =>
-        Effect.gen(function* () {
-          yield* Effect.promise(async () => {
-            await fs.mkdir(path.join(tmp.path, "deploy"), { recursive: true })
-            await write(tmp.path, "deploy", "Initial")
-          })
-          const skill = yield* start([tmp.path], tmp.path)
-          expect((yield* skill.list()).find((item) => item.id === "deploy")?.description).toBe("Initial")
-
-          const deploy = path.join(tmp.path, "deploy", "SKILL.md")
-          yield* Effect.promise(() => write(tmp.path, "deploy", "Updated"))
-          yield* emitAndWait({ type: "update", path: deploy })
-          expect((yield* skill.list()).find((item) => item.id === "deploy")?.description).toBe("Updated")
-
-          yield* Effect.promise(async () => {
-            await fs.mkdir(path.join(tmp.path, "review"), { recursive: true })
-            await write(tmp.path, "review", "Review")
-          })
-          yield* emitAndWait({ type: "create", path: path.join(tmp.path, "review", "SKILL.md") })
-          expect((yield* skill.list()).map((item) => item.id)).toEqual([
-            Skill.ID.make("deploy"),
-            Skill.ID.make("review"),
-          ])
+        Skill.DirectorySource.make({
+          type: "directory",
+          path: AbsolutePath.make(path.join("/repo/.agents", "skills")),
         }),
-      ),
-    ),
-  )
-
-  it.live("follows missing source directories as their parents appear", () =>
-    Effect.acquireRelease(
-      Effect.promise(() => tmpdir()),
-      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
-    ).pipe(
-      Effect.flatMap((tmp) =>
-        Effect.gen(function* () {
-          const source = path.join(tmp.path, "generated", "skills")
-          const skill = yield* start([source], tmp.path)
-          const watcher = yield* Watcher.Test
-          expect(yield* skill.list()).toEqual([])
-          expect(yield* watcher.subscriptions()).toEqual([{ path: path.join(tmp.path, "generated"), type: "file" }])
-
-          yield* Effect.promise(() => fs.mkdir(path.join(tmp.path, "generated")))
-          yield* emitAndWait({ type: "create", path: path.join(tmp.path, "generated") })
-          yield* Effect.promise(async () => {
-            await fs.mkdir(path.join(source, "deploy"), { recursive: true })
-            await write(source, "deploy", "Deploy")
-          })
-          yield* emitAndWait({ type: "create", path: source })
-          expect((yield* skill.list()).map((item) => item.id)).toEqual([Skill.ID.make("deploy")])
+        Skill.DirectorySource.make({
+          type: "directory",
+          path: AbsolutePath.make(path.join("/repo/.opencode", "skill")),
         }),
-      ),
-    ),
+        Skill.DirectorySource.make({
+          type: "directory",
+          path: AbsolutePath.make(path.join("/repo/.opencode", "skills")),
+        }),
+        Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make(path.join(directory, "skills")) }),
+        Skill.DirectorySource.make({
+          type: "directory",
+          path: AbsolutePath.make(path.join("/home/test", "shared-skills")),
+        }),
+        Skill.DirectorySource.make({ type: "directory", path: AbsolutePath.make("/opt/skills") }),
+        Skill.UrlSource.make({ type: "url", url: "https://example.test/skills/" }),
+      ])
+    }),
   )
 })

packages/core/test/plugin/fixture.ts

@@ -19,11 +19,9 @@ import { PluginHooks } from "@opencode-ai/core/plugin/hooks"
 import { PluginRuntime } from "@opencode-ai/core/plugin/runtime"
 import { Reference } from "@opencode-ai/core/reference"
 import { Skill } from "@opencode-ai/core/skill"
-import { SkillDiscovery } from "@opencode-ai/core/skill/discovery"
-import { Watcher } from "@opencode-ai/core/filesystem/watcher"
 import { Tool } from "@opencode-ai/core/tool"
 import { WebSearch } from "@opencode-ai/core/websearch"
-import { Effect, Layer } from "effect"
+import { Effect, Layer, Stream } from "effect"
 import { tempLocationLayer } from "../fixture/location"
 
 const npmLayer = Layer.succeed(
@@ -55,10 +53,8 @@ export const PluginTestLayer = AppNodeBuilder.build(
     PluginHooks.node,
     Reference.node,
     Skill.node,
-    SkillDiscovery.node,
     PluginHooks.node,
     Tool.node,
-    Watcher.node,
     WebSearch.node,
   ]),
   [

packages/core/test/plugin/provider-cloudflare-workers-ai.test.ts

@@ -2,6 +2,8 @@ import { AISDK } from "@opencode-ai/core/aisdk"
 import { describe, expect } from "bun:test"
 import { Effect } from "effect"
 import { Catalog } from "@opencode-ai/core/catalog"
+import { Credential } from "@opencode-ai/core/credential"
+import { ModelResolver } from "@opencode-ai/core/model-resolver"
 import { Model } from "@opencode-ai/core/model"
 import { Plugin } from "@opencode-ai/core/plugin"
 import { PluginHost } from "@opencode-ai/core/plugin/host"
@@ -16,7 +18,6 @@ const it = testEffect(PluginTestLayer)
 
 const addPlugin = Effect.fn(function* () {
   const plugin = yield* Plugin.Service
-  const aisdk = yield* AISDK.Service
   const host = yield* PluginHost.make(plugin)
   yield* CloudflareWorkersAIPlugin.effect(host)
 })
@@ -103,15 +104,13 @@ describe("CloudflareWorkersAIPlugin", () => {
     ),
   )
 
-  it.effect("maps account ID to endpoint URL and creates an OpenAI-compatible SDK", () =>
+  it.effect("maps the environment account ID to the native endpoint", () =>
     withEnv({ CLOUDFLARE_ACCOUNT_ID: "acct", CLOUDFLARE_API_KEY: "key" }, () =>
       Effect.gen(function* () {
-        const plugin = yield* Plugin.Service
-        const aisdk = yield* AISDK.Service
         const catalog = yield* Catalog.Service
         yield* catalog.transform((catalog) =>
           catalog.provider.update(Provider.ID.make("cloudflare-workers-ai"), (provider) => {
-            provider.package = Provider.aisdk("test-provider")
+            provider.package = Provider.aisdk("@ai-sdk/openai-compatible")
           }),
         )
         yield* addPlugin()
@@ -119,21 +118,10 @@ describe("CloudflareWorkersAIPlugin", () => {
           (yield* (yield* Integration.Service).get(Integration.ID.make("cloudflare-workers-ai")))?.methods,
         ).toContainEqual({ type: "key", label: "API key" })
         const provider = required(yield* catalog.provider.get(Provider.ID.make("cloudflare-workers-ai")))
-        const sdk = yield* aisdk.runSDK({
-          model: Model.Info.make({
-            ...Model.Info.default(Provider.ID.make("cloudflare-workers-ai"), Model.ID.make("@cf/model")),
-            modelID: Model.ID.make("@cf/model"),
-            package: provider.package,
-            settings: provider.settings,
-          }),
-          package: "@ai-sdk/openai-compatible",
-          options: { name: "cloudflare-workers-ai", headers: { custom: "header" } },
-        })
         expect(provider).toMatchObject({
-          package: "aisdk:test-provider",
+          package: "@opencode-ai/ai/providers/cloudflare-workers-ai",
           settings: { baseURL: "https://api.cloudflare.com/client/v4/accounts/acct/ai/v1" },
         })
-        expect(sdk.sdk).toBeDefined()
       }),
     ),
   )
@@ -193,19 +181,72 @@ describe("CloudflareWorkersAIPlugin", () => {
         const catalog = yield* Catalog.Service
         yield* catalog.transform((catalog) =>
           catalog.provider.update(Provider.ID.make("cloudflare-workers-ai"), (provider) => {
-            provider.package = Provider.aisdk("test-provider")
+            provider.package = Provider.aisdk("@ai-sdk/openai-compatible")
             provider.settings = { ...provider.settings, accountId: "configured-acct" }
           }),
         )
         yield* addPlugin()
         expect(required(yield* catalog.provider.get(Provider.ID.make("cloudflare-workers-ai")))).toMatchObject({
-          package: "aisdk:test-provider",
-          settings: { baseURL: "https://api.cloudflare.com/client/v4/accounts/env-acct/ai/v1" },
+          package: "@opencode-ai/ai/providers/cloudflare-workers-ai",
+          settings: {
+            accountId: "configured-acct",
+            baseURL: "https://api.cloudflare.com/client/v4/accounts/env-acct/ai/v1",
+          },
         })
       }),
     ),
   )
 
+  it.effect("passes the connected account ID to the native provider at runtime", () =>
+    withEnv({ CLOUDFLARE_ACCOUNT_ID: undefined }, () =>
+      Effect.gen(function* () {
+        const catalog = yield* Catalog.Service
+        const providerID = Provider.ID.make("cloudflare-workers-ai")
+        yield* catalog.transform((draft) => {
+          draft.provider.update(providerID, (provider) => {
+            provider.package = Provider.aisdk("@ai-sdk/openai-compatible")
+            provider.settings = {
+              accountId: "configured-acct",
+              baseURL: "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1",
+            }
+          })
+          draft.model.update(providerID, Model.ID.make("@cf/model"), (model) => {
+            model.settings = {
+              accountId: "model-acct",
+              baseURL: "https://api.cloudflare.com/client/v4/accounts/${CLOUDFLARE_ACCOUNT_ID}/ai/v1",
+            }
+          })
+        })
+        yield* addPlugin()
+
+        const selected = required(yield* catalog.model.get(providerID, Model.ID.make("@cf/model")))
+        const { model } = yield* Effect.promise(() => import("@opencode-ai/ai/providers/cloudflare-workers-ai"))
+        const resolved = yield* ModelResolver.fromCatalogModel(
+          selected,
+          Credential.Key.make({
+            type: "key",
+            key: "secret",
+            configuration: { accountId: "connected-acct" },
+          }),
+          { loadPackage: () => Effect.succeed({ model }) },
+        )
+
+        expect(required(yield* catalog.provider.get(providerID))).toMatchObject({
+          package: "@opencode-ai/ai/providers/cloudflare-workers-ai",
+          settings: { accountId: "configured-acct" },
+        })
+        expect(selected).toMatchObject({
+          package: "@opencode-ai/ai/providers/cloudflare-workers-ai",
+          settings: { accountId: "model-acct" },
+        })
+        expect(selected.settings).not.toHaveProperty("baseURL")
+        expect(resolved.route.endpoint.baseURL).toBe(
+          "https://api.cloudflare.com/client/v4/accounts/connected-acct/ai/v1",
+        )
+      }),
+    ),
+  )
+
   it.effect("uses env API key over auth or configured API key and keeps the Cloudflare User-Agent", () =>
     withEnv({ CLOUDFLARE_ACCOUNT_ID: "acct", CLOUDFLARE_API_KEY: "env-key" }, () =>
       Effect.gen(function* () {

packages/core/test/skill.test.ts

@@ -1,102 +1,438 @@
+import fs from "fs/promises"
+import path from "path"
 import { describe, expect } from "bun:test"
-import { Deferred, Effect, Fiber, Stream } from "effect"
+import { Deferred, Effect, Fiber, Layer, Stream } from "effect"
 import { Agent } from "@opencode-ai/core/agent"
 import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/util/effect/layer-node"
 import { Bus } from "@opencode-ai/core/bus"
 import { AbsolutePath } from "@opencode-ai/core/schema"
 import { Skill } from "@opencode-ai/core/skill"
+import { SkillDiscovery } from "@opencode-ai/core/skill/discovery"
+import { Watcher } from "@opencode-ai/core/filesystem/watcher"
+import { tmpdir } from "./fixture/tmpdir"
 import { testEffect } from "./lib/effect"
 
-const it = testEffect(AppNodeBuilder.build(LayerNode.group([Skill.node, Agent.node, Bus.node])))
+const urls = new Map<string, AbsolutePath[]>()
+let pulls = 0
+const discovery = Layer.succeed(
+  SkillDiscovery.Service,
+  SkillDiscovery.Service.of({
+    pull: (url) => {
+      pulls++
+      return Effect.succeed(urls.get(url) ?? [])
+    },
+  }),
+)
+const watcherLayer = Watcher.testLayer
+const it = testEffect(
+  Layer.mergeAll(
+    AppNodeBuilder.build(LayerNode.group([Skill.node, Agent.node, Bus.node]), [
+      [SkillDiscovery.node, discovery],
+      [Watcher.node, watcherLayer],
+    ]),
+    watcherLayer,
+  ),
+)
 
-const info = (id: string, description: string) =>
-  Skill.Info.make({
-    id: Skill.ID.make(id),
-    name: Skill.Name.make(id),
-    description,
-    location: AbsolutePath.make(`/skills/${id}/SKILL.md`),
-    content: `# ${id}`,
+function write(directory: string, name: string, description: string) {
+  return fs.writeFile(
+    path.join(directory, name, "SKILL.md"),
+    `---
+name: ${name}
+description: ${description}
+---
+# ${name}`,
+  )
+}
+
+function waitForSkillUpdate() {
+  return Effect.gen(function* () {
+    const bus = yield* Bus.Service
+    const deferred = yield* Deferred.make<void>()
+    const fiber = yield* bus.subscribe(Skill.Event.Updated).pipe(
+      Stream.runForEach(() => Deferred.succeed(deferred, undefined).pipe(Effect.asVoid)),
+      Effect.forkScoped,
+    )
+    yield* Effect.yieldNow
+    return { deferred, fiber }
   })
+}
+
+function expectSubscription(check: (input: Watcher.WatchInput) => boolean) {
+  return Effect.gen(function* () {
+    const watcher = yield* Watcher.Test
+    expect((yield* watcher.subscriptions()).some(check)).toBe(true)
+  })
+}
+
+function emitAndWait(update: Watcher.Update) {
+  return Effect.gen(function* () {
+    const watcher = yield* Watcher.Test
+    yield* Effect.acquireUseRelease(
+      waitForSkillUpdate(),
+      ({ deferred }) => watcher.emit(update).pipe(Effect.andThen(Deferred.await(deferred)), Effect.timeout("1 second")),
+      ({ fiber }) => Fiber.interrupt(fiber),
+    )
+  })
+}
 
 describe("Skill", () => {
-  it.effect("registers values with last-write-wins precedence", () =>
+  it.live("publishes updates when skill sources change", () =>
     Effect.gen(function* () {
       const skill = yield* Skill.Service
-      yield* skill.transform((draft) => {
-        draft.add(info("review", "First"))
-        draft.add(info("deploy", "Deploy"))
-        draft.add(info("review", "Second"))
-        expect(draft.list().map((item) => item.id)).toEqual([Skill.ID.make("review"), Skill.ID.make("deploy")])
-      })
 
-      expect(yield* skill.list()).toEqual([info("review", "Second"), info("deploy", "Deploy")])
+      yield* Effect.acquireUseRelease(
+        waitForSkillUpdate(),
+        ({ deferred }) =>
+          skill
+            .transform((editor) =>
+              editor.source({ type: "directory", path: AbsolutePath.make("/tmp/opencode-skills") }),
+            )
+            .pipe(Effect.andThen(Deferred.await(deferred)), Effect.timeout("1 second")),
+        ({ fiber }) => Fiber.interrupt(fiber),
+      )
     }),
   )
 
-  it.effect("updates and removes registered values", () =>
-    Effect.gen(function* () {
-      const skill = yield* Skill.Service
-      yield* skill.transform((draft) => {
-        draft.add(info("review", "Initial"))
-        draft.update("review", (value) => {
-          value.description = "Updated"
-          value.id = Skill.ID.make("ignored")
-        })
-        draft.update("missing", () => Effect.die("unreachable"))
-        draft.add(info("deploy", "Deploy"))
-        draft.remove("deploy")
-      })
+  it.live("registers sources and resolves later source precedence", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          const first = path.join(tmp.path, "first")
+          const second = path.join(tmp.path, "second")
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(first, "review"), { recursive: true })
+            await fs.mkdir(path.join(second, "review"), { recursive: true })
+            await write(first, "review", "First")
+            await write(second, "review", "Second")
+            await fs.writeFile(path.join(first, "foo.md"), "---\nslash: true\n---\n# foo")
+          })
 
-      expect(yield* skill.list()).toEqual([info("review", "Updated")])
-    }),
-  )
+          const skill = yield* Skill.Service
+          const watcher = yield* Watcher.Test
+          yield* skill.transform((editor) => {
+            editor.source({ type: "directory", path: AbsolutePath.make(first) })
+            editor.source({ type: "directory", path: AbsolutePath.make(first) })
+            editor.source({ type: "directory", path: AbsolutePath.make(second) })
+            expect(editor.list()).toEqual([
+              { type: "directory", path: AbsolutePath.make(first) },
+              { type: "directory", path: AbsolutePath.make(second) },
+            ])
+          })
 
-  it.effect("restores earlier values when an updating transform is disposed", () =>
-    Effect.gen(function* () {
-      const skill = yield* Skill.Service
-      const original = info("review", "Initial")
-      yield* skill.transform((draft) => draft.add(original))
-      const updated = yield* skill.transform((draft) =>
-        draft.update("review", (value) => {
-          value.description = "Updated"
+          expect(yield* skill.sources()).toEqual([
+            { type: "directory", path: AbsolutePath.make(first) },
+            { type: "directory", path: AbsolutePath.make(second) },
+          ])
+          expect(yield* skill.list()).toEqual([
+            Skill.Info.make({
+              id: Skill.ID.make("foo"),
+              name: Skill.Name.make("foo"),
+              slash: true,
+              location: AbsolutePath.make(path.join(first, "foo.md")),
+              content: "# foo",
+            }),
+            {
+              id: Skill.ID.make("review"),
+              name: Skill.Name.make("review"),
+              description: "Second",
+              location: AbsolutePath.make(path.join(second, "review", "SKILL.md")),
+              content: "# review",
+            },
+          ])
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: first, type: "directory" },
+            { path: second, type: "directory" },
+          ])
+
+          yield* Effect.promise(() => write(second, "review", "Updated Second"))
+          yield* emitAndWait({ type: "update", path: path.join(second, "review", "SKILL.md") })
+
+          expect((yield* skill.list()).find((item) => item.id === "review")?.description).toBe("Updated Second")
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: first, type: "directory" },
+            { path: second, type: "directory" },
+            { path: first, type: "directory" },
+            { path: second, type: "directory" },
+          ])
         }),
-      )
-
-      expect((yield* skill.list())[0]?.description).toBe("Updated")
-      yield* updated.dispose
-      expect((yield* skill.list())[0]?.description).toBe("Initial")
-      expect(original.description).toBe("Initial")
-    }),
+      ),
+    ),
   )
 
-  it.live("publishes updates after committed values are visible", () =>
-    Effect.gen(function* () {
-      const skill = yield* Skill.Service
-      const bus = yield* Bus.Service
-      const updated = yield* Deferred.make<Skill.Info[]>()
-      const fiber = yield* bus.subscribe(Skill.Event.Updated).pipe(
-        Stream.runForEach(() => skill.list().pipe(Effect.flatMap((values) => Deferred.succeed(updated, values)))),
-        Effect.forkScoped,
-      )
-      yield* Effect.yieldNow
+  it.live("loads URL sources and filters skills for agents", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(tmp.path, "deploy"), { recursive: true })
+            await write(tmp.path, "deploy", "Deploy production")
+          })
+          pulls = 0
+          urls.set("https://example.test/skills/", [AbsolutePath.make(tmp.path)])
 
-      yield* skill.transform((draft) => draft.add(info("review", "Visible")))
-      expect(yield* Deferred.await(updated).pipe(Effect.timeout("1 second"))).toEqual([info("review", "Visible")])
-      yield* Fiber.interrupt(fiber)
-    }),
-  )
+          const agents = yield* Agent.Service
+          yield* agents.transform((editor) =>
+            editor.update(Agent.ID.make("reviewer"), (agent) => {
+              agent.permissions.push({ action: "skill", resource: "deploy", effect: "deny" })
+            }),
+          )
 
-  it.effect("filters values by agent permissions", () =>
-    Effect.gen(function* () {
-      const agents = yield* Agent.Service
-      yield* agents.transform((draft) =>
-        draft.update(Agent.ID.make("reviewer"), (agent) => {
-          agent.permissions.push({ action: "skill", resource: "deploy", effect: "deny" })
+          const skill = yield* Skill.Service
+          yield* skill.transform((editor) => editor.source({ type: "url", url: "https://example.test/skills/" }))
+
+          expect((yield* skill.list()).map((item) => item.name)).toEqual([Skill.Name.make("deploy")])
+          expect((yield* skill.list()).map((item) => item.name)).toEqual([Skill.Name.make("deploy")])
+          expect(pulls).toBe(1)
+          expect(Skill.available(yield* skill.list(), (yield* agents.get(Agent.ID.make("reviewer")))!)).toEqual([])
         }),
-      )
-      const agent = yield* agents.get(Agent.ID.make("reviewer"))
-      expect(Skill.available([info("deploy", "Deploy")], agent!)).toEqual([])
-    }),
+      ),
+    ),
+  )
+
+  it.live("parses opencode metadata flags from skill frontmatter", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(tmp.path, "manual"), { recursive: true })
+            await fs.writeFile(
+              path.join(tmp.path, "manual", "SKILL.md"),
+              `---
+name: manual
+description: Manual only
+metadata:
+  opencode/slash: true
+  opencode/autoinvoke: false
+---
+# manual`,
+            )
+          })
+
+          const skill = yield* Skill.Service
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(tmp.path) }))
+
+          expect(yield* skill.list()).toEqual([
+            {
+              id: Skill.ID.make("manual"),
+              name: Skill.Name.make("manual"),
+              description: "Manual only",
+              slash: true,
+              autoinvoke: false,
+              location: AbsolutePath.make(path.join(tmp.path, "manual", "SKILL.md")),
+              content: "# manual",
+            },
+          ])
+        }),
+      ),
+    ),
+  )
+
+  it.live("clears cached skills when sources reload", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(tmp.path, "deploy"), { recursive: true })
+            await write(tmp.path, "deploy", "Initial deploy")
+          })
+
+          const skill = yield* Skill.Service
+          const watcher = yield* Watcher.Test
+          const bus = yield* Bus.Service
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(tmp.path) }))
+          expect((yield* skill.list()).find((item) => item.id === "deploy")?.description).toBe("Initial deploy")
+          expect(yield* watcher.subscriptions()).toEqual([{ path: tmp.path, type: "directory" }])
+
+          let refreshed: Skill.Info[] = []
+          const unsubscribe = yield* bus.listen((event) => {
+            if (event.type !== Skill.Event.Updated.type) return Effect.void
+            return skill.list().pipe(
+              Effect.tap((items) => Effect.sync(() => (refreshed = items))),
+              Effect.asVoid,
+            )
+          })
+
+          yield* Effect.promise(() => write(tmp.path, "deploy", "Updated deploy"))
+          yield* skill.reload().pipe(Effect.timeout("1 second"))
+          yield* unsubscribe
+
+          expect(refreshed.find((item) => item.id === "deploy")?.description).toBe("Updated deploy")
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: tmp.path, type: "directory" },
+            { path: tmp.path, type: "directory" },
+          ])
+        }),
+      ),
+    ),
+  )
+
+  it.live("reloads project sources created after their missing parent", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          const source = path.join(tmp.path, "generated", "skills")
+          const file = path.join(source, "deploy", "SKILL.md")
+          const skill = yield* Skill.Service
+          const watcher = yield* Watcher.Test
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(source) }))
+          expect(yield* skill.list()).toEqual([])
+          expect(yield* watcher.subscriptions()).toEqual([{ path: path.join(tmp.path, "generated"), type: "file" }])
+
+          yield* Effect.promise(() => fs.mkdir(path.join(tmp.path, "generated")))
+          yield* emitAndWait({ type: "create", path: path.join(tmp.path, "generated") })
+          expect(yield* skill.list()).toEqual([])
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: path.join(tmp.path, "generated"), type: "file" },
+            { path: source, type: "file" },
+          ])
+
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.dirname(file), { recursive: true })
+            await write(source, "deploy", "Deploy production")
+          })
+          yield* emitAndWait({ type: "create", path: source })
+
+          expect((yield* skill.list()).map((item) => item.id)).toEqual([Skill.ID.make("deploy")])
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: path.join(tmp.path, "generated"), type: "file" },
+            { path: source, type: "file" },
+            { path: source, type: "directory" },
+          ])
+        }),
+      ),
+    ),
+  )
+
+  it.live("watches directory sources for added and changed skills", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(tmp.path, "deploy"), { recursive: true })
+            await write(tmp.path, "deploy", "Initial deploy")
+          })
+
+          const skill = yield* Skill.Service
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(tmp.path) }))
+          expect((yield* skill.list()).map((item) => item.id)).toEqual([Skill.ID.make("deploy")])
+          yield* expectSubscription((input) => input.type === "directory" && input.path === tmp.path)
+
+          const deploy = path.join(tmp.path, "deploy", "SKILL.md")
+          yield* Effect.promise(() => write(tmp.path, "deploy", "Updated deploy"))
+          yield* emitAndWait({ type: "update", path: deploy })
+          expect((yield* skill.list()).find((item) => item.id === "deploy")?.description).toBe("Updated deploy")
+
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(tmp.path, "review"), { recursive: true })
+            await write(tmp.path, "review", "Review changes")
+          })
+          const review = path.join(tmp.path, "review", "SKILL.md")
+          yield* emitAndWait({ type: "create", path: review })
+          expect((yield* skill.list()).map((item) => item.id)).toEqual([
+            Skill.ID.make("deploy"),
+            Skill.ID.make("review"),
+          ])
+
+          yield* Effect.promise(() => fs.rm(path.join(tmp.path, "review"), { recursive: true }))
+          yield* emitAndWait({ type: "delete", path: review })
+          expect((yield* skill.list()).map((item) => item.id)).toEqual([Skill.ID.make("deploy")])
+        }),
+      ),
+    ),
+  )
+
+  it.live("watches canonical directories behind symlinked skills", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          const source = path.join(tmp.path, "source")
+          const target = path.join(tmp.path, "target", "bro")
+          const file = path.join(target, "SKILL.md")
+          yield* Effect.promise(async () => {
+            await fs.mkdir(source, { recursive: true })
+            await fs.mkdir(target, { recursive: true })
+            await fs.writeFile(file, "---\nname: bro\ndescription: Initial\n---\n# bro")
+            await fs.symlink(target, path.join(source, "bro"))
+          })
+
+          const skill = yield* Skill.Service
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(source) }))
+          expect((yield* skill.list()).find((item) => item.id === "bro")?.description).toBe("Initial")
+          yield* expectSubscription((input) => input.type === "directory" && input.path === target)
+
+          yield* Effect.promise(() => fs.writeFile(file, "---\nname: bro\ndescription: Updated\n---\n# bro"))
+          yield* emitAndWait({ type: "update", path: file })
+          expect((yield* skill.list()).find((item) => item.id === "bro")?.description).toBe("Updated")
+        }),
+      ),
+    ),
+  )
+
+  it.live("invalidates symlinked sources when their target changes", () =>
+    Effect.acquireRelease(
+      Effect.promise(() => tmpdir()),
+      (tmp) => Effect.promise(() => tmp[Symbol.asyncDispose]()),
+    ).pipe(
+      Effect.flatMap((tmp) =>
+        Effect.gen(function* () {
+          const source = path.join(tmp.path, "source")
+          const first = path.join(tmp.path, "first")
+          const second = path.join(tmp.path, "second")
+          yield* Effect.promise(async () => {
+            await fs.mkdir(path.join(first, "bro"), { recursive: true })
+            await fs.mkdir(path.join(second, "bro"), { recursive: true })
+            await write(first, "bro", "First")
+            await write(second, "bro", "Second")
+            await fs.symlink(first, source)
+          })
+
+          const skill = yield* Skill.Service
+          const watcher = yield* Watcher.Test
+          yield* skill.transform((editor) => editor.source({ type: "directory", path: AbsolutePath.make(source) }))
+          expect((yield* skill.list()).find((item) => item.id === "bro")?.description).toBe("First")
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: first, type: "directory" },
+            { path: source, type: "file" },
+          ])
+
+          yield* Effect.promise(async () => {
+            await fs.unlink(source)
+            await fs.symlink(second, source)
+          })
+          yield* emitAndWait({ type: "update", path: source })
+
+          expect((yield* skill.list()).find((item) => item.id === "bro")?.description).toBe("Second")
+          expect(yield* watcher.subscriptions()).toEqual([
+            { path: first, type: "directory" },
+            { path: source, type: "file" },
+            { path: second, type: "directory" },
+            { path: source, type: "file" },
+          ])
+        }),
+      ),
+    ),
   )
 })

packages/core/test/tool-skill.test.ts

@@ -81,6 +81,7 @@ describe("SkillTool", () => {
             Skill.Service.of({
               transform: (_transform) => Effect.die("unused"),
               reload: () => Effect.die("unused"),
+              sources: () => Effect.die("unused"),
               list: () => Effect.succeed(current),
             }),
           )

packages/plugin/src/effect/skill.ts

@@ -1,13 +1,11 @@
 import type { SkillApi } from "@opencode-ai/client/effect/api"
 import { Skill } from "@opencode-ai/schema/skill"
-import type { Effect, Types } from "effect"
+import type { Effect } from "effect"
 import type { Transform } from "./registration.js"
 
 export interface SkillDraft {
-  list(): readonly Types.DeepMutable<Skill.Info>[]
-  add(skill: Skill.Info): void
-  update(id: string, update: (skill: Types.DeepMutable<Skill.Info>) => void): void
-  remove(id: string): void
+  source(source: Skill.Source): void
+  list(): readonly Skill.Source[]
 }
 
 export interface SkillDomain extends SkillApi<unknown> {

packages/plugin/src/promise/skill.ts

@@ -1,13 +1,10 @@
 import type { SkillApi } from "@opencode-ai/client/promise/api"
 import type { Skill } from "@opencode-ai/schema/skill"
 import type { Transform } from "./registration.js"
-import type { DeepMutable } from "./types.js"
 
 export interface SkillDraft {
-  list(): readonly DeepMutable<Skill.Info>[]
-  add(skill: Skill.Info): void
-  update(id: string, update: (skill: DeepMutable<Skill.Info>) => void): void
-  remove(id: string): void
+  source(source: Skill.Source): void
+  list(): readonly Skill.Source[]
 }
 
 export interface SkillDomain extends SkillApi {