feat: ship builtin skills to customers via postinstall

packages/opencode/script/postinstall.mjs

@@ -115,6 +115,39 @@ function printWelcome(version) {
  out(bot)
 }
 
+function copyDirRecursive(src, dst) {
+ fs.mkdirSync(dst, { recursive: true })
+ for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+ const srcPath = path.join(src, entry.name)
+ const dstPath = path.join(dst, entry.name)
+ if (entry.isDirectory()) {
+ copyDirRecursive(srcPath, dstPath)
+ } else {
+ fs.copyFileSync(srcPath, dstPath)
+ }
+ }
+}
+
+/**
+ * Copy bundled skills to ~/.altimate/builtin/ on every install/upgrade.
+ * The entire directory is wiped and replaced so each release is the single
+ * source of truth. Intentionally separate from ~/.altimate/skills/ which users own.
+ */
+function copySkillsToAltimate() {
+ try {
+ const skillsSrc = path.join(__dirname, "skills")
+ if (!fs.existsSync(skillsSrc)) return // skills not in package (shouldn't happen)
+
+ const builtinDst = path.join(os.homedir(), ".altimate", "builtin")
+
+ // Full wipe-and-replace — each release owns this directory entirely
+ if (fs.existsSync(builtinDst)) fs.rmSync(builtinDst, { recursive: true, force: true })
+ copyDirRecursive(skillsSrc, builtinDst)
+ } catch {
+ // Non-fatal — skills can be installed manually
+ }
+}
+
 /**
  * Write a marker file so the CLI can show a welcome/upgrade banner on first run.
  * npm v7+ silences postinstall stdout, so the CLI reads this marker at startup instead.
@@ -144,6 +177,7 @@ async function main() {
  // On Windows, the .exe is already included in the package and bin field points to it
  // No postinstall setup needed
  if (version) writeUpgradeMarker(version)
+ copySkillsToAltimate()
  return
  }
 
@@ -161,6 +195,7 @@ async function main() {
  // Write marker only — npm v7+ suppresses all postinstall output.
  // The CLI picks up the marker and shows the welcome box on first run.
  if (version) writeUpgradeMarker(version)
+ copySkillsToAltimate()
  } catch (error) {
  console.error("Failed to setup altimate-code binary:", error.message)
  process.exit(1)

packages/opencode/script/publish.ts

@@ -29,6 +29,7 @@ const version = Object.values(binaries)[0]
 
 await $`mkdir -p ./dist/${pkg.name}`
 await $`cp -r ./bin ./dist/${pkg.name}/bin`
+await $`cp -r ../../.opencode/skills ./dist/${pkg.name}/skills`
 await $`cp ./script/postinstall.mjs ./dist/${pkg.name}/postinstall.mjs`
 await Bun.file(`./dist/${pkg.name}/LICENSE`).write(await Bun.file("../../LICENSE").text())
 await Bun.file(`./dist/${pkg.name}/CHANGELOG.md`).write(await Bun.file("../../CHANGELOG.md").text())
@@ -70,6 +71,7 @@ const unscopedDir = `./dist/${unscopedName}`
 try {
  await $`mkdir -p ${unscopedDir}`
  await $`cp -r ./bin ${unscopedDir}/bin`
+ await $`cp -r ../../.opencode/skills ${unscopedDir}/skills`
  await $`cp ./script/postinstall.mjs ${unscopedDir}/postinstall.mjs`
  await Bun.file(`${unscopedDir}/LICENSE`).write(await Bun.file("../../LICENSE").text())
  await Bun.file(`${unscopedDir}/CHANGELOG.md`).write(await Bun.file("../../CHANGELOG.md").text())

packages/opencode/src/skill/skill.ts

@@ -104,6 +104,23 @@ export namespace Skill {
  })
  }
 
+ // altimate_change start - scan ~/.altimate/builtin/ for release-managed builtin skills
+ // This path is fully owned by postinstall (wipe-and-replace on every release).
+ // Kept separate from user-editable skill dirs so users never accidentally modify builtins.
+ if (!Flag.OPENCODE_DISABLE_EXTERNAL_SKILLS) {
+ const builtinDir = path.join(Global.Path.home, ".altimate", "builtin")
+ if (await Filesystem.isDir(builtinDir)) {
+ const matches = await Glob.scan(SKILL_PATTERN, {
+ cwd: builtinDir,
+ absolute: true,
+ include: "file",
+ symlink: true,
+ })
+ await Promise.all(matches.map(addSkill))
+ }
+ }
+ // altimate_change end
+
  // Scan external skill directories (.claude/skills/, .agents/skills/, etc.)
  // Load global (home) first, then project-level (so project-level overwrites)
  if (!Flag.OPENCODE_DISABLE_EXTERNAL_SKILLS) {

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

@@ -327,6 +327,89 @@ description: A skill in the .agents/skills directory.
  })
 })
 
+test("discovers builtin skills from ~/.altimate/builtin/", async () => {
+ await using tmp = await tmpdir({ git: true })
+
+ const originalHome = process.env.OPENCODE_TEST_HOME
+ process.env.OPENCODE_TEST_HOME = tmp.path
+
+ try {
+ const builtinDir = path.join(tmp.path, ".altimate", "builtin", "builtin-skill")
+ await fs.mkdir(builtinDir, { recursive: true })
+ await Bun.write(
+ path.join(builtinDir, "SKILL.md"),
+ `---
+name: builtin-skill
+description: A builtin skill shipped with the package.
+---
+
+# Builtin Skill
+`,
+ )
+
+ await Instance.provide({
+ directory: tmp.path,
+ fn: async () => {
+ const skills = await Skill.all()
+ expect(skills.length).toBe(1)
+ expect(skills[0].name).toBe("builtin-skill")
+ expect(skills[0].location).toContain(path.join(".altimate", "builtin", "builtin-skill", "SKILL.md"))
+ },
+ })
+ } finally {
+ process.env.OPENCODE_TEST_HOME = originalHome
+ }
+})
+
+test("project skill overrides builtin skill with same name", async () => {
+ await using tmp = await tmpdir({
+ git: true,
+ init: async (dir) => {
+ const projectSkillDir = path.join(dir, ".claude", "skills", "shared-skill")
+ await Bun.write(
+ path.join(projectSkillDir, "SKILL.md"),
+ `---
+name: shared-skill
+description: Project-level version.
+---
+
+# Project Skill
+`,
+ )
+ },
+ })
+
+ const originalHome = process.env.OPENCODE_TEST_HOME
+ process.env.OPENCODE_TEST_HOME = tmp.path
+
+ try {
+ const builtinDir = path.join(tmp.path, ".altimate", "builtin", "shared-skill")
+ await fs.mkdir(builtinDir, { recursive: true })
+ await Bun.write(
+ path.join(builtinDir, "SKILL.md"),
+ `---
+name: shared-skill
+description: Builtin version.
+---
+
+# Builtin Skill
+`,
+ )
+
+ await Instance.provide({
+ directory: tmp.path,
+ fn: async () => {
+ const skills = await Skill.all()
+ const skill = skills.find((s) => s.name === "shared-skill")
+ expect(skill).toBeDefined()
+ expect(skill!.description).toBe("Project-level version.")
+ },
+ })
+ } finally {
+ process.env.OPENCODE_TEST_HOME = originalHome
+ }
+})
+
 test("properly resolves directories that skills live in", async () => {
  await using tmp = await tmpdir({
  git: true,

script/upstream/utils/config.ts

@@ -268,6 +268,10 @@ export const defaultConfig: MergeConfig = {
  "packages/opencode/script/build.ts",
  "packages/opencode/script/publish.ts",
  "packages/opencode/script/bump-version.ts",
+ // postinstall copies builtin skills to ~/.altimate/builtin/ — our addition
+ "packages/opencode/script/postinstall.mjs",
+ // Builtin skills shipped to customers — fully owned by Altimate
+ ".opencode/skills/**",
  // Bin wrappers are Altimate-branded
  "packages/opencode/bin/**",
  "experiments/**",