AGENT SKILL

skill-loading-system

Explain or troubleshoot OpenCode skill discovery, loading, permissions, availability, or prompt injection.

License 许可
MIT
所属仓库
xiaden/SkyScow
最近更新
2026-09-30
Stars
★ 1
Forks
0

01 前言 Front Matter

name
skill-loading-system
description
Explain or troubleshoot OpenCode skill discovery, loading, permissions, availability, or prompt injection.

03 SKILL.md 正文

OpenCode Skill Loading System

Mental Model

Skills are discoverable knowledge packages loaded from the filesystem (SKILL.md files), remote URLs (index.json), or the binary itself (embedded/built-in). The system has a four-stage pipeline: Discovery → Parse & Load → Permission Filter → Format & Inject. The critical architectural insight: skill discovery is permissive (load everything found), but skill availability in the prompt is filtered by session permissions, description presence, and prompt formatting mode.

Pipeline Stages

1. Discovery (Skill.discovery → Ej)

Scans configured directories for SKILL.md files using glob patterns:

Pattern Scope Description
skills/**/SKILL.md Global (+ parent dirst up from project) Legacy Claude Code skills
{skill,skills}/**/SKILL.md Per config entry From each config directory entry (project .opencode/, ~/.config/opencode/)
**/SKILL.md Per configured skills.paths From user-configured paths in opencode.json
index.json fetch Per configured skills.urls From remote URL skill registries

Controlled by:

  • OPENCODE_DISABLE_EXTERNAL_SKILLS env var → disableExternalSkills flag
  • OPENCODE_DISABLE_CLAUDE_CODE / OPENCODE_DISABLE_CLAUDE_CODE_SKILLS → disableClaudeCodeSkills flag
  • ~/.claude/ and ~/.agents/ directories are scanned by default (unless disabled)

2. Parse & Load (hj + mj)

For each discovered SKILL.md:

  1. Parsed via Tj.parse(Y) (frontmatter parser)
  2. Validated: must have name: string and optional description: string
  3. If duplicate name detected: logs a warning but overwrites (last one wins)
  4. Stored in state map: { name, description, location, content }

Built-in skill: customize-opencode is always injected first (hardcoded content in the binary).

3. Permission Filter (Skill.available → w)

w = j.fn("Skill.available")(function*(K){
  let G=yield*W.get(A), // get all skills
  N = Object.values(G.skills).toSorted();
  if(!K) return N;  // no permissions context → return all
  return N.filter((V)=>y.evaluate("skill", V.name, K.permission).action !== "deny");
});

Skills are filtered by evaluating evaluate("skill", skillName, sessionPermissions). If the session's permission rules deny a specific skill name, it's removed from the list.

4. Format & Inject (Two Code Paths)

Path A: SkillGuidance.load (system prompt context injection)

Used by the system context infrastructure (N$ service). Returns a SystemContext entry with name, description fields:

  • Filters out skills with description === void 0
  • If zero skills AND skill:* permission is denied → returns empty
  • Uses R7 formatter to produce <available_skills> XML block
  • Includes diff tracking: baseline function for initial render, update function for changes

Path B: Direct session prompt assembly

Used in the LLM session initialization:

  • Checks if session has "skill" capability
  • Calls available(d) to get filtered list
  • Uses tl.fmt(s, {verbose: true}) which adds <location> tags with file:// URLs

The <available_skills> Block Format

Generated by R7 function:

Skills provide specialized instructions and workflows for specific tasks.
Use the skill tool to load a skill when a task matches its description.
<available_skills>
  <skill>
    <name>skill-name</name>
    <description>What the skill does</description>
  </skill>
</available_skills>

The verbose format (Path B) also includes:

  <skill>
    <name>...</name>
    <description>...</description>
    <location>file:///path/to/SKILL.md</location>
  </skill>

If no skills available: "No skills are currently available."

The skill Tool (Loading On-Demand)

The native skill tool:

  1. Takes parameter { name: string } — annotated as "The name of the skill from available_skills"
  2. Calls Skill.require(name) — looks up the skill in state, throws Skill.NotFoundError with the list of available skill names if not found
  3. Asks for permission: { permission: "skill", patterns: [skillName], always: [skillName] }
  4. Returns skill content wrapped in <skill_content name="..."> and <skill_files> XML
  5. Includes sample of non-SKILL.md files in the skill directory

Sources (in discovery order)

  • Built-in: customize-opencode (always present)
  • Global legacy: ~/.claude/skills/**/SKILL.md, ~/.agents/skills/**/SKILL.md (unless disabled)
  • Parent directory walk: Up from project root looking for .claude/, .agents/
  • Config entries: {dir}/skill/**/SKILL.md, {dir}/skills/**/SKILL.md for each config source
  • Configured paths: From opencode.json → skills.paths
  • Remote URLs: From opencode.json → skills.urls (fetches index.json with format { skills: [{ name, files[] }] })

Inconsistent Availability — Causes

  1. Permission filtering: Skills can appear in Skill.all() but not in Skill.available(session) if session permissions deny them.
  2. Undefined descriptions: SkillGuidance.load FILTERS OUT skills with description === void 0.
  3. Name collision: Last-loaded skill with a given name wins (overwrites prior). Order depends on file system traversal order.
  4. Environment variables: OPENCODE_DISABLE_EXTERNAL_SKILLS / OPENCODE_DISABLE_CLAUDE_CODE_SKILLS prevent whole categories from being discovered.
  5. Config loading order: Different config sources (project .opencode/opencode.json vs global ~/.config/opencode/opencode.json) contribute different skills.paths and skills.urls.
  6. Two prompt paths: Path A and Path B may produce different lists since Path B uses the verbose formatter and Path A uses the simpler R7 formatter with the description filter.
  7. Async race: Discovery parsing uses concurrency: "unbounded" for file loading — though internally consistent, the order of processing is non-deterministic.

Sources

  • /usr/local/bin/opencode (compiled Bun binary) — all skill service logic is in the binary itself
  • /home/opencode/.config/opencode/node_modules/@opencode-ai/sdk/dist/v2/gen/types.gen.d.ts — TypeScript types for SkillV2Info, SkillV2Source, config schema
  • /home/opencode/.config/opencode/node_modules/@opencode-ai/plugin/dist/v2/effect/skill.d.ts — Plugin skill hooks type definitions
  • /home/opencode/.config/opencode/skills/making-editing-skills/SKILL.md — Skill authoring conventions (user documentation)
  • /home/opencode/.config/opencode/agents/agent.md — Agent-level skill usage instructions

04 同仓库更多 Skills