OpenCode+Antigravity Skills：打造团队级AI结对编程技能库

把 OpenCode 真正接进团队日常开发，我前后折腾了两周。最开始它和每个人终端里的 AI 编程助手没什么两样——能聊天、能改代码、能跑命令，但问题也一模一样：各用各的，规则全靠个人口头约定。直到我把 Antigravity Skills 这套技能包规范引进来，OpenCode 才真正从“我的工具”变成了“团队的 AI 结对编程伙伴”。同一套代码规范、同一份审查清单、同一种提交约定，不管团队里谁打开终端，AI 给它喂的行为规则都是一致的。这篇文章是完整的落地记录，适合已经能把 OpenCode 当个人助手用、但想让它在多人协作里稳定发挥的团队参考。

1. 为什么 OpenCode 需要一套“团队技能库”

很多团队引入 AI 结对编程工具后，第一个体感是“这东西确实能写代码，但总差点意思”。不是模型不够强，而是模型每次都在猜你的规则。你让它写一个接口，它可能用 RESTful 风格，也可能用 RPC 风格；你让它提交代码，它可能写 update xxx，也可能老老实实写 feat: add xxx。在个人项目里这些差异无所谓，但放进团队代码库，就是灾难。

1.1 个人用与团队用的本质差异

个人用 OpenCode，本质是“一个更聪明的补全工具”。你把需求说清楚，模型把代码写出来，你看一眼，改一改，完事。规则只存在于你的脑子里，最多写进几次对话的 prompt 里。

团队用就完全不同了。团队里有新人，有跨模块协作，有 Code Review，有统一的提交规范和分支策略。这时候 AI 的行为必须是可预期的。A 成员让 OpenCode 生成的代码，和 B 成员让 OpenCode 生成的代码，应该遵循同一套代码风格、命名规范、目录约束、异常处理方式。如果做不到，AI 结对编程不但没提高效率，反而让 Review 的人更累——因为要额外判断“这段代码是不是 AI 写的、符不符合规范”。

一两个人靠记忆和口头沟通还能撑住，五个人以上就崩。这也是为什么很多团队发现 AGENTS.md 不够用：它只是个纯文本约定文件，模型每次都要把全部内容塞进上下文，既占 token，又没法附带可执行的校验脚本。

1.2 Antigravity Skills 在其中的位置

Antigravity Skills 解决的不是“让模型更强”，而是“让模型按团队规则工作”。你可以把它理解成一套技能包规范：每个技能包是一个独立目录，里面有一个 SKILL.md 入口文件，加上若干脚本、模板、参考文档。模型在对话中根据用户意图自动匹配并加载对应的技能包，按里面的指令、步骤、脚本去执行。

这个思路很像给同一个实习生发不同岗位的手册。模型还是那个模型，但手上拿的规则不一样，输出的东西就不一样。对团队来说，这比把规则揉进每一条 prompt 里要靠谱得多——规则可以版本化、可以评审、可以分发，新人来了拉一份技能库就能上手。

而且这套规范是开放的，不绑定某个特定 IDE。OpenCode 作为终端型编码代理，天然适合做这件事：它本身就是一个可以加载技能、执行脚本、接入多模型的“AI 工作台”。

2. OpenCode 本体安装：从裸终端到跑通第一个对话

想玩团队级配置，先把 OpenCode 本体装明白。这里不废话，直接把安装链路和最容易出问题的 Windows 环境讲清楚。

2.1 安装与第一个报错

OpenCode 的主流安装方式有两种，任选其一。

bash复制# 方式一：使用 npm 全局安装
npm install -g opencode-ai

# 方式二：使用官方安装脚本（macOS / Linux）
curl -fsSL https://opencode.ai/install | bash

装完先验证版本：

bash复制opencode --version

如果你在 Windows PowerShell 里执行 opencode，大概率会碰到这个经典报错：

text复制opencode : 无法将“opencode”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。
请检查名称的拼写，如果包括路径，请验证路径是否正确，然后再试一次。

这道题有两个考点。第一，npm 全局安装目录有没有进 PATH；第二，PowerShell 的执行策略有没有拦住 .cmd / .ps1 脚本。排查顺序如下：

1. 先看 npm 全局目录：npm prefix -g，通常在 C:\Users\你的用户名\AppData\Roaming\npm。
2. 检查环境变量 PATH 里有没有这个目录。没有就手动加进去，然后重开终端。
3. 如果加完还是不行，执行：Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser，允许本地脚本运行。
4. 如果是用 nvm-windows 装的 Node，注意 npm prefix -g 可能指向 nvm 的当前版本目录，切换 Node 版本后全局命令会消失，需要重新安装或者把公共目录加进 PATH。

2.2 模型接入与最小配置

OpenCode 本身不内置模型，需要接入各家大模型的 API。首次运行可以用交互式登录：

bash复制opencode auth login

它会列出支持的 Provider，包括 Anthropic、OpenAI、Google、OpenCode 自己的托管服务等。选择后按提示粘贴 API Key 即可。

但团队场景下，我更推荐直接写配置文件，方便统一管理。默认配置文件路径：

• macOS / Linux：~/.config/opencode/opencode.json
• Windows：%USERPROFILE%\.config\opencode\opencode.json

最小配置示例：

json复制{
  "model": "anthropic/claude-sonnet-4-5",
  "provider": {
    "anthropic": {
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    }
  }
}

apiKeyEnv 表示从环境变量读取密钥，而不是硬编码在配置文件里——这个习惯很重要，团队共享配置时谁都不想把自己的 Key 暴露出去。多模型场景下还可以配多个 provider，用 opencode 命令内切换。

2.3 第一次结对对话

完成配置后，在项目根目录运行：

bash复制opencode

进入交互式 TUI，你就可以直接提需求。举个例子，你可以输入：“分析一下这个仓库的模块划分，指出循环依赖”，OpenCode 会读取代码结构、生成回答。

不想进交互界面时，也能直接用非交互模式：

bash复制opencode run "给 UserService 写单元测试"

团队里的自动化脚本、CI 流程都非常依赖这种非交互调用方式，后面章节会用到。到这里，OpenCode 已经能在你个人电脑上稳定工作了，下一步才是重头戏——装技能。

3. Antigravity Skills 到底定义了什么：拆开一个技能包看内部结构

很多人第一次接触 Skills 时觉得玄乎，其实拆开看就是一个带约定的目录结构。先记住一个事实：Skill 的本质是“写给模型看的可执行说明书”。

3.1 SKILL.md：技能包的入口文件

每个技能包的核心是 SKILL.md，头部有一段 YAML frontmatter，后面是 Markdown 正文。下面是一个简化示例：

markdown复制---
name: team-commit-convention
description: 按团队提交规范校验 git commit message。当用户准备提交代码、生成 commit message、写 PR 描述或生成 changelog 时使用本技能。
---

# 团队提交规范

严格遵循 Conventional Commits 标准检查提交信息：

1. type 必须是 feat / fix / docs / refactor / perf / test / chore / revert 之一
2. scope 必须来自项目 docs/scopes.txt 中登记的模块名
3. 主题行不超过 72 字符
4. 破坏性变更必须在 message 中标注 BREAKING CHANGE

执行步骤：

1. 先读取项目根目录 docs/scopes.txt，加载合法 scope 列表
2. 用 scripts/check-commit.mjs 逐行校验提交信息
3. 校验失败时，返回脚本输出，并给出修正建议

关键在 description。模型不是靠文件名识别技能的，而是靠 description 里的语义描述去匹配用户意图。用户说“帮我写个提交信息”，模型读到 description 里“生成 commit message 时使用本技能”，就会加载这个技能包。所以 description 写得好不好，直接决定技能触发率——这点后面避坑章节会重点展开。

3.2 一个完整技能包的目录拆解

实际团队里，一个技能包通常长这样：

text复制~/.config/antigravity/skills/
├── commit-convention/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── check-commit.mjs
│   └── references/
│       └── conventional-commits.md
├── code-review/
│   ├── SKILL.md
│   ├── scripts/
│   │   └── review.py
│   └── checklist.md
├── api-design/
│   ├── SKILL.md
│   └── templates/
│       └── rest-api-handler.md
└── onboarding-java/
    ├── SKILL.md
    └── references/
        └── project-conventions.md

• scripts/ 放可执行脚本，模型可以调用它们做校验、生成、分析。
• references/ 放参考文档，模型在需要时按需读取，避免一次性全塞进上下文。
• templates/ 放代码模板，模型照着模板生成业务代码，保证风格统一。

这种结构与“把一大段规则写进 AGENTS.md”最大的区别是：规则是结构化的，资源是懒加载的，校验是可执行的。模型不需要在每次对话时把全部技能内容读一遍，它只在匹配到对应场景时才加载，省 token，也减少规则之间的互相干扰。

3.3 触发机制与加载方式

OpenCode 加载技能的方式有两种。第一种是全局技能目录，适合放团队通用规范；第二种是项目内技能目录，适合放项目专属约定，通常放在 .antigravity/skills 下，随 Git 仓库走。

要让 OpenCode 识别技能目录，在 opencode.json 里声明：

json复制{
  "skillDirs": [
    "~/.config/antigravity/skills",
    ".antigravity/skills"
  ]
}

配置好后，每次对话时 OpenCode 会扫描这些目录下的 SKILL.md，把技能名称和描述作为“可选能力清单”提供给你选的模型。模型判断用户请求与某个技能描述匹配时，才会真正读取该技能包的完整内容并执行。

这个机制意味着：技能不会抢占上下文，也不会在没有必要的时候干扰模型行为。它更像“按需查阅的操作手册”，而不是每次开工前都要读一遍的冗长说明。

4. 把团队规范“技能化”：从 AGENTS.md 到可复用 Skill 的实操路径

AGENTS.md 真的没用了吗？不是。它适合放“全仓库一次性加载的全局约定”，比如项目结构、常用命令、构建方式。但技能化的规范适合放“按场景触发、可能需要执行脚本”的规则。两者是互补关系，不是替代关系。

4.1 六步落地法

把团队规范技能化，我建议不要一上来就写一堆技能，按下面六步走，稳一点。

第一步：盘点团队高频问题。 看看过去一个月的 Code Review 记录，最多重复出现的是哪几类意见。大概率是这几类：提交信息不规范、异常处理缺失、空指针没判空、新代码没写测试、接口没做参数校验。这些就是技能的种子。

第二步：把规则固化成文字。 挑一个问题，写清楚“什么时候用、要检查什么、不满足算什么级别的问题、怎么修”。这是给模型看的，所以每条规则都要无歧义。比如“异常处理缺失”要写得更具体：“进入方法后，所有可能抛出 RuntimeException 的外部调用必须用 try-catch 包裹，自定义异常必须包含 errorCode 和 message”。

第三步：做最小验证。 先写一个技能包的 SKILL.md，不放脚本，只放规则。然后在某个仓库里跑一次对话，看模型会不会按规则执行。不会就调 description。

第四步：把关键校验脚本化。 规则里凡是可以程序化判断的，都写成脚本。比如提交信息检查，用正则就能搞定，没必要让模型自己“阅读理解”。让模型执行脚本，而不是让模型背诵规则——这是技能化最核心的一点。

第五步：放进团队仓库并审查。 技能包要像代码一样走 Code Review。写技能的人容易把话说得太满，Review 的人要判断“这个规则对所有成员都合理吗”。

第六步：迭代。 每两周看一次技能使用情况，把新增的高频意见继续沉淀成技能，把不触发的技能优化描述。

4.2 一个可运行的校验脚本

以提交信息校验为例，脚本可以直接用 Node.js 写，不依赖额外依赖：

javascript复制#!/usr/bin/env node
// scripts/check-commit.mjs

import fs from 'node:fs';
import path from 'node:path';

const types = ['feat', 'fix', 'docs', 'refactor', 'perf', 'test', 'chore', 'revert'];
const message = process.argv[2] || '';

if (!message) {
  console.error('缺少提交信息参数');
  process.exit(1);
}

const match = /^(\w+)(\(([\w-]+)\))?: (.+)$/.exec(message);
if (!match) {
  console.error('提交信息格式错误，应符合 Conventional Commits：type(scope): subject');
  process.exit(1);
}

const type = match[1];
const scope = match[3] || '';
const subject = match[4];

if (!types.includes(type)) {
  console.error(`type 必须是：${types.join(' / ')}，当前是：${type}`);
  process.exit(1);
}

const scopesFile = path.join(process.cwd(), 'docs', 'scopes.txt');
if (fs.existsSync(scopesFile)) {
  const allowedScopes = fs.readFileSync(scopesFile, 'utf-8')
    .split('\n').map(s => s.trim()).filter(Boolean);
  if (scope && !allowedScopes.includes(scope)) {
    console.error(`scope "${scope}" 不在 docs/scopes.txt 登记范围内`);
    process.exit(1);
  }
}

if (subject.length > 72) {
  console.error(`主题行超过 72 字符，当前 ${subject.length} 字符`);
  process.exit(1);
}

console.log('提交信息校验通过');

然后在 SKILL.md 里写明执行步骤，模型就知道先读 scopes.txt，再调用脚本校验，最后给出修正建议。这就是一个标准的团队技能包。

5. 让每个结对伙伴都加载同一套能力：团队共享与同步机制

个人技能包折腾得再漂亮，如果只躺在自己电脑上，就没什么团队价值。真正要把 OpenCode 变成“团队级结对编程伙伴”，必须解决分发和同步问题。

5.1 技能仓库是团队资产

我建议把团队技能库单独拉一个 Git 仓库，不要和业务代码混在一起。结构如下：

text复制ai-team/skills/
├── README.md
├── commit-convention/
├── code-review/
├── api-design/
├── test-strategy/
└── onboarding-java/

每个成员在本地把技能目录软链到 OpenCode 的全局技能目录：

bash复制ln -s ~/work/ai-team/skills ~/.config/antigravity/skills

Windows 上用目录联接：

powershell复制cmd /c mklink /J "%USERPROFILE%\.config\antigravity\skills" "D:\work\ai-team\skills"

这样技能包的更新不需要成员重新配置，只要 git pull 到位，OpenCode 下次对话自动扫描到最新技能。

5.2 同步脚本与自动更新

很多人会忘记 pull 技能库，导致本地技能过期。可以写一个简单的同步脚本，挂到终端启动或者提交命令的 hook 里：

bash复制#!/usr/bin/env bash
# sync-skills.sh
SKILL_REPO="$HOME/work/ai-team/skills"
SKILL_LINK="$HOME/.config/antigravity/skills"

if [ -L "$SKILL_LINK" ]; then
  echo "技能库已软链，执行 git pull..."
  git -C "$SKILL_REPO" pull --ff-only
else
  echo "技能库未软链，请先执行 ln -s 命令创建软链"
  exit 1
fi

如果团队用 zsh，在 .zshrc 里加一行 sh ~/work/ai-team/skills/sync-skills.sh，每次开终端自动同步。这个方案简单粗暴，但对大多数团队已经够用。

5.3 权限、审查与版本管理

技能仓库的权限要和代码仓库一样严格。这里有两个容易踩的坑：

第一个是技能仓库的 Review 流程不能省。 任何人改了 SKILL.md，必须有至少一个人 Review。因为技能规则直接影响 AI 在所有成员电脑上的输出行为，一条不合理的规则会被复制到每一段生成代码里。

第二个是版本管理要跟上。 我建议每个技能包目录下维护一个 CHANGELOG.md，每次规则变更记录变更内容和影响范围。当技能库规模超过 10 个技能包时，可以考虑给每个技能包打 tag，比如 commit-convention/v1.2.0，在 SKILL.md 里标注最低兼容版本。

6. 多 Agent 协同与模型编排：从单打独斗到团队流水线

OpenCode 单次对话能解决的问题有限，真正的团队级协作需要多个环节串起来：需求分析、代码生成、自测、审查、提交。这些环节可以让同一个模型扮演不同角色，也可以不同模型分工。

6.1 用 Skill 定义工作流，而不是靠人肉指挥

团队流水线第一个要解决的问题是“流程一致性”。你不希望 A 让 AI 生成完代码就直接提交，B 让 AI 多跑一轮自测。这时候可以写一个 feature-workflow 技能，把标准流程固化成步骤：

markdown复制---
name: feature-workflow
description: 新功能开发的标准工作流。当用户提出新功能开发、需求变更、Bug 修复任务时使用本技能，按流程执行。
---

# 新功能开发工作流

按以下顺序执行：

1. 需求澄清：列出需求中的不明确点，一次最多问 3 个问题
2. 影响面分析：搜索相关模块，列出受影响文件与风险点
3. 设计概要：给出接口设计与数据模型变更方案，等待用户确认
4. 编码实现：按 api-design 技能模板生成代码
5. 自测：调用 test-strategy 技能生成并运行单元测试
6. 提交：调用 commit-convention 技能生成合规提交信息

这个技能本身不写代码，它定义的是“流程”。模型按流程一步步执行，每一步可以做决策、调子技能、问用户确认。效果上，OpenCode 就从“一个会写代码的问答工具”变成了“一个会走流程的开发者”。

6.2 在 CI 和本地跑一条完整链路

OpenCode 的非交互模式可以在 CI 里跑完整链路，比如一个“变更审查”的自动化任务：

bash复制opencode run --format json \
  "读取当前 MR 的变更文件，按 code-review 技能执行检查，输出问题清单和修改建议"

输出 JSON 后，CI 可以直接解析，把结果贴到 MR 评论区。这套玩法对团队的 Code Review 效率提升非常明显：AI 先把机械性问题（格式、命名、缺失校验、重复代码）过一遍，人只关注设计和业务逻辑。

6.3 模型分工：便宜模型做检索，强模型做评审

团队预算有限时，不需要所有环节都用最强的模型。我的实践是：

OpenCode 支持在 opencode.json 里配置多个 provider 和模型，在技能包内也可以指定“本技能默认使用某模型”的偏好。团队可以先统一用一套配置，运行一两周后再根据 token 消耗和效果调优，不必第一版就追求“全流程最强模型”。

7. 实测踩坑清单：这些坑我替你先踩了

最后这部分是干货中的干货。以下问题都是我自己在使用过程中真实遇到过的，按出现的频率排个序，每一个都附了完整的排查思路。

7.1 Windows 下“opencode 无法识别”的完整排查链路

这个问题我在第 2 章提过，但这里再展开一次完整的排查思路，因为团队里总有人会遇到。

当 PowerShell 报“无法将‘opencode’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”时，按顺序检查：

1. 确认装没装上：执行 npm ls -g opencode-ai。没装上就重装，这是最容易被忽略的一步。
2. 找到 npm 全局目录：npm prefix -g，然后把输出路径加到系统 PATH。
3. 检查执行策略：Get-ExecutionPolicy。如果是 Restricted，执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。
4. 重开终端：PowerShell 的 PATH 缓存只在启动时加载，改完环境变量不重开终端等于白改。
5. 如果是 nvm-windows 用户：先 nvm list 看当前版本，再确认 npm prefix -g 指向的目录是否在当前版本的 node_modules 下。这种情况最坑，因为切换 Node 版本后全局命令会消失。

7.2 技能不触发：别让 description 变成废话

技能包写完，模型却不加载，十有八九是 description 写得太泛。比如：

yaml复制description: 检查代码质量。

这种描述几乎永远不会被触发。模型无法从“检查代码质量”判断出“用户说‘给这个函数加点防御’时应该用这个技能”。正确的写法要带场景关键词和触发条件：

yaml复制description: 按团队规范检查代码质量。当用户要求添加参数校验、异常处理、空指针防护，或者在提交代码前要求检查代码时使用。

模型是靠语义匹配触发技能的，不是靠文件名。所以 description 里要把用户可能说的多种表达方式都覆盖到，比如“判空”“防御性编程”“参数校验”都要写进去。

7.3 上下文被技能塞满：给模型减负

技能包的正文越长，模型加载技能时占用的上下文就越多。如果一次对话同时触发三四个技能，光技能正文就可能吃掉上万 token，留给代码分析的窗口就小了。

给模型减负有三个办法：

1. 正文只写“规则和流程”，不写“长篇解释”。解释性文字放 references/ 里，模型需要时按需读取。
2. 能用脚本判断的规则，不要写进正文。让模型跑脚本，拿到输出再解读，比让它自己“背规则”要省 token 得多。
3. 技能不要贪多。一个技能解决一类问题，不要写出一个功能入口处理所有事情的全能技能。

7.4 团队 API Key 泄漏事故

这是所有坑里后果最严重的。团队共享配置时，有人为了方便，直接把 API Key 写进了 opencode.json，然后把这个配置文件连同项目仓库一起推到了远程。当天晚上模型账号就被盗刷了。

一定要把密钥放在环境变量里，配置文件只写变量名：

json复制{
  "provider": {
    "anthropic": {
      "apiKeyEnv": "ANTHROPIC_API_KEY"
    }
  }
}

另外建议定期轮换密钥，并且给每个团队成员独立的 Key，别共用。谁泄露了，直接定位到人。

7.5 跨平台路径与权限：技能脚本的隐藏风险

技能包里的脚本如果用了 Linux 绝对路径，比如 /home/user/project/...，在 Windows 成员机器上就会直接跑挂。写脚本时用相对路径，基于 process.cwd() 或技能包自身目录定位资源。

还有权限问题。scripts/ 下的可执行脚本在被模型执行时，本质是在用户机器上跑任意的子进程。这意味着技能库不能随便加脚本——只要你装了某个技能包，它里面的脚本就有了以你电脑权限运行的能力。这要求团队对技能包的来源和变更保持警惕。我的原则是：技能脚本必须经过 Review，不得从不明来源的公开技能库直接装进团队环境。

最后分享一个我自己的习惯

现在每轮迭代结束后，我会把 Code Review 里重复出现的意见记到一张清单上，每周花半小时决定哪些要沉淀成新技能。这个习惯坚持下来，团队里很多“口头约定”都变成了 AI 默认行为。新同事入职的第一天，把技能库拉下来，OpenCode 就已经具备了团队几个月的规则沉淀——这种“经验可复制”的感觉，是单纯换一个更强模型给不了的。如果你们团队也在用 OpenCode 做结对编程，建议从一个小技能开始试，比如提交信息校验，跑通之后再逐步扩大。