feat(skill): add builtin skill infrastructure and improve tool descriptions (#340)

* feat(skill): add builtin skill types and schemas with priority-based merging support

- Add BuiltinSkill interface for programmatic skill definitions
- Create builtin-skills module with createBuiltinSkills factory function
- Add SkillScope expansion to include 'builtin' and 'config' scopes
- Create SkillsConfig and SkillDefinition Zod schemas for config validation
- Add merger.ts utility with mergeSkills function for priority-based skill merging
- Update skill and command types to support optional paths for builtin/config skills
- Priority order: builtin < config < user < opencode < project < opencode-project

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

* feat(skill): integrate programmatic skill discovery and merged skill support

- Add discovery functions for Claude and OpenCode skill directories
- Add discoverUserClaudeSkills, discoverProjectClaudeSkills functions
- Add discoverOpencodeGlobalSkills, discoverOpencodeProjectSkills functions
- Update createSkillTool to support pre-merged skills via options
- Add extractSkillBody utility to handle both file and programmatic skills
- Integrate mergeSkills in plugin initialization to apply priority-based merging
- Support optional path/resolvedPath for builtin and config-sourced skills

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

* chore(slashcommand): support optional path for builtin and config command scopes

- Update CommandInfo type to make path and content optional properties
- Prepare command tool for builtin and config sourced commands
- Maintain backward compatibility with file-based command loading

🤖 GENERATED WITH ASSISTANCE OF [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

* docs(tools): improve tool descriptions for interactive-bash and slashcommand

- Added use case clarification to interactive-bash tool description (server processes, long-running tasks, background jobs, interactive CLI tools)
- Simplified slashcommand description to emphasize 'loading' skills concept and removed verbose documentation

🤖 Generated with assistance of [OhMyOpenCode](https://github.com/code-yeongyu/oh-my-opencode)

* refactor(skill-loader): simplify redundant condition in skill merging logic

Remove redundant 'else if (loaded)' condition that was always true since we're already inside the 'if (loaded)' block. Simplify to 'else' for clarity.

Addresses code review feedback on PR #340 for the skill infrastructure feature.

🤖 Generated with assistance of OhMyOpenCode (https://github.com/code-yeongyu/oh-my-opencode)

src/tools/interactive-bash/constants.ts

@@ -13,4 +13,6 @@ export const BLOCKED_TMUX_SUBCOMMANDS = [
 
 export const INTERACTIVE_BASH_DESCRIPTION = `Execute tmux commands. Use "omo-{name}" session pattern.
 
+For: server processes, long-running tasks, background jobs, interactive CLI tools.
+
 Blocked (use bash instead): capture-pane, save-buffer, show-buffer, pipe-pane.`

src/tools/skill/tools.ts

@@ -3,7 +3,7 @@ import { readFileSync } from "node:fs"
 import { tool, type ToolDefinition } from "@opencode-ai/plugin"
 import { TOOL_DESCRIPTION_NO_SKILLS, TOOL_DESCRIPTION_PREFIX } from "./constants"
 import type { SkillArgs, SkillInfo, SkillLoadOptions } from "./types"
-import { discoverSkills, getSkillByName, type LoadedSkill } from "../../features/opencode-skill-loader"
+import { discoverSkills, type LoadedSkill } from "../../features/opencode-skill-loader"
 import { parseFrontmatter } from "../../shared/frontmatter"
 
 function loadedSkillToInfo(skill: LoadedSkill): SkillInfo {
@@ -38,8 +38,19 @@ function formatSkillsXml(skills: SkillInfo[]): string {
   return `\n\n<available_skills>\n${skillsXml}\n</available_skills>`
 }
 
+function extractSkillBody(skill: LoadedSkill): string {
+  if (skill.path) {
+    const content = readFileSync(skill.path, "utf-8")
+    const { body } = parseFrontmatter(content)
+    return body.trim()
+  }
+
+  const templateMatch = skill.definition.template?.match(/<skill-instruction>([\s\S]*?)<\/skill-instruction>/)
+  return templateMatch ? templateMatch[1].trim() : skill.definition.template || ""
+}
+
 export function createSkillTool(options: SkillLoadOptions = {}): ToolDefinition {
-  const skills = discoverSkills({ includeClaudeCodePaths: !options.opencodeOnly })
+  const skills = options.skills ?? discoverSkills({ includeClaudeCodePaths: !options.opencodeOnly })
   const skillInfos = skills.map(loadedSkillToInfo)
 
   const description = skillInfos.length === 0
@@ -52,26 +63,25 @@ export function createSkillTool(options: SkillLoadOptions = {}): ToolDefinition
       name: tool.schema.string().describe("The skill identifier from available_skills (e.g., 'code-review')"),
     },
     async execute(args: SkillArgs) {
-      const skill = getSkillByName(args.name, { includeClaudeCodePaths: !options.opencodeOnly })
+      const skill = options.skills
+        ? skills.find(s => s.name === args.name)
+        : skills.find(s => s.name === args.name)
 
       if (!skill) {
         const available = skills.map(s => s.name).join(", ")
         throw new Error(`Skill "${args.name}" not found. Available skills: ${available || "none"}`)
       }
 
-      const content = readFileSync(skill.path, "utf-8")
-      const { body } = parseFrontmatter(content)
-      const dir = dirname(skill.path)
+      const body = extractSkillBody(skill)
+      const dir = skill.path ? dirname(skill.path) : skill.resolvedPath || process.cwd()
 
-      const output = [
+      return [
         `## Skill: ${skill.name}`,
         "",
         `**Base directory**: ${dir}`,
         "",
-        body.trim(),
+        body,
       ].join("\n")
-
-      return output
     },
   })
 }

src/tools/skill/types.ts

@@ -1,3 +1,5 @@
+import type { SkillScope, LoadedSkill } from "../../features/opencode-skill-loader/types"
+
 export interface SkillArgs {
   name: string
 }
@@ -5,8 +7,8 @@ export interface SkillArgs {
 export interface SkillInfo {
   name: string
   description: string
-  location: string
-  scope: "opencode-project" | "project" | "opencode" | "user"
+  location?: string
+  scope: SkillScope
   license?: string
   compatibility?: string
   metadata?: Record<string, string>
@@ -16,4 +18,6 @@ export interface SkillInfo {
 export interface SkillLoadOptions {
   /** When true, only load from OpenCode paths (.opencode/skill/, ~/.config/opencode/skill/) */
   opencodeOnly?: boolean
+  /** Pre-merged skills to use instead of discovering */
+  skills?: LoadedSkill[]
 }

src/tools/slashcommand/tools.ts

@@ -124,8 +124,8 @@ async function formatLoadedCommand(cmd: CommandInfo): Promise<string> {
   sections.push("---\n")
   sections.push("## Command Instructions\n")
 
-  const commandDir = dirname(cmd.path)
-  const withFileRefs = await resolveFileReferencesInText(cmd.content, commandDir)
+  const commandDir = cmd.path ? dirname(cmd.path) : process.cwd()
+  const withFileRefs = await resolveFileReferencesInText(cmd.content || "", commandDir)
   const resolvedContent = await resolveCommandsInText(withFileRefs)
   sections.push(resolvedContent.trim())
 
@@ -151,40 +151,14 @@ function formatCommandList(items: CommandInfo[]): string {
 }
 
 export const slashcommand: ToolDefinition = tool({
-  description: `Execute a slash command within the main conversation.
+  description: `Load a skill to get detailed instructions for a specific task.
 
-When you use this tool, the slash command gets expanded to a full prompt that provides detailed instructions on how to complete the task.
+Skills provide specialized knowledge and step-by-step guidance.
+Use this when a task matches an available skill's description.
 
-How slash commands work:
-- Invoke commands using this tool with the command name (without arguments)
-- The command's prompt will expand and provide detailed instructions
-- Arguments from user input should be passed separately
-
-Important:
-- Only use commands listed in Available Commands below
-- Do not invoke a command that is already running
-- **CRITICAL**: When user's message starts with '/' (e.g., "/commit", "/plan"), you MUST immediately invoke this tool with that command. Do NOT attempt to handle the command manually.
-
-Commands are loaded from (priority order, highest wins):
-- .opencode/command/ (opencode-project - OpenCode project-specific commands)
-- ./.claude/commands/ (project - Claude Code project-specific commands)
-- ~/.config/opencode/command/ (opencode - OpenCode global commands)
-- $CLAUDE_CONFIG_DIR/commands/ or ~/.claude/commands/ (user - Claude Code global commands)
-
-Skills are loaded from (priority order, highest wins):
-- .opencode/skill/ (opencode-project - OpenCode project-specific skills)
-- ./.claude/skills/ (project - Claude Code project-specific skills)
-- ~/.config/opencode/skill/ (opencode - OpenCode global skills)
-- $CLAUDE_CONFIG_DIR/skills/ or ~/.claude/skills/ (user - Claude Code global skills)
-
-Each command/skill is a markdown file with:
-- YAML frontmatter: description, argument-hint, model, agent, subtask (optional)
-- Markdown body: The command instructions/prompt
-- File references: @path/to/file (relative to command file location)
-- Shell injection: \`!\`command\`\` (executes and injects output)
-
-Available Commands:
-${commandListForDescription}`,
+<available_skills>
+${commandListForDescription}
+</available_skills>`,
 
   args: {
     command: tool.schema

src/tools/slashcommand/types.ts

@@ -1,4 +1,4 @@
-export type CommandScope = "user" | "project" | "opencode" | "opencode-project"
+export type CommandScope = "builtin" | "config" | "user" | "project" | "opencode" | "opencode-project"
 
 export interface CommandMetadata {
   name: string
@@ -11,8 +11,8 @@ export interface CommandMetadata {
 
 export interface CommandInfo {
   name: string
-  path: string
+  path?: string
   metadata: CommandMetadata
-  content: string
+  content?: string
   scope: CommandScope
 }