Skills System & Skill Loader
Relevant source files
The following files were used as context for generating this wiki page:
The Skills System is a modular framework designed to inject specialized domain expertise and technical instructions into AI agents. By loading specific "skills," agents gain access to tailored workflows, aesthetic guidelines, and restricted toolsets that enhance their performance in targeted areas like Git operations, browser automation, or UI/UX design.
The Skill Loader serves as the discovery and management engine for these skills. It handles the asynchronous loading of skill definitions from multiple sources—including built-in plugin skills, project-specific skills, and user-defined skills—parsing their metadata, frontmatter, and associated Model Context Protocol (MCP) configurations.
Sources: src/tools/skill/tools.ts, src/agents/dynamic-agent-prompt-builder.ts, sisyphus-prompt.md
Architecture and Core Components
The system is built on a tiered discovery model that prioritizes specialized expertise. Skills are not just static prompts; they are dynamic objects that can include specialized instructions, MCP server configurations, and restricted access to specific tools.
Skill Hierarchy and Scopes
Skills are categorized by their location and intended scope, allowing for flexible overrides and environment-specific behaviors:
| Scope | Description | Priority |
|---|---|---|
| Plugin (Built-in) | Core skills provided by the OhMyOpenCode package (e.g., git-master, playwright). | Standard |
| Project | Skills defined within the .opencode/skills directory of a specific repository. | High |
| User | Custom skills defined in the user's global configuration directory. | Highest |
Sources: src/agents/dynamic-agent-prompt-builder.ts:18-22, src/features/opencode-skill-loader/async-loader.test.ts:44-55
Component Interaction Flow
The following diagram illustrates how the Skill Loader discovers skills and how they are eventually consumed by the Skill Tool to equip agents.
The Loader scans directories for SKILL.md files or named markdown files, parses YAML frontmatter for metadata, and checks for companion mcp.json files.
Sources: src/features/opencode-skill-loader/async-loader.test.ts:71-100, src/tools/skill/tools.ts:162-175
Skill Loading and Discovery Logic
The system utilizes an asynchronous discovery mechanism to identify valid skills without blocking the main agent execution loop.
Metadata Parsing
Skills are defined in Markdown files with YAML frontmatter. The loader extracts key information such as the name, description, and specific model constraints.
{
"name": "example-skill",
"description": "Domain expertise description",
"mcp": {
"server-name": {
"command": "npx",
"args": ["@mcp/server"]
}
}
}
Sources: src/features/opencode-skill-loader/async-loader.test.ts:133-145
Concurrency and Performance
The async-loader implements mapWithConcurrency to process items with a default limit (e.g., 16), ensuring that large directories of custom skills do not lead to file descriptor exhaustion or significant latency.
Sources: src/features/opencode-skill-loader/async-loader.test.ts:187-200
The Skill Tool and Agent Interaction
The skill tool is the primary interface through which an orchestrator agent (like Atlas or Sisyphus) retrieves specialized instructions to pass to subagents.
Tool Execution Flow
When the skill tool is invoked with a specific name, it performs the following steps:
- Validation: Checks if the skill exists and if the calling agent is authorized to use it.
- Template Extraction: Retrieves the
<skill-instruction>block from the markdown content. - Dynamic Injection: For complex skills like
git-master, it may inject environment-specific configurations. - MCP Discovery: If the skill has associated MCP servers, the tool queries the
SkillMcpManagerto list available tools, resources, and prompts provided by that skill.
Sources: src/tools/skill/tools.ts:162-212
Skill Evaluation Protocol
Orchestrators are governed by a strict protocol for delegation. Before calling a subtask, the orchestrator must evaluate all available skills and justify why each was included or omitted.
| Phase | Requirement |
|---|---|
| Evaluation | Scan all Built-in and User-installed skills. |
| Priority | User-installed skills get priority; when in doubt, include them. |
| Justification | If a skill matches the task domain but is omitted, the agent MUST state the reason in the prompt. |
Sources: src/agents/dynamic-agent-prompt-builder.ts:255-275, sisyphus-prompt.md:255-270
Specialized Built-in Skills
Several core skills are provided by default to handle critical engineering domains.
Git Master (git-master)
A complex skill that combines roles of a Commit Architect, Rebase Surgeon, and History Archaeologist. It enforces strict rules such as atomic commits and mandatory commit grouping by directory.
- Trigger: Phrases like 'commit', 'rebase', 'who changed'.
- Constraint: Hard rule against single giant commits (e.g., 3+ files must be 2+ commits).
Sources: src/features/builtin-skills/skills/git-master.ts:14-50
Frontend UI/UX (frontend-ui-ux)
Provides a "Designer-Turned-Developer" persona. It focuses on aesthetic choices like typography (avoiding Inter/Roboto), motion, and spatial composition.
- Mission: Create visually stunning interfaces even without mockups.
- Focus: Spacing, color harmony, and micro-interactions.
Sources: src/features/builtin-skills/skills/frontend-ui-ux.ts:5-15
Playwright
Mandatory skill for any browser-related tasks. It equips agents with instructions for using Playwright effectively for web automation and testing.
Sources: sisyphus-prompt.md:38, 71
Conclusion
The Skills System & Skill Loader provide a robust mechanism for scaling agent intelligence. By separating core reasoning from domain-specific expertise, the project allows agents to remain versatile while being capable of high-precision work in specialized fields. The loader's ability to discover local and global skills ensures the system remains extensible for users and specific projects.