How does opencode SDK handle skills automatically?

how does opencode sdk handle skills? does it load them automatically?

Now I have a clear picture. Let me summarize how OpenCode SDK handles skills:

##How OpenCode SDK Handles Skills

###Skills are NOT loaded automatically into conversations

Skills in OpenCode are loaded on-demand, not automatically. Here's how the system works:

###1. Skill Discovery (at initialization)

When an OpenCode instance is created for a project, the Skill.state() function (packages/opencode/src/skill/skill.ts:44-127) lazily scans and discovers all available skills from multiple locations:

Project-level:
- .opencode/skill/<name>/SKILL.md
- .opencode/skills/<name>/SKILL.md
- .claude/skills/<name>/SKILL.md

Global:
- ~/.config/opencode/skills/<name>/SKILL.md
- ~/.claude/skills/<name>/SKILL.md

The discovery uses glob patterns:

• {skill,skills}/**/SKILL.md for OpenCode directories
• skills/**/SKILL.md for Claude-compatible directories

###2. Skill Metadata Exposed to Agents

The SkillTool (packages/opencode/src/tool/skill.ts) is registered in the tool registry. When the tool is initialized, it:

1. Fetches all discovered skills via Skill.all()
2. Filters them by agent permissions
3. Embeds their names and descriptions (not full content) into the tool's description:

<available_skills>
  <skill>
    <name>git-release</name>
    <description>How to create a release</description>
  </skill>
</available_skills>

###3. On-Demand Loading via Tool Call

The agent sees the available skills listed in the tool description. When the agent decides it needs a skill, it explicitly calls:

skill({ name: "git-release" })

Only then does OpenCode:

1. Verify the skill exists
2. Check permissions via ctx.ask()
3. Parse and return the full SKILL.md content

###4. SDK Access

The SDK exposes a /skill endpoint to list all available skills:

import { createOpencodeClient } from "@opencode-ai/sdk"

const client = createOpencodeClient()
const skills = await client.app.skills()

###Key Design Points:

This design keeps the system prompt lean—agents only see skill names/descriptions, and load the full instructions when actually needed.