AGENTS.md

1# src/features/opencode-skill-loader/ — 4-Scope Skill Discovery
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
725 files (~2.8k LOC). Discovers, parses, merges, and resolves SKILL.md files from 4 scopes with priority deduplication.
8 
9## 4-SCOPE PRIORITY (highest → lowest)
10 
11```
121. Project (.opencode/skills/)
132. OpenCode config (~/.config/opencode/skills/)
143. User (~/.config/opencode/oh-my-opencode/skills/)
154. Global (built-in skills)
16```
17 
18Same-named skill at higher scope overrides lower.
19 
20## KEY FILES
21 
22| File | Purpose |
23|------|---------|
24| `loader.ts` | Main `loadSkills()` — orchestrates discovery → parse → merge |
25| `merger.ts` | Priority-based deduplication across scopes |
26| `skill-content.ts` | YAML frontmatter parsing from SKILL.md |
27| `skill-discovery.ts` | Find SKILL.md files in directory trees |
28| `skill-directory-loader.ts` | Load all skills from a single directory |
29| `config-source-discovery.ts` | Discover scope directories from config |
30| `skill-template-resolver.ts` | Variable substitution in skill templates |
31| `skill-mcp-config.ts` | Extract MCP configs from skill YAML |
32| `types.ts` | `LoadedSkill`, `SkillScope`, `SkillDiscoveryResult` |
33 
34## SKILL FORMAT (SKILL.md)
35 
36```markdown
37---
38name: my-skill
39description: What this skill does
40tools: [Bash, Read, Write]
41mcp:
42  - name: my-mcp
43    type: stdio
44    command: npx
45    args: [-y, my-mcp-server]
46---
47 
48Skill content (instructions for the agent)...
49```
50 
51## MERGER SUBDIRECTORY
52 
53Handles complex merge logic when skills from multiple scopes have overlapping names or MCP configs.
54 
55## TEMPLATE RESOLUTION
56 
57Variables like `{{directory}}`, `{{agent}}` in skill content get resolved at load time based on current context.
58