Skills and Commands Loader
Relevant source files
The following files were used as context for generating this wiki page:
The Skills and Commands Loader is a core architectural component of the OhMyOpenCode ecosystem designed to dynamically discover, parse, and inject specialized capabilities into AI agents. It enables agents to move beyond generic instruction sets by loading domain-specific "skills" (defined in Markdown files) and executing built-in commands like /init-deep to manage project-wide knowledge bases. Sources: [src/features/opencode-skill-loader/AGENTS.md], [src/features/builtin-commands/templates/init-deep.ts]
This system operates on a multi-scope priority model, ensuring that project-specific or user-defined skills override global defaults. By combining domain-optimized categories with these loadable skills, the loader provides the technical foundation for autonomous workflows such as deep codebase exploration, strategic planning, and visual engineering. Sources: [src/features/opencode-skill-loader/AGENTS.md:7-14], [src/agents/dynamic-agent-category-skills-guide.ts:50-70]
Skill Discovery and Resolution Architecture
The loader implements a hierarchical discovery mechanism that scans four distinct scopes for SKILL.md files. This allows for fine-grained control over agent behavior depending on the environment.
4-Scope Priority Model
The loader resolves conflicts by applying a "highest to lowest" priority sequence. If a skill with the same name exists in multiple scopes, the higher-priority version is used.
| Priority | Scope | Location |
|---|---|---|
| 1 | Project | .opencode/skills/ |
| 2 | OpenCode Config | ~/.config/opencode/skills/ |
| 3 | User Config | ~/.config/opencode/oh-my-opencode/skills/ |
| 4 | Global | Built-in system skills |
Sources: [src/features/opencode-skill-loader/AGENTS.md:7-16]
Data Flow for Skill Loading
The following diagram illustrates the lifecycle of a skill from discovery on disk to resolution in the agent's context.
The system uses specialized modules like merger.ts for deduplication and skill-template-resolver.ts to substitute dynamic variables such as {{directory}} or {{agent}} into the skill content at runtime. Sources: [src/features/opencode-skill-loader/AGENTS.md:18-35]
Dynamic Skill Injection in Agents
Agents such as Hephaestus and Sisyphus utilize the task() function to combine domain-optimized categories with specific skills. This injection happens through the load_skills parameter, which triggers the loader to fetch the relevant Markdown instructions and tools.
Category and Skill Selection Protocol
Agents follow a mandatory two-step protocol to equip themselves for complex tasks:
- Select Category: Match the task domain (e.g.,
visual-engineeringfor UI work). - Evaluate Skills: Check the
skilltool for availability and include all that overlap with the task domain.
Sources: [src/agents/dynamic-agent-category-skills-guide.ts:50-70], [src/agents/hephaestus/gpt-5-4.ts:400-415]
Implementation Snippet
Skills are defined using Markdown with a YAML frontmatter block that specifies required tools and Model Context Protocol (MCP) configurations.
---
name: my-skill
description: Custom toolset
tools: [Bash, Read, Write]
mcp:
- name: server-1
type: stdio
command: npx
---
Skill instructions...
Sources: [src/features/opencode-skill-loader/AGENTS.md:37-51]
Built-in Command: /init-deep
The loader supports the execution of complex built-in commands designed to initialize or maintain project state. The /init-deep command is a primary example, used to generate hierarchical AGENTS.md files across a repository.
Command Execution Workflow
The /init-deep command utilizes parallel execution tracks to analyze codebase concentration and generate documentation.
- Discovery: Fires background explore agents to find entry points, conventions, and anti-patterns.
- Scoring: Uses a matrix (file count, symbol density, exports) to decide where
AGENTS.mdfiles are needed. - Generation: Writes or edits Markdown files based on identified locations.
Sources: [src/features/builtin-commands/templates/init-deep.ts:16-50]
Scoring Matrix for Command Logic
The command evaluates directories using the following weighted criteria:
| Factor | Weight | Source |
|---|---|---|
| File Count | 3x | Bash |
| Reference Centrality | 3x | LSP |
| Symbol Density | 2x | LSP |
| Module Boundary | 2x | File System |
Sources: [src/features/builtin-commands/templates/init-deep.ts:120-135]
Agent-Specific Integration Strategies
Different agents interact with the loader based on their model-specific optimizations.
Prometheus (Strategic Planning)
Prometheus uses the loader to equip research subagents (explore, librarian) during its "Grounding" phase. It creates work plans in .sisyphus/plans/ that explicitly specify which skills the implementing agent should load. Sources: [src/agents/prometheus/gpt.ts:100-120], [src/agents/prometheus/identity-constraints.ts:150-165]
Hephaestus (Autonomous Deep Worker)
Hephaestus is programmed to load relevant skills immediately upon identifying a domain overlap. It treats "user-installed skills" as priority overrides to ensure it follows project-specific conventions over built-in defaults. Sources: [src/agents/hephaestus/gpt-5-4.ts:120-135], [src/agents/dynamic-agent-category-skills-guide.ts:10-30]
The Skills and Commands Loader serves as the intelligence-routing layer of the project. By managing a tiered hierarchy of loadable Markdown skills and providing structured command templates like /init-deep, it ensures that AI agents remain context-aware and capable of executing specialized engineering tasks with high precision. Sources: [src/features/opencode-skill-loader/AGENTS.md], [src/agents/sisyphus.ts:100-110]