How do plugins work and differ from skills?

how do plugins work? what's the diff between plugins and skils?

Now I have enough context. Here's a comprehensive answer:

##Plugins vs Skills: Key Differences

Plugins and Skills serve fundamentally different purposes in OpenCode:

###Skills = Reusable Instructions for the AI

Skills are markdown files (SKILL.md) that provide the AI with specialized knowledge and step-by-step guidance for specific tasks. They're essentially "prompt templates" or "instruction sets."

How they work:

• Defined as markdown files with YAML frontmatter in specific directories
• Discovered automatically at startup from:
  • .opencode/skills/<name>/SKILL.md (project)
  • ~/.config/opencode/skills/<name>/SKILL.md (global)
  • .claude/skills/<name>/SKILL.md (Claude-compatible)
• The AI can load them on-demand via the built-in skill tool
• Skills are listed to the AI, which decides when to use them based on the task

Example: A git-release skill might contain instructions on how to draft release notes and version bumps.

From packages/opencode/src/skill/skill.ts:

export const Info = z.object({
  name: z.string(),
  description: z.string(),
  location: z.string(),
})

###Plugins = Code Extensions That Hook Into OpenCode

Plugins are JavaScript/TypeScript modules that extend OpenCode's core functionality by hooking into various lifecycle events.

How they work:

• Can be loaded from:
  • Local files in .opencode/plugins/ or ~/.config/opencode/plugins/
  • npm packages specified in opencode.json
• Plugins export functions that return hooks - callbacks for various events
• They can modify behavior, add authentication methods, transform messages, etc.

Available hooks (from packages/plugin/src/index.ts):

Example: The CodexAuthPlugin adds OAuth authentication for OpenAI's Codex API.

###TL;DR Comparison

Skills = "Hey AI, here's how to do X"
Plugins = "Hey OpenCode, let me add/change functionality"