feat: add skills browsing and selection feature

This should close #418

Author: sudo-tee

README.md

@@ -642,6 +642,7 @@ The plugin provides the following actions that can be triggered via keymaps, com
 | Set mode to Build                                           | -                                     | `:Opencode agent build`                     | `require('opencode.api').agent_build()`                                |
 | Set mode to Plan                                            | -                                     | `:Opencode agent plan`                      | `require('opencode.api').agent_plan()`                                 |
 | Select and switch mode/agent                                | -                                     | `:Opencode agent select`                    | `require('opencode.api').select_agent()`                               |
+| Browse and select available skills                          | -                                     | `:Opencode skills` / `/skills`              | -                                                                      |
 | Display list of available mcp servers                       | -                                     | `:Opencode mcp`                             | `require('opencode.api').mcp()`                                        |
 | Run user commands                                           | -                                     | `:Opencode run user_command`                | `require('opencode.api').run_user_command()`                           |
 | Share current session and get a link                        | -                                     | `:Opencode session share` / `/share`        | `require('opencode.api').share()`                                      |
@@ -979,6 +980,22 @@ When `port = 'auto'` is used, opencode.nvim:
 - Only kills the server when the last nvim instance exits (if `auto_kill = true`). Only applies to servers spawned by the plugin with `spawn_command`/`kill_command`.
 - Locally spawned servers will be killed automatically regardless of the auto_kill setting if they are the last nvim instance using them
 
+## 🎯 Skills
+
+Skills are reusable, installable instruction packs that enhance opencode.nvim with domain-specific workflows. Each skill provides its own behavior, prompts, and tool configurations.
+
+### Browsing Skills
+
+- **Via command:** Run `:Opencode skills` to open the skills picker
+- **Via slash command:** Type `/skills` in the input window to open the skills picker
+- **Via completion:** Type `/` in the input window and select a skill from the completion menu
+
+The skills picker displays each skill with its name, description, and full content rendered as markdown in the preview pane. Selecting a skill executes it directly — opening a session and sending the skill's content as a prompt.
+
+### Installing Skills
+
+See the [Opencode Skills Documentation](https://opencode.ai/docs/skills/) for how to discover and install community skills.
+
 ## User Commands and Slash Commands
 
 You can run predefined user commands and built-in slash commands from the input window by typing `/`. This opens a command picker where you can select a command to execute. The output of the command will be included in your prompt context.
@@ -993,6 +1010,7 @@ You can run predefined user commands and built-in slash commands from the input
 - `/agents_init` — Initialize/update AGENTS.md
 - `/help` — Show help
 - `/mcp` — Show MCP servers
+- `/skills` — Browse and select available skills
 - `/models` — Switch provider/model
 - `/variant` — Switch model variant
 - `/sessions` — Switch session

lua/opencode/api_client.lua

@@ -571,6 +571,15 @@ function OpencodeApiClient:_subscribe_to_global_events(directory, on_event)
   end)
 end
 
+-- Skill endpoints
+
+--- List all skills
+--- @param directory string|nil Directory path
+--- @return Promise<OpencodeSkill[]>
+function OpencodeApiClient:list_skills(directory)
+  return self:_call('/skill', 'GET', nil, { directory = directory })
+end
+
 -- Tool endpoints
 
 --- List all tool IDs (including built-in and dynamically registered)

lua/opencode/commands/handlers/surface.lua

@@ -120,6 +120,11 @@ M.actions.mcp = Promise.async(function()
   mcp_picker.pick()
 end)
 
+M.actions.skills = Promise.async(function()
+  local skill_picker = require('opencode.ui.skill_picker')
+  skill_picker.pick()
+end)
+
 M.command_defs = {
   help = {
     desc = 'Show this help message',
@@ -129,6 +134,10 @@ M.command_defs = {
     desc = 'Show user-defined commands',
     execute = M.actions.commands_list,
   },
+  skills = {
+    desc = 'Browse and select available skills',
+    execute = M.actions.skills,
+  },
   mcp = {
     desc = 'Show MCP server configuration',
     execute = M.actions.mcp,

lua/opencode/commands/slash.lua

@@ -23,8 +23,9 @@ local slash_command_presets = {
   ['/variant'] = { name = 'variant' },
   ['/new'] = { name = 'session', preset_args = { 'new' } },
   ['/redo'] = { name = 'redo' },
-  ['/sessions'] = { name = 'session', preset_args = { 'select' } },
-  ['/share'] = { name = 'session', preset_args = { 'share' } },
+  ['/sessions']      = { name = 'session', preset_args = { 'select' } },
+  ['/skills']        = { name = 'skills' },
+  ['/share']         = { name = 'session', preset_args = { 'share' } },
   ['/clear_selections'] = { name = 'clear_selections' },
   ['/clear_files'] = { name = 'clear_files' },
   ['/timeline'] = { name = 'timeline' },

lua/opencode/types.lua

@@ -34,6 +34,12 @@
 ---@field worktree string
 ---@field directory string
 
+---@class OpencodeSkill
+---@field name string
+---@field description string|nil
+---@field location string
+---@field content string
+
 ---@class OpencodeCommand
 ---@field description string
 ---@field agent string

lua/opencode/ui/completion.lua

@@ -8,11 +8,13 @@ function M.setup()
   local subagents_source = require('opencode.ui.completion.subagents')
   local commands_source = require('opencode.ui.completion.commands')
   local context_source = require('opencode.ui.completion.context')
+  local skills_source = require('opencode.ui.completion.skills')
 
   M.register_source(files_source.get_source())
   M.register_source(subagents_source.get_source())
   M.register_source(commands_source.get_source())
   M.register_source(context_source.get_source())
+  M.register_source(skills_source.get_source())
 
   table.sort(M._sources, function(a, b)
     return (a.priority or 0) > (b.priority or 0)

lua/opencode/ui/completion/skills.lua

@@ -0,0 +1,85 @@
+local icons = require('opencode.ui.icons')
+local Promise = require('opencode.promise')
+
+local M = {}
+
+local custom_kind = require('opencode.ui.completion.kind')
+
+---@type CompletionSource
+local skill_source = {
+  name = 'skills',
+  priority = 1,
+  custom_kind = custom_kind.register('skills', icons.get('skill')),
+  complete = Promise.async(function(context)
+    local config = require('opencode.config')
+    local expected_trigger = config.get_key_for_function('input_window', 'slash_commands') or '/'
+    if context.trigger_char ~= expected_trigger then
+      return {}
+    end
+
+    if not context.line:match('^' .. vim.pesc(expected_trigger) .. '[^%s/]*$') then
+      return {}
+    end
+
+    local state = require('opencode.state')
+    local api_client = state and state.api_client
+    if not api_client then
+      return {}
+    end
+
+    local ok, skills = pcall(function()
+      return api_client:list_skills():await()
+    end)
+    if not ok or not skills then
+      return {}
+    end
+    ---@cast skills OpencodeSkill[]
+
+    local items = {}
+
+    for _, skill in ipairs(skills) do
+      local item = {
+        label = expected_trigger .. skill.name,
+        kind = 'skill',
+        kind_icon = icons.get('skill'),
+        detail = skill.description or '',
+        insert_text = skill.name .. ' ',
+        source_name = 'skills',
+        data = {
+          name = skill.name,
+          content = skill.content,
+        },
+      }
+      table.insert(items, item)
+    end
+
+    local sort_util = require('opencode.ui.completion.sort')
+    sort_util.sort_by_relevance(items, context.input)
+
+    return items
+  end),
+  on_complete = function(item)
+    if item.kind ~= 'skill' or not item.data or not item.data.content then
+      return
+    end
+
+    vim.defer_fn(function()
+      require('opencode.services.session_runtime').open({ new_session = false, focus = 'output' }):and_then(function()
+        return require('opencode.services.messaging').send_message(item.data.content, {})
+      end)
+    end, 10)
+    require('opencode.ui.input_window').set_content('')
+  end,
+  get_trigger_character = function()
+    local config = require('opencode.config')
+    return config.get_key_for_function('input_window', 'slash_commands') or '/'
+  end,
+}
+
+---Get the skill completion source
+---@return CompletionSource
+function M.get_source()
+  return skill_source
+end
+
+return M

lua/opencode/ui/skill_picker.lua

@@ -0,0 +1,80 @@
+local base_picker = require('opencode.ui.base_picker')
+local Promise = require('opencode.promise')
+
+local M = {}
+
+---@param skill OpencodeSkill
+---@param width number
+---@return PickerItem
+local function format_skill_item(skill, width)
+  width = width or vim.api.nvim_win_get_width(0)
+  local desc_width = math.max(20, width - 30)
+  local desc = skill.description or ''
+  if #desc > desc_width then
+    desc = desc:sub(1, desc_width - 3) .. '...'
+  end
+  return base_picker.create_picker_item({
+    { text = base_picker.align(skill.name, 20, { truncate = true }), highlight = 'OpencodeFile' },
+    { text = desc, highlight = 'OpencodeHint' },
+  })
+end
+
+---@param skill OpencodeSkill
+---@param target PickerPreviewTarget
+local function preview_skill(skill, target)
+  if not skill or not skill.content then
+    return
+  end
+
+  local lines = vim.split(skill.content, '\n')
+  target:set_lines(lines)
+
+  local bufnr = target:get_bufnr()
+  if bufnr then
+    vim.bo[bufnr].filetype = 'markdown'
+  end
+end
+
+---Show skills picker
+function M.pick()
+  local state = require('opencode.state')
+  local ui = require('opencode.ui.ui')
+  local input_window = require('opencode.ui.input_window')
+
+  local ok, skills = pcall(function()
+    return state.api_client:list_skills():await()
+  end)
+
+  if not ok or not skills then
+    vim.notify('Failed to fetch skills: ' .. tostring(skills), vim.log.levels.ERROR)
+    return
+  end
+
+  if #skills == 0 then
+    vim.notify('No skills available', vim.log.levels.WARN)
+    return
+  end
+
+  local callback = function(selected)
+    if not selected then
+      return
+    end
+
+    ui.focus_input()
+    input_window.set_content('/' .. selected.name .. ' ')
+    vim.api.nvim_win_set_cursor(state.windows.input_win, { 1, #selected.name + 2 })
+  end
+
+  base_picker.pick({
+    items = skills,
+    format_fn = format_skill_item,
+    actions = {},
+    callback = callback,
+    title = 'Skills',
+    width = 65,
+    preview = 'custom',
+    preview_fn = preview_skill,
+  })
+end
+
+return M

tests/unit/completion_spec.lua

@@ -33,6 +33,7 @@ describe('opencode.ui.completion', function()
     package.loaded['opencode.ui.completion.subagents'] = nil
     package.loaded['opencode.ui.completion.commands'] = nil
     package.loaded['opencode.ui.completion.context'] = nil
+    package.loaded['opencode.ui.completion.skills'] = nil
 
     completion = require('opencode.ui.completion')
     completion._sources = {}
@@ -48,10 +49,11 @@ describe('opencode.ui.completion', function()
     package.loaded['opencode.ui.completion.subagents'] = nil
     package.loaded['opencode.ui.completion.commands'] = nil
     package.loaded['opencode.ui.completion.context'] = nil
+    package.loaded['opencode.ui.completion.skills'] = nil
   end)
 
   describe('setup', function()
-    it('registers all four built-in sources', function()
+    it('registers all built-in sources', function()
       local registered = {}
 
       package.loaded['opencode.ui.completion.files'] = {
@@ -74,6 +76,11 @@ describe('opencode.ui.completion', function()
           return { name = 'context', priority = 1, complete = function() end }
         end,
       }
+      package.loaded['opencode.ui.completion.skills'] = {
+        get_source = function()
+          return { name = 'skills', priority = 1, complete = function() end }
+        end,
+      }
 
       package.loaded['opencode.ui.completion'] = nil
       completion = require('opencode.ui.completion')
@@ -82,7 +89,7 @@ describe('opencode.ui.completion', function()
       completion.setup()
 
       local sources = completion.get_sources()
-      assert.are.equal(4, #sources)
+      assert.are.equal(5, #sources)
 
       for _, s in ipairs(sources) do
         registered[s.name] = true
@@ -91,6 +98,7 @@ describe('opencode.ui.completion', function()
       assert.is_true(registered['subagents'])
       assert.is_true(registered['commands'])
       assert.is_true(registered['context'])
+      assert.is_true(registered['skills'])
     end)
 
     it('sorts sources in descending priority order after setup', function()
@@ -114,6 +122,11 @@ describe('opencode.ui.completion', function()
           return { name = 'context', priority = 1, complete = function() end }
         end,
       }
+      package.loaded['opencode.ui.completion.skills'] = {
+        get_source = function()
+          return { name = 'skills', priority = 1, complete = function() end }
+        end,
+      }
 
       package.loaded['opencode.ui.completion'] = nil
       completion = require('opencode.ui.completion')
@@ -148,6 +161,11 @@ describe('opencode.ui.completion', function()
           return { name = 'context', complete = function() end } -- no priority
         end,
       }
+      package.loaded['opencode.ui.completion.skills'] = {
+        get_source = function()
+          return { name = 'skills', priority = 1, complete = function() end }
+        end,
+      }
 
       package.loaded['opencode.ui.completion'] = nil
       completion = require('opencode.ui.completion')
@@ -158,7 +176,7 @@ describe('opencode.ui.completion', function()
       end)
 
       local sources = completion.get_sources()
-      assert.are.equal(4, #sources)
+      assert.are.equal(5, #sources)
     end)
   end)
 end)