OpenCode完整入门指南：从安装到Skill配置，建立AI编程工作流

OpenCode 的价值不仅在于把模型搬进终端，更在于让它围绕当前项目读取资料、理解代码并执行工作。新手应先建立一个能验收的小任务，再把反复使用的方法写成 Skill，这样技能内容才有实际依据。

第一步：选择一种安装方式

在 macOS、Linux 或 WSL 的 Bash 环境中，可以使用官方安装脚本；已经使用 npm 的环境也可以选择对应软件包。两种方式选一种即可。

# Bash 环境安装
curl -fsSL https://opencode.ai/install | bash

# 或者使用已配置好的 npm
npm install -g opencode-ai

安装后在新终端执行 opencode --version，再进入目标项目启动 opencode。若找不到命令，先检查安装输出和程序所在目录是否在 PATH 中，不要反复叠加安装。

第二步：连接提供商并选择模型

1. 在交互界面执行 /connect，选择你实际使用的服务。
2. 按该服务的方式登录或提供 API Key。
3. 使用 /models 选择有权限访问的模型。
4. 先做一次简短问答，再让它读取一个已知文件。

提供商、模型和技能属于不同层次。换模型可能改变推理和工具能力；增加 Skill 则提供任务方法，并不会自动开通某个服务或赋予模型新的基础能力。

初始化项目知识

在项目根目录使用 /init 可以帮助建立项目说明。生成后应自己检查构建命令、目录结构和约定，删去错误推断。项目说明应该写稳定事实，不要记录一次性故障和个人密钥。

第三步：创建第一个 Skill

例如你经常需要在修改后整理验收结果，可以创建 .opencode/skills/change-review/SKILL.md。目录名和 name 应一致，使用小写字母与连字符。

---
name: change-review
description: 在代码修改完成后检查差异，整理测试结果与尚未验证的事项。
---

## 工作步骤
1. 阅读本次修改的文件和差异。
2. 根据项目说明确认相关检查命令。
3. 执行与改动直接相关的检查。
4. 区分已通过、失败和未执行的检查。
5. 输出修改原因、验证证据和剩余问题。

## 交付要求
- 不把未运行的测试写成通过。
- 不把已有改动误称为本次新增。
- 不自动提交或发布。

这是一个原创的简单技能示例，适合先验证发现与调用流程。Skill 的描述要说明“什么时候该用”，正文则说明“具体怎么做”。仅写“你是一位专家”很难带来稳定的工作方法。

第四步：验证技能真的生效

在新会话明确要求使用 change-review，给它一个小改动。检查它是否发现并加载技能，以及输出是否包含实际运行的检查结果。不能只看回答语气像不像技能要求。

技能没有被发现时

• 检查文件是否确实叫 SKILL.md，以及目录层级是否正确。
• 核对 YAML 开头的 name 与 description 是否存在。
• 确认启动目录属于预期项目，必要时重开会话。
• 检查技能权限和同名定义，避免多个位置的内容造成混淆。

项目技能与个人技能怎么选

项目规则放在仓库内，便于团队审查和同步；只适合自己的偏好，可放在 ~/.config/opencode/skills/。共享技能要避免依赖个人绝对路径，否则换一台电脑就无法执行。

从一次成功走向稳定使用

用一个真实的小缺陷跑完整流程：说明问题、要求分析、检查方案、执行修改、验证行为、回顾差异。重复出现的步骤再整理进 Skill。随着项目变化定期更新技能，保持它简短、具体，并能通过实际任务证明有用。