feat: add context filtering for instruction files

Add context.exclude config option to filter which instruction files
are automatically loaded.

- Add ContextMap utility returning Effect directly
- Integrate in instruction.ts to filter paths and skip ignored files
- Integrate in skill/index.ts to filter external skill directories

Example config:
{
  "context": {
    "exclude": ["AGENTS.md", "CLAUDE.md"]
  }
}

Author: lbrsilva

packages/opencode/src/config/config.ts

@@ -1057,6 +1057,19 @@ export namespace Config {
           },
         ),
       instructions: z.array(z.string()).optional().describe("Additional instruction files or patterns to include"),
+      context: z
+        .object({
+          exclude: z
+            .array(z.string())
+            .optional()
+            .describe("Glob patterns for instruction files or directories to exclude from automatic loading"),
+          include: z
+            .array(z.string())
+            .optional()
+            .describe("Glob patterns for additional instruction files to include"),
+        })
+        .optional()
+        .describe("Control which instruction files are automatically loaded"),
       layout: Layout.optional().describe("@deprecated Always uses stretch layout."),
       permission: Permission.optional(),
       tools: z.record(z.string(), z.boolean()).optional(),

packages/opencode/src/session/instruction.ts

@@ -11,6 +11,7 @@ import { withTransientReadRetry } from "@/util/effect-http-client"
 import { Global } from "../global"
 import { Instance } from "../project/instance"
 import { Log } from "../util/log"
+import { ContextMap } from "../util/context-map"
 import type { MessageV2 } from "./message-v2"
 import type { MessageID } from "./schema"
 
@@ -158,7 +159,8 @@ export namespace Instruction {
             }
           }
 
-          return paths
+          // Filter paths based on context.exclude config
+          return yield* ContextMap.filterPaths(paths)
         })
 
         const system = Effect.fn("Instruction.system")(function* () {
@@ -206,6 +208,13 @@ export namespace Instruction {
               continue
             }
 
+            // Check if file should be excluded via context.exclude config
+            const ignored = yield* ContextMap.isIgnored(found)
+            if (ignored) {
+              current = path.dirname(current)
+              continue
+            }
+
             let set = s.claims.get(messageID)
             if (!set) {
               set = new Set()

packages/opencode/src/skill/index.ts

@@ -17,6 +17,7 @@ import { ConfigMarkdown } from "../config/markdown"
 import { Glob } from "../util/glob"
 import { Log } from "../util/log"
 import { Discovery } from "./discovery"
+import { ContextMap } from "../util/context-map"
 
 export namespace Skill {
   const log = Log.create({ service: "skill" })
@@ -145,6 +146,7 @@ export namespace Skill {
   ) {
     if (!Flag.OPENCODE_DISABLE_EXTERNAL_SKILLS) {
       for (const dir of EXTERNAL_DIRS) {
+        if (yield* ContextMap.isExternalDirIgnored(dir)) continue
         const root = path.join(Global.Path.home, dir)
         if (!(yield* fsys.isDir(root))) continue
         yield* scan(state, bus, root, EXTERNAL_SKILL_PATTERN, { dot: true, scope: "global" })
@@ -155,6 +157,8 @@ export namespace Skill {
         .pipe(Effect.catch(() => Effect.succeed([] as string[])))
 
       for (const root of upDirs) {
+        const dirName = path.basename(root)
+        if (yield* ContextMap.isExternalDirIgnored(dirName)) continue
         yield* scan(state, bus, root, EXTERNAL_SKILL_PATTERN, { dot: true, scope: "project" })
       }
     }

packages/opencode/src/util/context-map.ts

@@ -0,0 +1,75 @@
+import path from "path"
+import { Effect } from "effect"
+import { minimatch } from "minimatch"
+import { Config } from "../config/config"
+import { Instance } from "../project/instance"
+
+export namespace ContextMap {
+  function excludePatterns(): Effect.Effect<string[], never, never> {
+    return Effect.promise(() => Config.get().then((config) => config.context?.exclude ?? [])).pipe(
+      Effect.catch(() => Effect.succeed([])),
+    )
+  }
+
+  function includePatterns(): Effect.Effect<string[], never, never> {
+    return Effect.promise(() => Config.get().then((config) => config.context?.include ?? [])).pipe(
+      Effect.catch(() => Effect.succeed([])),
+    )
+  }
+
+  function matches(filepath: string, patterns: string[]): boolean {
+    const basename = path.basename(filepath)
+    const relative = path.relative(Instance.directory, filepath)
+
+    for (const pattern of patterns) {
+      if (minimatch(basename, pattern)) return true
+      if (minimatch(relative, pattern)) return true
+      if (minimatch(filepath, pattern)) return true
+    }
+    return false
+  }
+
+  export function isIgnored(filepath: string): Effect.Effect<boolean, never, never> {
+    return excludePatterns().pipe(
+      Effect.map((patterns) => {
+        if (patterns.length === 0) return false
+        return matches(filepath, patterns)
+      }),
+    )
+  }
+
+  export function filterPaths(paths: Set<string>): Effect.Effect<Set<string>, never, never> {
+    return excludePatterns().pipe(
+      Effect.map((patterns) => {
+        if (patterns.length === 0) return paths
+        const result = new Set<string>()
+        for (const p of paths) {
+          if (!matches(p, patterns)) {
+            result.add(p)
+          }
+        }
+        return result
+      }),
+    )
+  }
+
+  export function isExternalDirIgnored(dirName: string): Effect.Effect<boolean, never, never> {
+    return excludePatterns().pipe(
+      Effect.map((patterns) => {
+        if (patterns.length === 0) return false
+        for (const pattern of patterns) {
+          if (minimatch(dirName, pattern)) return true
+          const segments = pattern.split("/")
+          for (const segment of segments) {
+            if (segment !== "*" && minimatch(dirName, segment)) return true
+          }
+        }
+        return false
+      }),
+    )
+  }
+
+  export function contextPatterns(): Effect.Effect<string[], never, never> {
+    return includePatterns()
+  }
+}