OpenCode Skills 教程：7 个规则复用 AI 编程工作流

本页只覆盖 opencode skill 的独立搜索意图。本站已有部署页处理安装，Ollama 页处理本地模型，MCP 页处理外部工具服务，session storage 页处理本地历史。Skills 位于这些主题之间：它们改变 OpenCode 执行重复工作的方式，但不等于 provider、shell 命令或远程集成。

如果同一段说明反复出现在提示词里，就值得考虑 skill：审查迁移、写发布说明、检查高风险 diff、生成多语言 SEO 页面或执行仓库测试仪式。如果只是一次性提醒，直接写进当前提示词；如果是永远不变的个人偏好，放在普通配置或项目文档里更合适。

最好的判断方法是实际跑一次。用拟定 skill 做一个小任务，再和普通提示词结果对比。如果 skill 减少重复解释并产出更干净的 diff，就保留；如果只是增加空泛原则却没有改善结果，就删除或压缩。

全局 skill 适合跨仓库都成立的个人习惯，例如代码审查摘要方式、验收记录格式、常见本地工具流程。项目 skill 适合仓库规则，例如路由约定、测试命令、内容风格、安全边界、本地化规则和部署限制。

团队更容易审查项目 skill，因为它靠近受影响的代码。全局 skill 很强，但也容易把某个技术栈的规则带到另一个仓库。只要 skill 提到框架、部署目标、内容口吻或合规规则，通常应优先放在项目级。

Skill 用来复用指导原则；command 用来触发明确命名的工作流；agent 用来隔离角色、工具范围或上下文；MCP 用来把外部服务工具暴露给 OpenCode。它们可以配合，但不应该互相伪装。

例如代码审查 skill 说明风险优先级，发布 command 启动发布清单，专门 agent 独立检查大型子系统，MCP server 提供 issue 或设计数据。如果把四件事都塞进一个 skill，排错时就分不清到底是指令、角色、工具还是外部服务失败。

有用的 skill 要说明用途、触发条件、作用范围、必要步骤和停止规则。它应该告诉 agent 必须做什么、必须避免什么。示例要靠近对应判断，避免长背景、口号式语言和无关偏好。

把 skill 当代码一样审查。如果它改变输出风格，就给一个短示例；如果它改变安全行为，就说明风险；如果它改变验收方式，就写清命令或证据。无法测试的 skill 往往范围太宽。

先从最小 skill 开始，不要一上来做大型库。下面的形状刻意保持短：定义适用场景、要检查的上下文、必须运行的验证，以及如何报告结果。请把占位语言替换为真实仓库命令和规则。

---
name: repository-review
description: Use when reviewing code changes in this repository.
---

# Repository Review

1. Inspect the changed files and nearby tests before giving findings.
2. Prioritize bugs, regressions, security risks, and missing validation.
3. Run the documented test command when the touched area has one.
4. Report findings first with file and line references.
5. If no issue is found, say so and mention residual test risk.

不要把 API key、token、私有 base URL、客户数据或生产凭据写进 skill。Skill 可以描述如何处理密钥，但不应该包含密钥本身。请使用环境变量、provider 登录、密码管理器或官方凭据路径。

权限也要保持显式。如果 skill 允许编辑文件、执行命令、发布或部署，就应要求验证和审查证据。Skill 可以让重复工作更快，但不应该悄悄拿走用户检查高风险变更的机会。

如果某个 skill 让结果变差，先禁用无关指令。然后分别用 skill、普通提示词和缩短版 skill 跑同一任务。多数失败来自重叠：skill 与项目文档、用户提示、另一个 skill 或工具策略互相竞争。

团队 skill 要保留小型变更记录：为什么存在、解决了什么问题、更新后验证发生了什么变化。如果没人能解释最近三次修改，skill 可能已经变成隐藏制度堆，而不是工作流契约。

如果你要把 AGENTS.md 规则拆成具名 subagents，请先阅读 OpenCode agents 指南，确认角色、模型和工具边界。 OpenCode agents 指南.