The Skills System provides domain-specific capability extensions through SKILL.md files that combine system instructions, tool permissions, and Model Context Protocol (MCP) server configurations. Skills are discovered from four hierarchical scopes, injected into agent prompts, and managed by a dedicated loader system.
Skills are self-contained capability units that provide:
.mcp.json files [packages/omo-opencode/src/features/AGENTS.md:18-18].allowedTools when a skill is active [packages/omo-opencode/src/features/builtin-skills/skills.test.ts:31-32].Sources: [packages/omo-opencode/src/features/AGENTS.md:61-66], [packages/omo-opencode/src/features/builtin-skills/skills.ts:27-63]
Skills are discovered from multiple primary scopes with priority-based deduplication. The opencode-skill-loader module handles YAML frontmatter parsing and priority merging [packages/omo-opencode/src/features/AGENTS.md:61-66].
| Priority | Scope | Directory Context | Implementation |
|---|---|---|---|
| 1 | Project | <project>/.opencode/skills/ | discoverOpencodeProjectSkills [packages/omo-opencode/src/features/AGENTS.md:63-63] |
| 2 | Opencode | ~/.config/opencode/skills/ | discoverOpencodeGlobalSkills [packages/omo-opencode/src/features/AGENTS.md:63-63] |
| 3 | User | ~/.config/claude/skills/ | discoverUserClaudeSkills [packages/omo-opencode/src/features/AGENTS.md:63-63] |
| 4 | Global | Shared internal skills | discoverGlobalSkills [packages/omo-opencode/src/features/AGENTS.md:63-63] |
The system uses a walk-up discovery mechanism for AGENTS.md and SKILL.md files, ensuring that project-specific rules take precedence over global defaults [packages/AGENTS.md:45-45].
This diagram bridges the Natural Language "Skill Name" to the Code Entity LoadedSkill.
Sources: [packages/omo-opencode/src/features/AGENTS.md:16-16], [packages/AGENTS.md:55-55]
Skills are defined using YAML frontmatter followed by markdown content. The metadata is parsed to determine tool permissions and MCP requirements.
The following fields are typically parsed from the SKILL.md header:
name: Unique identifier for the skill (e.g., git-master).description: Human-readable purpose.allowedTools: A list of tools permitted during skill execution [packages/omo-opencode/src/features/builtin-skills/skills.test.ts:31-32].mcpConfig: Configuration for the skill-mcp-manager to spawn required servers [packages/omo-opencode/src/features/AGENTS.md:18-18].Skills can define MCP servers that are managed by the skill-mcp-manager [packages/omo-opencode/src/features/AGENTS.md:18-18]. This adapter layer provides the OpenCode runtime with a tier-3 MCP client lifecycle, supporting OAuth 2.0 + PKCE for authenticated servers [packages/omo-opencode/src/features/AGENTS.md:21-21].
Sources: [packages/omo-opencode/src/features/AGENTS.md:18-21], [packages/AGENTS.md:56-56]
The skill tool allows agents to discover and evaluate available skills at runtime.
Sources: [packages/omo-opencode/src/features/AGENTS.md:16-18], [packages/omo-opencode/src/features/builtin-skills/skills.test.ts:7-19]
The system includes 12 "batteries-included" skills that are automatically registered and managed.
| Skill | Purpose | Notes |
|---|---|---|
git-master | Atomic commits, rebase, history search | 1111 LOC implementation [packages/omo-opencode/src/features/AGENTS.md:76-76] |
playwright | Browser automation via MCP | Default browser engine [packages/omo-opencode/src/features/AGENTS.md:77-77] |
review-work | 5-agent post-implementation review | Orchestrates parallel review lanes [packages/omo-opencode/src/features/AGENTS.md:80-80] |
remove-ai-slops | Automated code pattern cleanup | Removes common AI-generated slop [packages/omo-opencode/src/features/AGENTS.md:81-81] |
team-mode | Parallel multi-agent coordination | Only loaded if team_mode.enabled [packages/omo-opencode/src/features/AGENTS.md:85-85] |
The system utilizes two specific hooks in the Skill Tier to manage awareness:
categorySkillReminder: Hints to load relevant skills before invoking categories [packages/omo-opencode/src/hooks/AGENTS.md:100-100].autoSlashCommand: Automatically executes matching /command from user messages [packages/omo-opencode/src/hooks/AGENTS.md:101-101].Sources: [packages/omo-opencode/src/features/AGENTS.md:72-87], [packages/omo-opencode/src/hooks/AGENTS.md:96-101]