OpenCode Skills 和 Commands：打造你的 AI 工作流

用 AI 写代码这事，大家应该都不陌生了。但有个问题一直困扰我：每次让 AI 干活，都要重复描述一遍"你要怎么做"。比如写 commit message，每次都得说"看看改了啥，帮我写个规范的 commit"；比如做 code review，每次都得贴一堆规则。时间长了，我就在想——能不能把这些"指令模板"存起来，用的时候一句话就调出来？

OpenCode 给出了两个很优雅的答案：Skills 和 Commands。这两个机制让我把重复性的 AI 交互全部标准化了，效果出奇地好。

我花了大约一周时间把这两个系统摸透了，踩了不少坑，也总结出了一套实用的玩法。今天把心得分享给大家。

本文提纲

Skills：用 Markdown 给 AI 写"技能卡"
Auto-discovery：OpenCode 怎么找到你的 Skills
动手写一个自定义 Skill
Skills 的权限控制
Commands：一句话触发完整工作流
内置 Commands 详解
自定义 Command 实战
Skills vs Commands：什么时候用哪个

Skills：用 Markdown 给 AI 写"技能卡"

先说 Skills。简单讲，一个 Skill 就是一份 Markdown 文件，里面写着"遇到什么情况该怎么做"。AI 在运行过程中会看到所有可用的 Skills 列表，根据当前任务判断要不要加载某个 Skill。

每个 Skill 的核心是一个 SKILL.md 文件，必须以 YAML frontmatter 开头。先看一个最简单的例子：

---
name: git-release
description: Create consistent releases and changelogs
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

Frontmatter 里只有两个字段是必须的：

name：Skill 的名字，要求全小写、用连字符分隔，比如 git-release、code-review
description：一句话描述，告诉 AI 这个 Skill 干什么用，最多 1024 个字符

还有几个可选字段：license、compatibility、metadata（一个 string-to-string 的 map）。不过说实话，日常使用基本用不到这些。

name 的命名有严格规则：只能包含小写字母、数字和连字符，不能以连字符开头或结尾，不能有连续连字符。对应的正则是 ^[a-z0-9]+(-[a-z0-9]+)*$。记住这一点就行：用 kebab-case，别搞花样。

Auto-discovery：OpenCode 怎么找到你的 Skills

OpenCode 会在好几个目录里自动搜索 Skills。这就是它的 auto-discovery 机制，不需要你做任何配置，只要文件放在对的位置就行。

项目级别（跟随项目）：

路径	说明
`.opencode/skills/<name>/SKILL.md`	OpenCode 原生路径
`.claude/skills/<name>/SKILL.md`	兼容 Claude Code
`.agents/skills/<name>/SKILL.md`	兼容通用 Agent 规范

全局级别（所有项目共享）：

路径	说明
`~/.config/opencode/skills/<name>/SKILL.md`	OpenCode 全局
`~/.claude/skills/<name>/SKILL.md`	Claude 全局
`~/.agents/skills/<name>/SKILL.md`	Agent 全局

这里有个细节值得注意：OpenCode 会从当前工作目录向上遍历，直到 git worktree 的根目录。也就是说，如果你在子目录里工作，OpenCode 也能找到项目根目录下的 Skills。这个设计很贴心，不用关心你在哪个目录启动。

实际效果是这样的：AI 启动后，所有 Skills 的 name 和 description 会被注入到 skill 工具的描述中，AI 能看到一份完整的"技能清单"。当 AI 判断需要某个 Skill 时，它会调用 skill({ name: "git-release" }) 来加载完整内容。

这意味着什么？Skills 不是一开始就塞进上下文的，而是按需加载。这个设计很聪明——你有 50 个 Skill 也不会撑爆 context window，AI 只在需要的时候才去读。

动手写一个自定义 Skill

光说不练假把式，我们来写一个实际的 Skill。假设我想要一个帮我做 PR Review 的 Skill，放在项目目录下：

---
name: pr-review
description: Review pull requests with focus on security, performance and readability
---

## Review Checklist

Review the following aspects in order:

### 1. Security
- Check for hardcoded secrets, API keys, tokens
- Validate input sanitization
- Look for SQL injection, XSS vulnerabilities
- Verify authentication/authorization logic

### 2. Performance
- Identify N+1 queries or unnecessary database calls
- Check for memory leaks (unclosed connections, missing cleanup)
- Flag O(n²) algorithms that could be O(n)

### 3. Code Quality
- Functions should do one thing (SRP)
- No magic numbers - use named constants
- Meaningful variable names, no single-letter names (except loop counters)

### 4. Tests
- Are new features covered by tests?
- Are edge cases tested?
- No flaky test patterns (time-dependent, random-dependent)

## Output Format

For each issue found:
1. **File and line number**
2. **Severity**: Critical / Warning / Suggestion
3. **Description**: What's wrong
4. **Suggested fix**: Code snippet if applicable

Start with the most critical issues. Be direct - skip obvious praise.

保存到 .opencode/skills/pr-review/SKILL.md，搞定。

使用的时候，AI 看到你在讨论 PR Review 相关的话题，就会自动加载这个 Skill。你也可以直接跟 AI 说"用 pr-review skill 来帮我 review 这段代码"。

我自己的实践经验是：Skill 的内容越具体越好。不要写"请注意代码质量"这种空话，要写具体的检查项和输出格式。AI 拿到明确的指令，输出质量会高很多。

另一个技巧是把常用的团队规范放进 Skill。比如我们的 API 设计规范、数据库迁移规范，每个都写成一个 Skill。新人加入团队后，AI 就自带了团队的规范意识，非常省心。

Skills 的权限控制

如果你的项目有些 Skill 不想让 AI 随便用（比如内部工具相关的），OpenCode 提供了权限控制。在 opencode.json 里这样配置：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

三种权限行为：

allow：Skill 直接加载，不需要确认
deny：AI 完全看不到这个 Skill，就像不存在一样
ask：加载前会弹窗问你"是否允许"

支持通配符，internal-* 会匹配所有以 internal- 开头的 Skill。这对管理大型项目特别有用。

你还可以针对不同的 Agent 设置不同的权限。比如让 plan agent 能访问内部 Skill，但 code agent 不行：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

如果某个 Agent 完全不需要 Skills，可以直接关掉 skill 工具：

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Commands：一句话触发完整工作流

如果说 Skills 是 AI 的"知识储备"，那 Commands 就是用户的"快捷键"。

Commands 的用法很简单：在 TUI 里输入 /command-name，就能触发一段预设的 prompt。比如输入 /commit，AI 就会自动分析当前的 git 变更，帮你写 commit message。

Commands 的定义方式有两种：

方式一：Markdown 文件（推荐）

在 .opencode/commands/ 目录下创建 Markdown 文件，文件名就是命令名：

---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report and show any failures.
Focus on the failing tests and suggest fixes.

保存为 .opencode/commands/test.md，之后在 TUI 里输入 /test 就能用了。

方式二：JSON 配置

在 opencode.json 里定义：

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build"
    }
  }
}

两种方式效果一样，但我更推荐 Markdown 方式——直观、版本友好、方便团队共享。

Commands 的存放位置和 Skills 类似：

全局：~/.config/opencode/commands/
项目级：.opencode/commands/

项目级的 Command 会覆盖全局同名 Command。自定义 Command 还能覆盖内置 Command——如果你觉得内置的 /commit 不合你意，完全可以定义自己的版本。

内置 Commands 详解

OpenCode 自带了一批实用的内置 Commands。这些是日常开发中用得最多的：

/commit

最常用的命令之一。它会分析当前 git 暂存区的变更，自动生成符合 Conventional Commits 规范的 commit message。你只需要检查一下、回车确认就行。

/changelog

根据最近的 git 历史生成 CHANGELOG。会按照 feat、fix、break 等类型分类整理。对维护开源项目的同学特别友好。

/issues

扫描代码库，找出潜在的 bug、安全问题和改进点。相当于让 AI 给你的项目做一次全面体检。

/learn

这个命令很特别。它让 AI 学习你项目的结构和约定——读 AGENTS.md、配置文件、已有代码风格，然后总结出项目的工作模式。第一次打开一个新项目时跑一下 /learn，后续的 AI 交互会精准很多。

/spellcheck

检查 markdown 文件和代码注释中的拼写错误。对写文档的同学来说是个神器。

/rmslop

这个名字挺有趣的——"remove slop"。它会清理 AI 生成的代码中常见的冗余模式：多余的注释、过度的错误处理、不必要的抽象层。我每次让 AI 写完代码都会跑一遍这个命令，代码质量肉眼可见地提升。

除了这些"内容型"命令，还有一些 TUI 操作命令也很实用：/compact 压缩当前会话上下文、/undo 撤回上一轮对话、/new 开始新会话、/share 分享当前对话。

自定义 Command 实战

内置命令不够用？自己写。Commands 最强大的地方在于支持参数、Shell 输出和文件引用。

参数传递

用 $ARGUMENTS 接收全部参数，用 $1、$2、$3 接收位置参数：

---
description: Create a new React component
---

Create a new React component named $ARGUMENTS with TypeScript support.
Include proper typing, basic structure, and a test file.

保存为 .opencode/commands/component.md，然后在 TUI 里：

/component Button

$ARGUMENTS 会被替换成 Button。位置参数的用法：

/create-file config.json src "{ \"key\": \"value\" }"

这里 $1 = config.json，$2 = src，$3 = { "key": "value" }。

注入 Shell 输出

用 ! + 反引号的语法可以把 Shell 命令的输出注入到 prompt 中：

---
description: Review recent changes
---

Recent git commits:
!`git log --oneline -10`

Review these changes and suggest any improvements.

当你在 TUI 里输入 /review-changes 时，OpenCode 会先执行 git log --oneline -10，把输出结果拼到 prompt 里，然后发给 AI。这意味着每次执行拿到的都是最新的 git 状态。

再举一个实用的例子——分析测试覆盖率：

---
description: Analyze test coverage
---

Here are the current test results:
!`npm test`

Based on these results, suggest improvements to increase coverage.

文件引用

用 @ 加文件路径可以把文件内容直接引用进来：

---
description: Review component
---

Review the component in @src/components/Button.tsx.
Check for performance issues and suggest improvements.

指定 Agent 和 Model

Command 还支持指定用哪个 Agent 执行、用哪个 Model：

---
description: Code review
agent: plan
model: anthropic/claude-3-5-sonnet-20241022
subtask: true
---

Review the current staged changes for potential issues.

subtask: true 会让 Command 以子任务方式运行，不会污染当前会话的上下文。这对复杂的分析任务特别有用——跑完结果出来，你的主对话还是干干净净的。

Skills vs Commands：什么时候用哪个

这两个机制经常让人混淆。我总结了一个简单的判断标准：

用 Skills 当：

定义的是"AI 应该怎么思考"，是行为规范
需要跨多个场景复用（比如"写代码时始终遵循 XX 规范"）
内容可能比较长，不希望每次都占上下文
AI 应该根据上下文自动判断是否加载

用 Commands 当：

定义的是"用户说一句话，AI 执行一整套流程"
有明确的触发时机（"我现在要做 XX"）
需要接受用户参数
需要注入动态内容（Shell 输出、文件引用）

一个直观的对比：

维度	Skills	Commands
触发方式	AI 自动判断	用户主动输入 `/xxx`
加载时机	按需加载	立即执行
支持参数	否	是（$ARGUMENTS、$1...）
Shell 输出	否	是（!`cmd`）
文件引用	否	是（@path）
适合场景	行为规范、团队约定	一次性工作流、快捷操作
上下文占用	只在加载时占用	每次执行都占用

我自己的实践是：团队规范、代码风格、安全检查清单这些放进 Skills；日常操作——commit、review、deploy 这些放进 Commands。两者配合使用，AI 的输出质量会有质的提升。

最后补充一个踩坑经验：Skills 加载失败最常见的原因是文件名不对。记住，必须是全大写的 SKILL.md，写成 skill.md 或 Skill.md 都不会被识别。这个问题我排查了半小时才发现，希望你不用再踩。

作者: itech001 来源: 公众号：AI人工智能时代主页: https://www.theaiera.cn（每日分享最前沿的AI新闻和技术）

本文首发于 AI人工智能时代，转载请注明出处。