AGENTS.md

1# src/tools/skill/ -- Skill and Command Loader Tool
2 
3**Generated:** 2026-05-18
4 
5## OVERVIEW
6 
7The `skill` tool. Dual purpose: (1) load a skill by name to inject its SKILL.md content into context, (2) invoke a slash command by name (omit leading slash). Skills may spin up embedded MCP servers on demand. Commands route through the autoSlashCommand hook.
8 
9## FILE CATALOG
10 
11| File | Purpose |
12|------|---------|
13| `tools.ts` | `createSkillTool` factory -- resolves name, loads body, returns formatted output |
14| `skill-body.ts` | Extracts `<skill-instruction>` block or full SKILL.md template |
15| `skill-matcher.ts` | Exact match, short-name fallback, partial-match suggestions |
16| `scope-priority.ts` | 4-scope priority: project (4) > user (3) > opencode (2) > builtin/plugin (1) |
17| `native-skills.ts` | Merges `PluginInput.skills` entries into discovered skill list |
18| `description-formatter.ts` | Builds LLM-visible `<available_items>` listing with scope tags |
19| `mcp-capability-formatter.ts` | Lists skill-embedded MCP tools/resources/prompts for `skill_mcp` calls |
20| `session-skill-cache.ts` | Dedupes repeated skill loads per session via `seenSessionIDs` |
21| `types.ts` | `SkillArgs`, `SkillInfo`, `SkillLoadOptions` |
22| `constants.ts` | Tool name and description prefix |
23| `index.ts` | Barrel exports |
24 
25## EXECUTION FLOW
26 
27```
28skill(name="git-master")
29  -> matchSkillByName()    # exact, then short-name
30  -> ask(permission)       # host skill permission gate
31  -> extractSkillBody()    # load SKILL.md content
32  -> formatMcpCapabilities()  # if skill has mcpConfig
33  -> return "## Skill: ..." + body + MCP info
34```
35 
36## SCOPE PRIORITY
37 
38Project configs override user configs, which override opencode builtins. `sortByScopePriority` applies to both skills and slash commands in the `<available_items>` listing.
39 
40## TEST MOCKS
41 
42`zauc-mocks-skill-tools/` -- `mock.module()` setup for skill tool tests. Loads alphabetically before consuming tests via the `zauc-` prefix sort-order hack.
43 
44## INTEGRATION
45 
46- Discovery: `opencode-skill-loader` feature module scans `.opencode/skills/`, `~/.config/opencode/skills/`, and built-in paths
47- MCP spawn: `skill-mcp-manager` feature module starts embedded MCP servers per session on demand
48- Commands: `slashcommand/` module feeds discovered commands into the tool description
49