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_SKILLSenv var →disableExternalSkillsflagOPENCODE_DISABLE_CLAUDE_CODE/OPENCODE_DISABLE_CLAUDE_CODE_SKILLS→disableClaudeCodeSkillsflag~/.claude/and~/.agents/directories are scanned by default (unless disabled)
2. Parse & Load (hj + mj)
For each discovered SKILL.md:
- Parsed via
Tj.parse(Y)(frontmatter parser) - Validated: must have
name: stringand optionaldescription: string - If duplicate name detected: logs a warning but overwrites (last one wins)
- 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
R7formatter to produce<available_skills>XML block - Includes diff tracking:
baselinefunction for initial render,updatefunction 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:
- Takes parameter
{ name: string }— annotated as "The name of the skill from available_skills" - Calls
Skill.require(name)— looks up the skill in state, throwsSkill.NotFoundErrorwith the list of available skill names if not found - Asks for permission:
{ permission: "skill", patterns: [skillName], always: [skillName] } - Returns skill content wrapped in
<skill_content name="...">and<skill_files>XML - 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.mdfor each config source - Configured paths: From
opencode.json→skills.paths - Remote URLs: From
opencode.json→skills.urls(fetchesindex.jsonwith format{ skills: [{ name, files[] }] })
Inconsistent Availability — Causes
- Permission filtering: Skills can appear in
Skill.all()but not inSkill.available(session)if session permissions deny them. - Undefined descriptions:
SkillGuidance.loadFILTERS OUT skills withdescription === void 0. - Name collision: Last-loaded skill with a given name wins (overwrites prior). Order depends on file system traversal order.
- Environment variables:
OPENCODE_DISABLE_EXTERNAL_SKILLS/OPENCODE_DISABLE_CLAUDE_CODE_SKILLSprevent whole categories from being discovered. - Config loading order: Different config sources (project
.opencode/opencode.jsonvs global~/.config/opencode/opencode.json) contribute differentskills.pathsandskills.urls. - 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
R7formatter with the description filter. - 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 forSkillV2Info,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
unquoted-colon
暂无简介
quoted-description
Use when a plain scalar contains a colon: like this one.
block-description
Use when a plain scalar contains a colon: like this one.
work-routing
Canonical authority for who owns the next unit of work — direct work versus delegation, task tiers, bounded localization, the Change DAG size threshold, R&D evaluation routing, progressive research escalation, researcher scope signals, and QA/support owner selection. Use before choosing execution, investigation, design, or QA ownership; do not use to construct dispatch prompts, handoff schemas, or Change DAG/DD tool operation.
update-docs
Update project documentation to match code changes — generate codemaps, refresh READMEs, detect doc/code drift using AST analysis. Use when updating documentation after code changes, generating codemaps, verifying doc accuracy, or detecting stale documentation. Do NOT use for writing API reference docs from scratch (use doc-coauthoring) or for creating new skill files (use making-editing-skills).
security-review
Review code or agent/tool configuration for security vulnerabilities using OWASP and AgentShield checks. Use for auth, data exposure, injection, secrets, XSS, deserialization, or security-sensitive agent, MCP, or plugin changes.