Skill Loading
“Load Only When Needed”
Inject specialized knowledge only when the task actually needs it.
Skills are SKILL.md files with YAML frontmatter. They load in strict priority order: project-level skills take precedence, followed by personal skills, then built-in defaults. A higher-priority skill shadows any skill sharing its name at a lower tier. The skill tool loads content on demand, injecting it into context only when the agent requests it.
Architecture Flow
The Problem: How to Inject Specialized Knowledge Without Overloading Context
A general-purpose coding agent cannot know every framework, library, or project convention in advance. Pre-loading all possible knowledge would exhaust the context window. The solution is an on-demand skill system: skills are markdown files with structured metadata, stored in a priority-ordered directory tree. The skill tool loads content only when the agent explicitly requests it or when a task description matches a skill's declared purpose. This approach keeps the context window lean while making specialized knowledge available precisely when needed.
Priority-Based Loading: Predictable Override
The three-tier priority system (project, personal, built-in) makes loading behavior fully deterministic. A project-level skill always wins, so there is no ambiguity about which version of a skill like 'react-testing' takes effect. This design allows organizations to distribute standard skills through their repository, lets individual developers override skills to match their preferences, and enables opencode itself to ship sensible defaults. The load_skill() function iterates directories in priority order and returns the first match, short-circuiting on success.
Design Decisions
Skill descriptions serve double duty: the agent uses them to discover relevant skills at runtime. When encountering an unfamiliar task, the agent scans available descriptions and requests the matching skill. This is a form of just-in-time knowledge retrieval.
Skills are pure markdown with no executable code. This guarantees safe loading from untrusted repositories. A skill file cannot execute arbitrary code or modify agent behavior beyond providing textual context.
Comparison: Claude Code
Both systems support SKILL.md-based skill loading. OpenCode's three-tier priority chain (project, user, built-in) is more explicit than Claude Code's implicit discovery mechanism. The priority system means a project skill overrides a personal skill, which in turn overrides a built-in default. This is essential for team environments where project-level standards must take precedence.
Deep Dive: Design Decisions
SKILL.md as the Unit of Knowledge
Each skill is a single SKILL.md file with YAML frontmatter (name, description) and markdown body. This is the simplest possible format that's both human-readable and machine-parseable.
Three-Level Priority Loading
Skills are loaded in priority order: project skills first, then personal skills, then built-in skills. Higher-priority skills shadow lower-priority ones with the same name, allowing customization without modifying base skills.