OpenCode v2 安装配置方法 – 从零开始 / 以及agents.md
本配置方法将会让你，在一台全新的 Windows 上，从零装出 OpenCode v2 、包含两个有用的插件、三个比较必要的 MCP 服务器，以及”中文不乱码”的PowerShell终端。
- 命令默认在 PowerShell 下执行。
- 路径里的
ngc13需要换成你自己电脑的用户名。 - 文中密钥、密码均已脱敏，请勿照抄。
目录
目标环境快照
先对一下基线，差异通常不影响使用，但如果主版本不是 v2 就要注意了，如果遇见问题那么对照这些区别可能有助于排查错误。我建议使用最新版，除非你使用最新版遇见问题了，再试图切换到我的这个建议版本号：
| 项目 | 参考值 | 说明 |
|---|---|---|
| 操作系统 | Windows 11 专业版 10.0.26200（x64） | OpenCode 支持 win32 / linux / darwin，系统不同一般也能用 |
| OpenCode | 2.0.21 | npm 全局包 @opencode/cli |
| Node.js | v24.15.0 | 提供 node、npm、npx |
| npm | 12.0.1 | 全局目录 %APPDATA%\npm |
| uv / uvx | 0.10.9 | 供 fetch MCP 使用 |
| Git | 2.53.0.windows.1 | 可选，推荐（worktree、Git 插件等） |
| 终端代码页 | 65001（UTF-8） | 由自建 shell 包装器保证 |
Windows 上 OpenCode 不能用 winget / choco / scoop 安装，只能 npm 或独立二进制，本文用 npm。
想离线安装请不要参考本文，方案差别很大。建议把本文和你的系统环境丢给 AI，让它出一套离线部署方案即可。
文中的 dspark 是作者比较有钱，自费架设的两台 DGX（跑满血 DeepSeek V4 Vision Exp）的本地模型接入配置，普通用户跳过 dspark 相关段落即可。
第 1 步 · 安装 Node.js
winget install OpenJS.NodeJS.LTS # 或去 nodejs.org 下载 LTS 安装包
node -v # 能打印版本即成功
npm -vOpenCode 的 npm 包在安装时会用 Node 的 postinstall 脚本下载对应平台的原生二进制。
第 2 步 · 安装 OpenCode
npm install -g @opencode/cli
opencode --version # 应输出 2.0.21装完后 %APPDATA%\npm 下会出现 opencode / opencode2 两组入口（opencode、opencode.cmd、opencode.ps1…），它们指向同一个二进制。
日后维护：
opencode upgrade # 升级到最新版
opencode uninstall # 卸载并清理相关文件（慎用，会一并清数据）或者用npm升级也可以。
备选方案：下载官方独立二进制
opencode-windows-x64.zip解压后加入 PATH。本文不展开。
第 3 步 · 创建配置目录
启动一次OpenCode即可自动完成。
opencode所有全局配置都放这里。数据库、日志、状态、插件缓存会由 OpenCode 自动生成到别的目录，不用手动建。
稍后按照本文的流程动作后，配好后的目录大概长这样：
%USERPROFILE%\.config\opencode\
├── opencode.jsonc # 服务器配置：提供商 / 插件 / MCP / shell / skills
├── cli.json # 终端 TUI 配置：键位 / 通知 / 插件开关
├── AGENTS.md # 全局指令，每次对话自动注入
├── opencode-notifier.json # 通知插件配置
├── shell-utf8.cmd # 中文不乱码包装器（第 4 步创建）
├── shell-utf8-impl.ps1
├── service.json # 自动生成，含随机密码，勿泄露 / 勿提交
└── .gitignore # 可选：把本目录当独立仓库时忽略噪音第 4 步 · 做中文不乱码的 shell 包装器
Windows 默认代码页是 GBK，OpenCode 直接调 PowerShell 时中文容易乱码。办法是让 OpenCode 走一个包装器：先切到 UTF-8，再执行真正的命令。
新建 %USERPROFILE%\.config\opencode\shell-utf8.cmd：
REM %USERPROFILE%\.config\opencode\shell-utf8.cmd
@echo off
chcp 65001 > nul 2>&1
powershell.exe -NoProfile -ExecutionPolicy Bypass -File "%~dp0shell-utf8-impl.ps1" %*新建 %USERPROFILE%\.config\opencode\shell-utf8-impl.ps1：
# %USERPROFILE%\.config\opencode\shell-utf8-impl.ps1
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8
$OutputEncoding = [System.Text.Encoding]::UTF8
$argsList = $args
$cmdIdx = [array]::IndexOf($argsList, '-Command')
if ($cmdIdx -lt 0) { $cmdIdx = [array]::IndexOf($argsList, '-c') }
if ($cmdIdx -ge 0 -and $cmdIdx + 1 -lt $argsList.Count) {
Invoke-Expression $argsList[$cmdIdx + 1]
}下一步的 opencode.jsonc 会用 "shell" 指向这个 .cmd。
注意：包装器把 -Command 后的字符串交给 Invoke-Expression，所以这样之后，ai在OpenCode中的命令里就不能用 |、<、>、&、^（尤其引号内），否则会被解析坏。要串联命令用 ;。
请无论如何一定要在OpenCode运行的时候，有地方告诉ai这个事情。建议放到全局AGENTS.md中说明。后文的示例AGENTS.md会有描述样例。
第 5 步 · 写 opencode.jsonc
核心的服务器配置，路径 %USERPROFILE%\.config\opencode\opencode.jsonc：
{
"$schema": "https://opencode.ai/config.json",
"shell": "C:\\Users\\ngc13\\.config\\opencode\\shell-utf8.cmd",
"instructions": [
"AGENTS.md",
"CONTRIBUTING.md",
"docs/guidelines.md",
".agents/*.md",
".opencode/*.md",
".clinerules/*.md"
],
"skills": [
".agents/skills",
".opencode/skills",
".cline/skills",
".clinerules/skills"
],
"plugins": [
"oc-metricboard",
"@mohak34/opencode-notifier@latest"
],
"mcp": {
"servers": {
"fetch": {
"type": "local",
"command": [
"uvx",
"--with",
"mcp<2.0.0",
"mcp-server-fetch"
],
"timeout": {
"catalog": 120000,
"execution": 120000
}
},
"bing-search": {
"type": "local",
"command": [
"npx",
"-y",
"bing-cn-mcp"
],
"timeout": {
"catalog": 120000,
"execution": 120000
}
},
"playwright": {
"type": "local",
"command": [
"npx",
"-y",
"@playwright/mcp@0.0.79"
],
"timeout": {
"catalog": 180000,
"execution": 180000
}
}
}
}
}逐块说明：
shell—— 指向第 4 步的包装器，解决中文乱码。instructions—— V2 目前不解析它 ，真正生效的是同目录的AGENTS.md。保留只是兼容多智能体插件（.agents/.opencode/.clinerules）的通行约定。skills—— 让 OpenCode 到这些目录里找技能文件，V2 有效字段。plugins—— 服务器端插件，缺包会自动下载安装（见第 9 步）。mcp.servers—— 三个本地 MCP 服务器（见第 9 步）。
如果你想使用自定义或者本地的接口，参考这个DGX spark上面部署的vllm驱动的deepseek v4 flash vision exp的接入例子，添加到配置中：
{
"$schema": "https://opencode.ai/config.json",
"providers": {
"dspark": {
"name": "DGX DeepSeek",
"package": "@opencode/ai/providers/openai-compatible",
"settings": {
"baseURL": "http://192.168.50.1:80/v1",
"apiKey": "local-no-auth",
"timeout": false,
"headerTimeout": false,
"chunkTimeout": 3600000
},
"models": {
"deepseek-v4-flash-vision-exp": {
"name": "DeepSeek V4 Flash Vision Exp",
"capabilities": {
"tools": true,
"input": [
"text",
"image"
],
"output": [
"text"
]
},
"limit": {
"context": 1048576,
"output": 384000
}
}
}
}
}
}providers.dspark—— 自定义 OpenAI 兼容提供商，指向内网 DGXhttp://192.168.50.1:80/v1，本地无鉴权（apiKey: local-no-auth）。三个超时设为false/ 1 小时，是为了本地大模型长时间生成不被掐断；模型声明了工具调用与图文输入能力，上下文 1M、输出 384K。 没有 DGX 就整段删掉。
第 6 步 · 写 cli.json
终端 TUI 专属配置，路径 %USERPROFILE%\.config\opencode\cli.json：
{
"$schema": "https://opencode.ai/v2/cli.json",
"keybinds": {
"app.toggle.paste_summary": "ctrl+o"
},
"session": {
"verbosity": "high"
},
"attention": {
"notifications": false,
"sound": false
},
"plugins": [
"oc-metricboard",
"-opencode.notifications"
]
}keybinds.app.toggle.paste_summary: "ctrl+o"—— 给”切换粘贴摘要”绑个键（该命令默认没绑）不然有时候粘贴个长内容自动折叠了，都没法展开。（注意，在vsc的终端内，可能和vsc自己的快捷键冲突，请在vsc的快捷键内配置当焦点在终端时，ctrl+o默认输入到终端，而非vsc快捷键）session.verbosity: "high"—— 会话显示更详细（自动展开一些调用的详情）。attention.notifications/attention.sound: false—— 关掉 TUI 内置 的通知和提示音。（我们会使用插件添加一个更好的全局系统通知（基于托盘通知toast））plugins——oc-metricboard开侧边栏指标板；-opencode.notifications提供toast支持的声音+系统通知。
cli.json和opencode.jsonc都能在 TUI 里按Ctrl+P→ Open settings 改；写错的字段会被拒绝。
第 7 步 · 写通知插件配置
路径 %USERPROFILE%\.config\opencode\opencode-notifier.json：
{
"sound": false,
"notification": true,
"bell": false,
"suppressWhenFocused": false,
"events": {
"permission": { "sound": false, "notification": true },
"complete": { "sound": false, "notification": true },
"subagent_complete": { "sound": false, "notification": false },
"error": { "sound": false, "notification": true },
"question": { "sound": false, "notification": true },
"interrupted": { "sound": false, "notification": true },
"user_cancelled": { "sound": false, "notification": true },
"plan_exit": { "sound": false, "notification": true },
"session_started": { "sound": false, "notification": false },
"user_message": { "sound": false, "notification": false },
"client_connected": { "sound": false, "notification": false }
}
}这个配置只弹系统通知，不发声、不响铃；只对”要授权、完成、出错、提问、被中断、取消、计划就绪”弹通知，其余噪音事件静默。suppressWhenFocused: false 表示终端在前台也弹。
第 8 步 · 写 AGENTS.md
路径 %USERPROFILE%\.config\opencode\AGENTS.md。OpenCode 会先加载全局 AGENTS.md，再按”当前工作目录 → 家目录”的顺序叠加各级 AGENTS.md；
完整内容较长，直接复制文末附录 · AGENTS.md 全文即可。
第 9 步 · 装插件与 MCP 依赖
插件不用手动装——写进配置后，OpenCode 启动时会自动下载到 %USERPROFILE%\.cache\opencode\npm\。需要手动装的是 MCP 的运行依赖：
winget install --id=astral-sh.uv # fetch MCP 需要 uvx
uv --version
npx playwright install chromium # playwright MCP 需要浏览器（也可首次运行时自动下载）为什么：三个 MCP 里 fetch 是 Python 的（用 uvx 启动），bing-search、playwright 是 Node 的（用 npx 启动）。首次启动时 npx / uvx 会去下包，配置里把 catalog / execution 超时提到 120~180s 就是防这个。
启动后可用 /mcps 查看连接状态，命令行：
opencode mcp list注意：playwright可能使用npx直接装会报错，原因未知，如果你遇见报错，就让OpenCode的ai帮你看看，看看能弄好不。我记得我最后的方案是用指定的旧版本就好了。似乎是一个已知的依赖问题，不好直接解决，用旧版比较稳定而且没啥坏处。
第 10 步 · 启动并连接模型
opencode进入 TUI 后：
/connect # 选 DeepSeek，粘贴 API Key
/models # 选 deepseek/deepseek-flash为什么：deepseek 是 OpenCode 内置目录（models.dev）自带的提供商，API 端点 https://api.deepseek.com，环境变量名 DEEPSEEK_API_KEY。凭据会加密存进 opencode.db，不落在配置文件里。
选中的模型与推理变体会记在 %USERPROFILE%\.local\state\opencode\model.json。想固定默认模型，也可以在 opencode.jsonc 里加一行 "model": "deepseek/deepseek-flash"。
作者本机可选的模型：
deepseek/deepseek-flash # 当前在用，推理变体 high
deepseek/deepseek-v4-pro
dspark/deepseek-v4-flash-vision-exp # 内网 DGX
opencode/* # 内置免费模型第 11 步 · 一次性验证
opencode --version
opencode auth list # 应显示 DeepSeek ... stored
opencode models # 能看到 deepseek / dspark / opencode 模型
opencode plugin list # oc-metricboard 0.1.19、opencode-notifier 0.6.0
opencode mcp list # fetch / bing-search / playwright
opencode service status # 返回 http://127.0.0.1:<端口>
opencode api get /api/info以后常用命令
opencode # 启动
opencode --standalone # 用私有服务启动（排查共享服务问题时用）
opencode service restart # 重启后台服务
opencode pair # 打印浏览器 / App 的连接链接、用户名、密码
opencode upgrade # 升级
opencode uninstall # 卸载并清理常见坑
- 中文乱码 → 没配
shell-utf8，或opencode.jsonc的shell没指对。 - 通知重复弹 → 内置通知没关干净：
attention.*和-opencode.notifications都要关。 instructions不生效 → V2 不解析它，指令请写进AGENTS.md。- MCP 连不上 → 多半是
npx/uvx首次下载超时，等一会儿或把超时调大。 - 凭据存在哪 → 在
opencode.db里（不是auth.json），用opencode auth list查看。 - 别手改数据库 / 服务文件 → 排障先备份，再用
opencode service系列命令操作。
复刻对照清单
- 装 Node.js LTS（本机 v24.15.0）
npm install -g @opencode/cli→ 2.0.21- 建
%USERPROFILE%\.config\opencode\ - 放
shell-utf8.cmd+shell-utf8-impl.ps1 - 写
opencode.jsonc（shell / dspark / skills / plugins / 三个 MCP） - 写
cli.json - 写
opencode-notifier.json - 写
AGENTS.md - 装 uv、Playwright 浏览器
/connect连 DeepSeek，/models选 deepseek-flash（变体 high）- （可选）装 git
- 跑一遍第 11 步的验证命令
附录 · AGENTS.md 全文
%USERPROFILE%\.config\opencode\AGENTS.md 完整内容，原样复制即可：
# 全局规则
## 规则说明
1. 此处的规则必须得到注意！
2. 该规则相较于任何其他规则rules, 或技能skill优先级都更低. 如果冲突，优先遵循项目规则，如果项目规则没提到的，再遵守此处的规则。用户要求是最高优先级，其次是项目目录的规则，最后是这里的。（也就是遇见冲突的提示时，先遵守其他规则）
3. 做长期正确的事。
## 计划与执行说明
1. 尽可能优先在plan时，将任务拆分的非常细致，保证每一次更改只针对一个需求或者在相似的源代码区域，尽量避免一次修改海量代码。
2. 请保持代码风格或行文文风的一致性。
3. 如果需要读取一个文件，那么最好一次读取整个文件，而不是按行一次次的读取文件的某个范围，除非用户手工指定读取的范围行数。
4. 如果项目代码已经存在，那么上下文代码是什么语言就用什么语言。上下文注释是什么语言就用什么语言。请注意一些情况下程序语言和注释语言可能不同。
5. 如无特别说明，从零开始写代码的时候，默认情况下注释和用户交互应该使用中文
6. 功能出现更改或添加的时候，请记得更新readme（如果存在）
7. 计划阶段如果发现了比较严重的问题，以致于修复该问题和完成要求的任务的工作量几乎一个数量级的，应提醒用户现在应该本轮次不添加新功能，先重点修复这个问题，之后再重开会话，继续新增功能的实现。
8. 如果plan模式下，由于只读导致分析计划受阻，可以请求用户临时切换到build模式。（但是仍然是优先计划任务，临时切换到build只是为了查看或者证实一些内容的手段更方便）
## 工具说明
1. 请正确的使用给您提供的tools，mcp服务器。
2. 除非工具无法实现，否则不要使用终端执行命令来查看或修改。必须优先使用内置tools或mcp服务器来实现相关的更改。如果遇见错误，请检查是否正确使用了工具，只有明确无法使用工具处理的情况，或用户明确指定使用命令行终端执行的，才使用终端。
3. 系统是PowerShell，请注意使用正确的命令语法。尤其是应使用`;`替代`&&`来连接命令。
4. PowerShell经过一次包装器保证中文不乱码，但是这会带来副作用。因此，命令里别在引号内使用 |（以及 < > & ^），搜索尽量用 glob/grep 工具。
5. 调用playwright_screenshot时，始终将downloadsDir参数设置为 `E:\LLM\playwright_data\cache`
6. 调用playwright时，除非明确指定，否则不要使用无头模式。
7. 如果用户指定下载路径，那么使用playwright时请手工将文件存储到用户指定的位置。
8. 如果你尝试读取查看，或者写入修改当前项目目录以外的文件或者路径（比如用户目录的配置文件或者程序的包之类的），一定会触发用户权限批准请求。因此你在尝试调用之前，需要给出一些必要性说明和目的描述，用户看见了才好给你批准，以防止未授权的意外操作。请勿在不事先提供任何说明的情况下直接尝试读取或者写入项目目录以外的任何文件，否则用户无法确认目的，不会批准请求。
## 子任务
1. 如有必要，请使用 subagent 来处理重复、乏味且海量的任务，例如校对，或者逐段落翻译。
2. 使用 subagent 的时候，请注意不要一次启动超过3个subagent以防子任务过多导致系统卡死。
3. 不要乱用subagent，尽量自己亲自看完所有内容，而非拉几个子助理阅读总结。除非翻译之类的明显可以并行执行的任务。
## 开发原则
1. 长期主义，面向维护，新增改动应降低未来开发成本，禁止引入技术债
2. 警惕可能产生架构分叉的编码，按最佳实践来做统一的结构
3. 单一真相源（SSOT），写入口唯一，其他皆派生、复用
4. 结构性问题用重构解决，禁止补丁、特例绕过
5. 遵循可执行最佳、现代的实践
6. 除非额外强调说明，否则积极引入成熟第三方库解决问题，而不是自己造轮子
7. 优先阅读代码而非写代码，优先寻找项目内可用可扩展的代码。如果项目有自己的自述文档，结构说明文档，可以参阅他们。如果通过文档即可明确，则无需阅读大量代码。阅读代码时，多使用grep或者filter过滤器等操作以降低读入的内容长度，同时不遗漏。
8. 迭代修改而非增量修改，重写/重构后删旧代码，不要留着。
9. 遵循KISS原则，选最短且长期最佳实现路径，架构导致冗余就简化架构
10. 做合适程度的强类型，相同的类型也单一类型定义源
11. 禁止做掩耳盗铃的事情，我们必须真实的做事
12. 不需计算编码成本，AI编码不是人工，永远选择最佳的方案
13. 做深度封装的组件，将复杂度封装在组件内，只暴露很少的必要的生命周期和API，要替调用方着想
14. 少做短期主义的hack和补丁
15. 精准手术刀式的修正，不做过度兜底
16. 通常采用 TDD，先编写测试，再实现功能，保证模块可进行有效单元测试，单元测试要涉及到下一层依赖，更深层的才可以mock。
17. 一个组件做好一件事，函数的过程别写太复杂，类别弄的太繁重（否则请使用组合/继承），单个源代码别太长，否则考虑功能拆开成多个高内聚低耦合的源代码。
18. 修复 Bug 时禁止过度兜底，要定位根因，并用正确的逻辑解决问题。
19. 不编写只有单一调用、没有复用或抽象价值的私有 Helper 函数。如果正好发现这类问题，请在当前功能结束后，提示用户修复这些功能，而不是在本轮次就尝试修复。
20. 代码和文档中，通常无需包含修改说明（包括这条也不要出现）。
## 自动测试
对于稍微复杂一些的，组件化或者系统化的东西，最好用自动测试来验证功能实现的是正确的。特别简单的修改就无需自动测试了。
1. 实现测试的时候，将测试代码写入一个新的测试脚本文件，然后执行它，而不是直接在终端执行大量的测试代码，除非测试代码很少（比如就两三行或者是一个指令而已）。
2. 所有单元测试等测试代码请保留好，不要用完删除。您应该首先查看当前仓库是否有专门放置单元测试代码的文件夹。
3. 自动测试请按需实现，如果针对简单的代码，或者用户没有明确请求，其实可以不用实现自动测试.
4. 自动测试最好给样例提供注释（因为我们有自动生成文档的代码可以自动生成测试报告，需要用到这些注释）。
## 文档规范
文档要保持索引和信息职责和单一信息，不能复述已经存在的逻辑，比如已有的代码逻辑，应该是指向相关的代码，而不是用文字将代码逻辑复述一遍，避免形成分叉，避免浪费上下文。文档保持精简。
对于可以独立运行或者明显构成模块的部分，他们如果都是遵循开发规范的，那么肯定都是模块化，组件化的代码。一般将每个程序或者子组件的文档放在各自文件夹底下的readme.md即可。除非额外要求。
1. 章节之间一般无需添加分割线。
2. 章节一般不需要手工编号序号。
最开始合适的位置（一般是摘要之后）需要添加自动目录：
```markdown
段落后空行，然后有以下标记会自动渲染形成目录：
[TOC]
上面这个就是自动目录，很简单，因此无需手写目录。
```
一个好的文档大纲可以参考如下参考大纲：
```markdown
# 标题
一句话介绍或者摘要段落（不需要），描述清楚这个东西解决的现实问题，关键科学技术工程问题，用的什么方法，实现的成果，效用和价值等。
## 快速开始
一个最小测试样例，演示程序如何立刻开始使用
## 详细说明
...
## 系统架构说明
.. 可以用mermaid图之类的方式辅助说明。图注用引用即可。
## 算法说明
.. 如果牵扯算法之类的
## 开发说明
包括环境配置，开发和贡献规则，注意事项，易坑说明，关键细节说明，计划完成的任务，ai开发准则，自动测试实现准则，部署交付准则等，可以分章节如果内容多
## 作者信息
wyb 日期 协议（没有说明则默认无协议，直接不写）
```
## 自进化原则
你在执行的过程中，可能会发现一些因为经验缺乏而犯错的地方，然后你很快就修正并且后续稳定处理。然而，下一次重新开始干活的时候，由于缺失上下文，这种坑仍然会踩第二遍。
因此，作为ai agent，你有义务更新这些类似于应该作为长期记忆的信息到持久化提示词中。也就是每个工程合适的位置下面放置的Markdown文件中。这些Markdown实际上是一种rules.md或者skill.md的存在，每次启动对话和任务，都会默认送入新的ai，因此将重要信息写入这个文件，能让你具备长期记忆，避免由于经验问题的持续犯错。
注意：对于项目的特定经验，有些只是笔记一类的东西，针对特定组件的特定区域描述的，最好通过注释记录到代码中。项目代码库通用的经验最好记录一些通用的规则，比如使用什么环境，注意编译方式之类的，而非大量的细节。
注意：自进化撰写的文档无需遵循上文中的推荐大纲。这个属于ai自己的笔记性质，不是给人类看的文档。
请将那些重要的经验，追加写入到项目根目录下的合适的位置下面放置的Markdown文件中，以提升自己的项目工作经验，在日后更好的完成事项，避免重复性的犯错。
什么是合适的位置？对于全局经验，建议放到每次都会被ai agent自动送入模型上下文的那些路径，也就是全局位置，他们将类似于rules.md的存在。而针对特定开发内容的经验，则适合放入按需提供给ai上下文的路径下，也就是类似于skills.md的存在。
### 适用于整体的项目经验
将整个项目的通用经验记录在类似于rules.md的位置下。优先查看项目目录的以下路径，这是兼容opencode和多种agent插件的常见位置，从第一个往后依次检查并优先写入，如果都不存在则使用第一个:
```text
.agents/*.md
.opencode/*.md
.clinerules/*.md
```
写入的内容就是正常的Markdown文档即可。
### 适用于特定情况的项目经验
如果一些经验不是针对项目全局的，而是项目中特定的算法或者功能组件的，那么建议将其记录为skills.md的存在。优先查看项目目录的以下路径，这是兼容opencode和多种agent插件的常见位置，从第一个往后依次检查并优先写入，如果都不存在则使用第一个:
```text
.agents/skills/*.md
.opencode/skills/*.md
.cline/skills/*.md
.clinerules/skills/*.md
```
对于skills.md，写入的内容相较于普通Markdown文档，还需要多一个元数据，也就是每个文档开头需要 YAML frontmatter，至少写清 name 和 description，类似于：
```markdown
---
name: 该技能或者经验的标题
description: 一句话说清楚这个 skill 什么时候该被用，ai将看到这个摘要并靠它做选择，是否查看整个文档
---
# 具体指令正文……
```
作为skills.md的这部分内容仅在必要时被送入ai，由ai决定是否查看全文。NGC13009 2026-10-01
本文依据本机
C:\Users\ngc13\.config\opencode现有配置、OpenCode V2 官方文档（https://opencode.ai/v2/docs/）以及实际调查整理；