[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7CTMSQD82CPD53C6F07J0R9":3,"skill-same:01M7CTMSQD82CPD53C6F07J0R9":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":27,"repositoryHtmlUrl":28,"repositoryHomepageUrl":6,"ownerHtmlUrl":29,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":30,"install":31,"resources":44},"01M7CTMSQD82CPD53C6F07J0R9","skill-loading-system",null,"Explain or troubleshoot OpenCode skill discovery, loading, permissions, availability, or prompt injection.","xiaden\u002FSkyScow","xiaden","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F3605480?v=4","01M7CTGKNTD1XNQE710J977HVD","Lucian Hardy","01M7CTGKPVQ3XRNXNRJ3A6E31F",1,"MIT","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Fskills\u002Fskill-loading-system\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: skill-loading-system\ndescription: Explain or troubleshoot OpenCode skill discovery, loading, permissions, availability, or prompt injection.\n---\n\n# OpenCode Skill Loading System\n\n## Mental Model\n\nSkills are discoverable knowledge packages loaded from the filesystem (SKILL.md files), remote URLs (index.json), or the binary itself (embedded\u002Fbuilt-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.\n\n## Pipeline Stages\n\n### 1. Discovery (`Skill.discovery` → `Ej`)\nScans configured directories for SKILL.md files using glob patterns:\n\n| Pattern | Scope | Description |\n|---------|-------|-------------|\n| `skills\u002F**\u002FSKILL.md` | Global (+ parent dirst up from project) | Legacy Claude Code skills |\n| `{skill,skills}\u002F**\u002FSKILL.md` | Per config entry | From each config directory entry (project `.opencode\u002F`, `~\u002F.config\u002Fopencode\u002F`) |\n| `**\u002FSKILL.md` | Per configured `skills.paths` | From user-configured paths in opencode.json |\n| `index.json` fetch | Per configured `skills.urls` | From remote URL skill registries |\n\n**Controlled by:**\n- `OPENCODE_DISABLE_EXTERNAL_SKILLS` env var → `disableExternalSkills` flag\n- `OPENCODE_DISABLE_CLAUDE_CODE` \u002F `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` → `disableClaudeCodeSkills` flag\n- `~\u002F.claude\u002F` and `~\u002F.agents\u002F` directories are scanned by default (unless disabled)\n\n### 2. Parse & Load (`hj` + `mj`)\nFor each discovered SKILL.md:\n1. Parsed via `Tj.parse(Y)` (frontmatter parser)\n2. Validated: must have `name: string` and optional `description: string`\n3. If duplicate name detected: logs a warning but **overwrites** (last one wins)\n4. Stored in state map: `{ name, description, location, content }`\n\n**Built-in skill:** `customize-opencode` is always injected first (hardcoded content in the binary).\n\n### 3. Permission Filter (`Skill.available` → `w`)\n\n```typescript\nw = j.fn(\"Skill.available\")(function*(K){\n  let G=yield*W.get(A), \u002F\u002F get all skills\n  N = Object.values(G.skills).toSorted();\n  if(!K) return N;  \u002F\u002F no permissions context → return all\n  return N.filter((V)=>y.evaluate(\"skill\", V.name, K.permission).action !== \"deny\");\n});\n```\n\nSkills 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.\n\n### 4. Format & Inject (Two Code Paths)\n\n#### Path A: `SkillGuidance.load` (system prompt context injection)\nUsed by the system context infrastructure (`N$` service). Returns a `SystemContext` entry with `name`, `description` fields:\n- Filters out skills with `description === void 0`\n- If zero skills AND `skill:*` permission is denied → returns empty\n- Uses `R7` formatter to produce `\u003Cavailable_skills>` XML block\n- Includes diff tracking: `baseline` function for initial render, `update` function for changes\n\n#### Path B: Direct session prompt assembly\nUsed in the LLM session initialization:\n- Checks if session has `\"skill\"` capability\n- Calls `available(d)` to get filtered list\n- Uses `tl.fmt(s, {verbose: true})` which adds `\u003Clocation>` tags with file:\u002F\u002F URLs\n\n## The `\u003Cavailable_skills>` Block Format\n\nGenerated by `R7` function:\n```\nSkills provide specialized instructions and workflows for specific tasks.\nUse the skill tool to load a skill when a task matches its description.\n\u003Cavailable_skills>\n  \u003Cskill>\n    \u003Cname>skill-name\u003C\u002Fname>\n    \u003Cdescription>What the skill does\u003C\u002Fdescription>\n  \u003C\u002Fskill>\n\u003C\u002Favailable_skills>\n```\n\nThe verbose format (Path B) also includes:\n```\n  \u003Cskill>\n    \u003Cname>...\u003C\u002Fname>\n    \u003Cdescription>...\u003C\u002Fdescription>\n    \u003Clocation>file:\u002F\u002F\u002Fpath\u002Fto\u002FSKILL.md\u003C\u002Flocation>\n  \u003C\u002Fskill>\n```\n\nIf no skills available: \"No skills are currently available.\"\n\n## The `skill` Tool (Loading On-Demand)\n\nThe native `skill` tool:\n1. Takes parameter `{ name: string }` — annotated as \"The name of the skill from available_skills\"\n2. Calls `Skill.require(name)` — looks up the skill in state, throws `Skill.NotFoundError` with the list of available skill names if not found\n3. Asks for permission: `{ permission: \"skill\", patterns: [skillName], always: [skillName] }`\n4. Returns skill content wrapped in `\u003Cskill_content name=\"...\">` and `\u003Cskill_files>` XML\n5. Includes sample of non-SKILL.md files in the skill directory\n\n## Sources (in discovery order)\n- **Built-in**: `customize-opencode` (always present)\n- **Global legacy**: `~\u002F.claude\u002Fskills\u002F**\u002FSKILL.md`, `~\u002F.agents\u002Fskills\u002F**\u002FSKILL.md` (unless disabled)\n- **Parent directory walk**: Up from project root looking for `.claude\u002F`, `.agents\u002F`\n- **Config entries**: `{dir}\u002Fskill\u002F**\u002FSKILL.md`, `{dir}\u002Fskills\u002F**\u002FSKILL.md` for each config source\n- **Configured paths**: From `opencode.json` → `skills.paths`\n- **Remote URLs**: From `opencode.json` → `skills.urls` (fetches `index.json` with format `{ skills: [{ name, files[] }] }`)\n\n## Inconsistent Availability — Causes\n\n1. **Permission filtering**: Skills can appear in `Skill.all()` but not in `Skill.available(session)` if session permissions deny them.\n2. **Undefined descriptions**: `SkillGuidance.load` FILTERS OUT skills with `description === void 0`.\n3. **Name collision**: Last-loaded skill with a given name wins (overwrites prior). Order depends on file system traversal order.\n4. **Environment variables**: `OPENCODE_DISABLE_EXTERNAL_SKILLS` \u002F `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` prevent whole categories from being discovered.\n5. **Config loading order**: Different config sources (project `.opencode\u002Fopencode.json` vs global `~\u002F.config\u002Fopencode\u002Fopencode.json`) contribute different `skills.paths` and `skills.urls`.\n6. **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.\n7. **Async race**: Discovery parsing uses `concurrency: \"unbounded\"` for file loading — though internally consistent, the *order* of processing is non-deterministic.\n\n## Sources\n- `\u002Fusr\u002Flocal\u002Fbin\u002Fopencode` (compiled Bun binary) — all skill service logic is in the binary itself\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fnode_modules\u002F@opencode-ai\u002Fsdk\u002Fdist\u002Fv2\u002Fgen\u002Ftypes.gen.d.ts` — TypeScript types for `SkillV2Info`, `SkillV2Source`, config schema\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fnode_modules\u002F@opencode-ai\u002Fplugin\u002Fdist\u002Fv2\u002Feffect\u002Fskill.d.ts` — Plugin skill hooks type definitions\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fskills\u002Fmaking-editing-skills\u002FSKILL.md` — Skill authoring conventions (user documentation)\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fagents\u002Fagent.md` — Agent-level skill usage instructions\n","# OpenCode Skill Loading System\n\n## Mental Model\n\nSkills are discoverable knowledge packages loaded from the filesystem (SKILL.md files), remote URLs (index.json), or the binary itself (embedded\u002Fbuilt-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.\n\n## Pipeline Stages\n\n### 1. Discovery (`Skill.discovery` → `Ej`)\nScans configured directories for SKILL.md files using glob patterns:\n\n| Pattern | Scope | Description |\n|---------|-------|-------------|\n| `skills\u002F**\u002FSKILL.md` | Global (+ parent dirst up from project) | Legacy Claude Code skills |\n| `{skill,skills}\u002F**\u002FSKILL.md` | Per config entry | From each config directory entry (project `.opencode\u002F`, `~\u002F.config\u002Fopencode\u002F`) |\n| `**\u002FSKILL.md` | Per configured `skills.paths` | From user-configured paths in opencode.json |\n| `index.json` fetch | Per configured `skills.urls` | From remote URL skill registries |\n\n**Controlled by:**\n- `OPENCODE_DISABLE_EXTERNAL_SKILLS` env var → `disableExternalSkills` flag\n- `OPENCODE_DISABLE_CLAUDE_CODE` \u002F `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` → `disableClaudeCodeSkills` flag\n- `~\u002F.claude\u002F` and `~\u002F.agents\u002F` directories are scanned by default (unless disabled)\n\n### 2. Parse & Load (`hj` + `mj`)\nFor each discovered SKILL.md:\n1. Parsed via `Tj.parse(Y)` (frontmatter parser)\n2. Validated: must have `name: string` and optional `description: string`\n3. If duplicate name detected: logs a warning but **overwrites** (last one wins)\n4. Stored in state map: `{ name, description, location, content }`\n\n**Built-in skill:** `customize-opencode` is always injected first (hardcoded content in the binary).\n\n### 3. Permission Filter (`Skill.available` → `w`)\n\n```typescript\nw = j.fn(\"Skill.available\")(function*(K){\n  let G=yield*W.get(A), \u002F\u002F get all skills\n  N = Object.values(G.skills).toSorted();\n  if(!K) return N;  \u002F\u002F no permissions context → return all\n  return N.filter((V)=>y.evaluate(\"skill\", V.name, K.permission).action !== \"deny\");\n});\n```\n\nSkills 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.\n\n### 4. Format & Inject (Two Code Paths)\n\n#### Path A: `SkillGuidance.load` (system prompt context injection)\nUsed by the system context infrastructure (`N$` service). Returns a `SystemContext` entry with `name`, `description` fields:\n- Filters out skills with `description === void 0`\n- If zero skills AND `skill:*` permission is denied → returns empty\n- Uses `R7` formatter to produce `\u003Cavailable_skills>` XML block\n- Includes diff tracking: `baseline` function for initial render, `update` function for changes\n\n#### Path B: Direct session prompt assembly\nUsed in the LLM session initialization:\n- Checks if session has `\"skill\"` capability\n- Calls `available(d)` to get filtered list\n- Uses `tl.fmt(s, {verbose: true})` which adds `\u003Clocation>` tags with file:\u002F\u002F URLs\n\n## The `\u003Cavailable_skills>` Block Format\n\nGenerated by `R7` function:\n```\nSkills provide specialized instructions and workflows for specific tasks.\nUse the skill tool to load a skill when a task matches its description.\n\u003Cavailable_skills>\n  \u003Cskill>\n    \u003Cname>skill-name\u003C\u002Fname>\n    \u003Cdescription>What the skill does\u003C\u002Fdescription>\n  \u003C\u002Fskill>\n\u003C\u002Favailable_skills>\n```\n\nThe verbose format (Path B) also includes:\n```\n  \u003Cskill>\n    \u003Cname>...\u003C\u002Fname>\n    \u003Cdescription>...\u003C\u002Fdescription>\n    \u003Clocation>file:\u002F\u002F\u002Fpath\u002Fto\u002FSKILL.md\u003C\u002Flocation>\n  \u003C\u002Fskill>\n```\n\nIf no skills available: \"No skills are currently available.\"\n\n## The `skill` Tool (Loading On-Demand)\n\nThe native `skill` tool:\n1. Takes parameter `{ name: string }` — annotated as \"The name of the skill from available_skills\"\n2. Calls `Skill.require(name)` — looks up the skill in state, throws `Skill.NotFoundError` with the list of available skill names if not found\n3. Asks for permission: `{ permission: \"skill\", patterns: [skillName], always: [skillName] }`\n4. Returns skill content wrapped in `\u003Cskill_content name=\"...\">` and `\u003Cskill_files>` XML\n5. Includes sample of non-SKILL.md files in the skill directory\n\n## Sources (in discovery order)\n- **Built-in**: `customize-opencode` (always present)\n- **Global legacy**: `~\u002F.claude\u002Fskills\u002F**\u002FSKILL.md`, `~\u002F.agents\u002Fskills\u002F**\u002FSKILL.md` (unless disabled)\n- **Parent directory walk**: Up from project root looking for `.claude\u002F`, `.agents\u002F`\n- **Config entries**: `{dir}\u002Fskill\u002F**\u002FSKILL.md`, `{dir}\u002Fskills\u002F**\u002FSKILL.md` for each config source\n- **Configured paths**: From `opencode.json` → `skills.paths`\n- **Remote URLs**: From `opencode.json` → `skills.urls` (fetches `index.json` with format `{ skills: [{ name, files[] }] }`)\n\n## Inconsistent Availability — Causes\n\n1. **Permission filtering**: Skills can appear in `Skill.all()` but not in `Skill.available(session)` if session permissions deny them.\n2. **Undefined descriptions**: `SkillGuidance.load` FILTERS OUT skills with `description === void 0`.\n3. **Name collision**: Last-loaded skill with a given name wins (overwrites prior). Order depends on file system traversal order.\n4. **Environment variables**: `OPENCODE_DISABLE_EXTERNAL_SKILLS` \u002F `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS` prevent whole categories from being discovered.\n5. **Config loading order**: Different config sources (project `.opencode\u002Fopencode.json` vs global `~\u002F.config\u002Fopencode\u002Fopencode.json`) contribute different `skills.paths` and `skills.urls`.\n6. **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.\n7. **Async race**: Discovery parsing uses `concurrency: \"unbounded\"` for file loading — though internally consistent, the *order* of processing is non-deterministic.\n\n## Sources\n- `\u002Fusr\u002Flocal\u002Fbin\u002Fopencode` (compiled Bun binary) — all skill service logic is in the binary itself\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fnode_modules\u002F@opencode-ai\u002Fsdk\u002Fdist\u002Fv2\u002Fgen\u002Ftypes.gen.d.ts` — TypeScript types for `SkillV2Info`, `SkillV2Source`, config schema\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fnode_modules\u002F@opencode-ai\u002Fplugin\u002Fdist\u002Fv2\u002Feffect\u002Fskill.d.ts` — Plugin skill hooks type definitions\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fskills\u002Fmaking-editing-skills\u002FSKILL.md` — Skill authoring conventions (user documentation)\n- `\u002Fhome\u002Fopencode\u002F.config\u002Fopencode\u002Fagents\u002Fagent.md` — Agent-level skill usage instructions\n",{"name":5,"description":7},"main","8f95d6b7cbf4ec39161b4e6c8bc5e1493e58003c","config\u002Fskills\u002Fskill-loading-system",0,"https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow","https:\u002F\u002Fgithub.com\u002Fxiaden","2026-09-30 22:33:49",{"source":8,"skillName":5,"commands":32,"prompt":42,"zipAvailable":43},[33,36,39],{"tool":34,"command":35},"npx","npx skills add xiaden\u002FSkyScow --skill skill-loading-system",{"tool":37,"command":38},"bunx","bunx skills add xiaden\u002FSkyScow --skill skill-loading-system",{"tool":40,"command":41},"pnpm","pnpm dlx skills add xiaden\u002FSkyScow --skill skill-loading-system","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Fskills\u002Fskill-loading-system\u002FSKILL.md",true,[],[46,52,59,65,72,79],{"skillNo":47,"name":48,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":19},"01M7CTNJ49PJ794TEFBCNYYKQM","unquoted-colon","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Ftools\u002Ftests\u002Ffixtures\u002Fskills\u002Funquoted-colon\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":19},"01M7CTNENFBZPEX63HNSRBCW4T","quoted-description","Use when a plain scalar contains a colon: like this one.","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Ftools\u002Ftests\u002Ffixtures\u002Fskills\u002Fquoted-description\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":19},"01M7CTNBBPKA6GMCVEM3GPB59F","block-description","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Ftools\u002Ftests\u002Ffixtures\u002Fskills\u002Fblock-description\u002FSKILL.md",[],[],{"skillNo":66,"name":67,"nameZh":6,"description":68,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":69,"categories":70,"keywords":71,"publishedAt":19},"01M7CTN4M0SR4Z4TPJMHWC3A3B","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\u002Fsupport owner selection. Use before choosing execution, investigation, design, or QA ownership; do not use to construct dispatch prompts, handoff schemas, or Change DAG\u002FDD tool operation.","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Fskills\u002Fwork-routing\u002FSKILL.md",[],[],{"skillNo":73,"name":74,"nameZh":6,"description":75,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":76,"categories":77,"keywords":78,"publishedAt":19},"01M7CTMY5AY3NSNHGQJA0M7VP9","update-docs","Update project documentation to match code changes — generate codemaps, refresh READMEs, detect doc\u002Fcode 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).","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Fskills\u002Fupdate-docs\u002FSKILL.md",[],[],{"skillNo":80,"name":81,"nameZh":6,"description":82,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M7CTMN61X0FYDFE5SMHH6974","security-review","Review code or agent\u002Ftool 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.","https:\u002F\u002Fgithub.com\u002Fxiaden\u002FSkyScow\u002Fblob\u002Fmain\u002Fconfig\u002Fskills\u002Fsecurity-review\u002FSKILL.md",[],[]]