feat(skill): add support for custom skill directories via config

Allows users to specify additional directories to search for SKILL.md files using the `skill.paths` config option. Paths can be relative, absolute, or use ~ for home directory expansion.

Closes #8533

Author: ian-pascoe

packages/opencode/src/config/config.ts

@@ -32,6 +32,10 @@ export namespace Config {
     if (target.instructions && source.instructions) {
       merged.instructions = Array.from(new Set([...target.instructions, ...source.instructions]))
     }
+    if (target.skill?.paths && source.skill?.paths) {
+      merged.skill = merged.skill || {}
+      merged.skill.paths = Array.from(new Set([...target.skill.paths, ...source.skill.paths]))
+    }
     return merged
   }
 
@@ -855,6 +859,12 @@ export namespace Config {
         })
         .optional(),
       plugin: z.string().array().optional(),
+      skill: z
+        .object({
+          paths: z.string().array().optional().describe("Additional directories to search for SKILL.md files"),
+        })
+        .optional()
+        .describe("Skill configuration"),
       snapshot: z.boolean().optional(),
       share: z
         .enum(["manual", "auto", "disabled"])

packages/opencode/src/skill/skill.ts

@@ -1,4 +1,5 @@
 import z from "zod"
+import path from "path"
 import { Config } from "../config/config"
 import { Instance } from "../project/instance"
 import { NamedError } from "@opencode-ai/util/error"
@@ -113,6 +114,34 @@ export namespace Skill {
       }
     }
 
+    // Scan custom skill paths from config
+    const cfg = await Config.get()
+    for (const raw of cfg.skill?.paths ?? []) {
+      const resolved = raw.startsWith("~")
+        ? path.join(Global.Path.home, raw.slice(1))
+        : path.isAbsolute(raw)
+          ? raw
+          : path.resolve(Instance.directory, raw)
+
+      if (!(await Filesystem.isDir(resolved))) continue
+
+      const matches = await Array.fromAsync(
+        OPENCODE_SKILL_GLOB.scan({
+          cwd: resolved,
+          absolute: true,
+          onlyFiles: true,
+          followSymlinks: true,
+        }),
+      ).catch((error) => {
+        log.error("failed custom skill directory scan", { dir: resolved, error })
+        return []
+      })
+
+      for (const match of matches) {
+        await addSkill(match)
+      }
+    }
+
     return skills
   })
 

packages/opencode/test/skill/skill.test.ts

@@ -183,3 +183,248 @@ test("returns empty array when no skills exist", async () => {
     },
   })
 })
+
+test("discovers skills from custom paths in config", async () => {
+  await using tmp = await tmpdir({
+    git: true,
+    init: async (dir) => {
+      const customDir = path.join(dir, "my-custom-skills", "skill", "custom-skill")
+      await Bun.write(
+        path.join(customDir, "SKILL.md"),
+        `---
+name: custom-skill
+description: A skill from a custom directory.
+---
+
+# Custom Skill
+`,
+      )
+      await Bun.write(
+        path.join(dir, "opencode.json"),
+        JSON.stringify({
+          $schema: "https://opencode.ai/config.json",
+          skill: {
+            paths: ["my-custom-skills"],
+          },
+        }),
+      )
+    },
+  })
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const skills = await Skill.all()
+      expect(skills.length).toBe(1)
+      const skill = skills.find((s) => s.name === "custom-skill")
+      expect(skill).toBeDefined()
+      expect(skill!.description).toBe("A skill from a custom directory.")
+    },
+  })
+})
+
+test("resolves relative custom skill paths from project directory", async () => {
+  await using tmp = await tmpdir({
+    git: true,
+    init: async (dir) => {
+      const customDir = path.join(dir, "custom-skills", "skills", "relative-skill")
+      await Bun.write(
+        path.join(customDir, "SKILL.md"),
+        `---
+name: relative-skill
+description: A skill from a relative path.
+---
+
+# Relative Skill
+`,
+      )
+      await Bun.write(
+        path.join(dir, "opencode.json"),
+        JSON.stringify({
+          $schema: "https://opencode.ai/config.json",
+          skill: {
+            paths: ["./custom-skills"],
+          },
+        }),
+      )
+    },
+  })
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const skills = await Skill.all()
+      expect(skills.length).toBe(1)
+      const skill = skills.find((s) => s.name === "relative-skill")
+      expect(skill).toBeDefined()
+      expect(skill!.location).toContain("custom-skills/skills/relative-skill/SKILL.md")
+    },
+  })
+})
+
+test("expands ~ in custom skill paths", async () => {
+  await using tmp = await tmpdir({ git: true })
+
+  const original = process.env.OPENCODE_TEST_HOME
+  process.env.OPENCODE_TEST_HOME = tmp.path
+
+  try {
+    const homeSkillDir = path.join(tmp.path, "test-skills", "skill", "home-skill")
+    await fs.mkdir(homeSkillDir, { recursive: true })
+    await Bun.write(
+      path.join(homeSkillDir, "SKILL.md"),
+      `---
+name: home-skill
+description: A skill from home directory expansion.
+---
+
+# Home Skill
+`,
+    )
+    await Bun.write(
+      path.join(tmp.path, "opencode.json"),
+      JSON.stringify({
+        $schema: "https://opencode.ai/config.json",
+        skill: {
+          paths: ["~/test-skills"],
+        },
+      }),
+    )
+
+    await Instance.provide({
+      directory: tmp.path,
+      fn: async () => {
+        const skills = await Skill.all()
+        expect(skills.length).toBe(1)
+        const skill = skills.find((s) => s.name === "home-skill")
+        expect(skill).toBeDefined()
+        expect(skill!.description).toBe("A skill from home directory expansion.")
+      },
+    })
+  } finally {
+    process.env.OPENCODE_TEST_HOME = original
+  }
+})
+
+test("handles absolute custom skill paths", async () => {
+  await using tmp = await tmpdir({ git: true })
+
+  const absoluteDir = path.join(tmp.path, "absolute-skills", "skill", "abs-skill")
+  await fs.mkdir(absoluteDir, { recursive: true })
+  await Bun.write(
+    path.join(absoluteDir, "SKILL.md"),
+    `---
+name: abs-skill
+description: A skill from an absolute path.
+---
+
+# Absolute Skill
+`,
+  )
+  await Bun.write(
+    path.join(tmp.path, "opencode.json"),
+    JSON.stringify({
+      $schema: "https://opencode.ai/config.json",
+      skill: {
+        paths: [path.join(tmp.path, "absolute-skills")],
+      },
+    }),
+  )
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const skills = await Skill.all()
+      expect(skills.length).toBe(1)
+      const skill = skills.find((s) => s.name === "abs-skill")
+      expect(skill).toBeDefined()
+      expect(skill!.location).toContain("absolute-skills/skill/abs-skill/SKILL.md")
+    },
+  })
+})
+
+test("gracefully skips non-existent custom paths", async () => {
+  await using tmp = await tmpdir({
+    git: true,
+    init: async (dir) => {
+      const skillDir = path.join(dir, ".opencode", "skill", "existing-skill")
+      await Bun.write(
+        path.join(skillDir, "SKILL.md"),
+        `---
+name: existing-skill
+description: An existing skill.
+---
+
+# Existing Skill
+`,
+      )
+      await Bun.write(
+        path.join(dir, "opencode.json"),
+        JSON.stringify({
+          $schema: "https://opencode.ai/config.json",
+          skill: {
+            paths: ["non-existent-path", "another-missing-dir"],
+          },
+        }),
+      )
+    },
+  })
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const skills = await Skill.all()
+      expect(skills.length).toBe(1)
+      expect(skills[0].name).toBe("existing-skill")
+    },
+  })
+})
+
+test("merges custom paths with default paths", async () => {
+  await using tmp = await tmpdir({
+    git: true,
+    init: async (dir) => {
+      const defaultDir = path.join(dir, ".opencode", "skill", "default-skill")
+      await Bun.write(
+        path.join(defaultDir, "SKILL.md"),
+        `---
+name: default-skill
+description: A skill from default path.
+---
+
+# Default Skill
+`,
+      )
+      const customDir = path.join(dir, "custom-skills", "skill", "custom-skill")
+      await Bun.write(
+        path.join(customDir, "SKILL.md"),
+        `---
+name: custom-skill
+description: A skill from custom path.
+---
+
+# Custom Skill
+`,
+      )
+      await Bun.write(
+        path.join(dir, "opencode.json"),
+        JSON.stringify({
+          $schema: "https://opencode.ai/config.json",
+          skill: {
+            paths: ["custom-skills"],
+          },
+        }),
+      )
+    },
+  })
+
+  await Instance.provide({
+    directory: tmp.path,
+    fn: async () => {
+      const skills = await Skill.all()
+      expect(skills.length).toBe(2)
+      expect(skills.find((s) => s.name === "default-skill")).toBeDefined()
+      expect(skills.find((s) => s.name === "custom-skill")).toBeDefined()
+    },
+  })
+})