---
title: OpenCode使用指南
date: 2026-01-07
tags:
  - Agent
  - Skill
  - AI
excerpt: "OpenCode是一款AI编程工具，产品是开源的，且限时提供MiniMax 2.1,GLM 4.7和Grok Code Fast 1等免费模型； 本文主要整理「个人使用OpenCode过程中总结的经验」"
---

## Intro

要讲的模块。包括slash commands, agent, agent skills，都是OpenCode中比较重要的功能模块。

### Location

这些模块在存储形式上采用Markdown文件进行存储和管理。可以分为两种层级：

- 全局：`~/.config/opencode/`
    - Slash Commands：`~/.config/opencode/commands/`
    - Agent：`~/.config/opencode/agents/`
    - Skills：`~/.config/opencode/skills/`
- 项目级别：`.opencode/`
    - Slash Commands：`.opencode/commands/`
    - Agent：`.opencode/agents/`
    - Skills：`.opencode/skills/`

### Usage Scenarios

- Slash Commands：将常用的Prompt封装成命令，例如创建Git提交、检查拼写
- Skill：对于需要多步操作，且步骤有规范要求的技能，可以封装到Skill中。例如对Office文件(`.pptx`, `docx`)的处理，需要分解成多个步骤：读取文件内容、分析内容、生成修改建议、输出结果，有些操作还要调用python脚本来辅助完成

## Slash Commands

> Custom commands let you specify a prompt you want to run when that command is executed in the TUI.
>
>  [Commands | OpenCode](https://opencode.ai/docs/commands/)

作用就是将常用的prompt指令封装成快捷命令，避免每次都要重复输入相同的prompt内容。

例如，可以让AI根据git暂存区的变更内容，生成符合规范的Git Commit Message，并执行提交操作。

```md git-commit.md
---
description: create git commit
subtask: true
---

Follow these steps to generate and execute a commit:

1. **Analyze changes**: Run `git --no-pager diff --cached` to examine the staged modifications.
2. **Generate message**: Create a conventional commit message based on the changes using the format:
   - Determine type: `feat` , `fix` , `docs` , `style` , `refactor` , `test` , `chore`
   - Add optional scope in parentheses if applicable, for example, `doc(api)`
   - Write concise description (50 chars max)
   - Add body if explanation needed, separated by blank line, prefer to explain WHY something was done from an end user perspective instead of WHAT was done.
   - The output language should be English if not specified otherwise.
3. **Execute commit**: Run `git commit -m "generated message"`
```

> [!TIPS]- Command 参数
>
> 在 `<command_name>.md` 中，使用 `$ARGUMENTS` 表示命令行参数。例如执行 `/<command> Button` 时，OpenCode会将 `$ARGUMENTS` 替换为 `Button`
>
> 对于多个参数，可分别用 `$1`、`$2` 代替

该Command解决的痛点是：

- VSCode的Copilot自动生成Commit Message总结往往过于简洁
- Cline生成的Commit Message则很详细，但是diff的范围是当前所有的改动，而我只想提交已stage的改动。

有了这个Command，以后只需在对话框中输入 `/git-commit` 即可让AI生成符合规范的Git提交信息，无需每次都强调"要遵循Conventional Commit specification"，"要使用 `{shell} git --no-pager diff --cached` [^1]来获取变更"

## Agent

>  Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
>
> [Agents | OpenCode](https://opencode.ai/docs/agents/)

Agent 可以当成对LLM的"角色设定"，OpenCode比较流行的Oh My OpenCode插件就内置了一些实用的 [AGENTS](https://ohmyopencode.com/agents/)，例如：

- **Planner-Sisyphus agent**: the default agent in Oh My OpenCode. It provides intelligent planning and execution capabilities, helping you break down complex tasks and execute them systematically.
- **Librarian Agent**: specialized for documentation and code exploration. It helps you find relevant code, understand codebases, and manage knowledge effectively.
- **Explore Agent**: designed for code exploration and navigation. It helps you efficiently navigate and understand large codebases.
- **Oracle agent**: a question-answering agent that provides intelligent responses based on codebase context. It's designed to answer questions about your code and help you understand complex concepts.

可以在 `<agent-name.md>` 的FrontMatter[^2]中指定Agent的配置，如使用的model、可用的Tools[^3]等，在正文中定义Agent的角色设定

```yaml
---
mode: primary
hidden: true
model: opencode/claude-haiku-4-5
color: "#E67E22"
tools:
  "*": false
  "github-pr-search": true
---

You are a duplicate PR detection agent. When a PR is opened, your job is to search for potentially duplicate or related open PRs.
...
```

### Awesome Agents

-  [Web Interface Guidelines](https://vercel.com/design/guidelines#interactions) Vercel的Web界面设计规范Agent，底部有提供 `AGENTS.md`，可以帮你检查UI设计是否符合Vercel的设计规范

## Agent Skills

>  A skill is a set of instructions - packaged as a simple folder - that teaches Claude how to handle specific tasks or workflows. Instead of re-explaining your preferences, processes, and domain expertise in every conversation, skills let you teach Claude once and benefit every time.
>
>  [The Complete Guide to Building Skills for Claude](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)

Skill类似于工作中所说的**SOP**（标准作业程序），将任务执行步骤与规范封装在Markdown文件中：

- **复用 & 共享**：Skill本质上是一个目录，可以提交到代码库进行版本控制，团队共享统一的开发规范
- **渐进式披露**：AI初始只加载 `SKILL.md` 中的FrontMatter（名称和描述），实际调用时才加载完整内容，防止上下文过载
- **跨平台**：Agent Skills已成为[开放标准](https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem)，同一个Skill可在Claude Code、OpenCode、Cursor、Codex等30+工具中使用

<script data-swup-reload-script type="module" src="/js/components/accordion.js"></script>

<x-accordion>
  <accordion-item title="Build: 创建 Skill">

根据 Anthropic 官方的 [Complete Guide](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf)，创建Skill需关注以下要点。

**目录结构**

一个标准的Skill由以下文件组成：

```
your-skill-name/
├── SKILL.md           # 必须，主指令文件（区分大小写）
├── scripts/           # 可选，可执行脚本（Python, Bash等）
├── references/        # 可选，参考文档
└── assets/            # 可选，模板、字体等资源
```

**YAML Frontmatter**

Frontmatter是AI决定是否加载该Skill的依据，`name` 和 `description` 为必填字段：

```yaml
---
name: your-skill-name
description: What it does. Use when user asks to [specific trigger phrases].
---
```

- `name`：**kebab-case**，不能有空格或大写（`notion-project-setup` 而非 `Notion Project Setup`），与文件夹名一致
- `description`：同时说明**做什么** & **何时触发**，包含用户可能使用的关键短语，不超过1024字符
- 禁止在Frontmatter中使用XML角尖括号 `< >`

> [!TIP]- Description 好坏示例
>
> ```yaml
> # Bad - 太模糊
> description: Helps with projects.
>
> # Bad - 缺少触发条件
> description: Creates sophisticated multi-page documentation systems.
>
> # Good - 具体，包含触发短语
> description: Analyzes Figma design files and generates developer
>   handoff documentation. Use when user uploads .fig files, asks for
>   "design specs", "component documentation", or "design-to-code handoff".
> ```

**编写指令的最佳实践**

- 指令要**具体可执行**：`Run python scripts/validate.py --input {filename}` 优于 "Validate the data before proceeding"
- 关键指令放在顶部，使用 `## Important` 或 `## Critical` 标题强调
- 详细文档放入 `references/` 目录并在 SKILL.md 中引用，保持主文件在5000词以内
- 包含错误处理说明和常见问题的解决方案

**快速上手**：使用内置的 `skill-creator`，让AI帮你生成初稿：

```
"Use the skill-creator skill to help me build a skill for [your use case]"
```

AI生成的Skill格式基本没问题，但内容建议自己审查一遍。

  </accordion-item>
  <accordion-item title="Install: 安装 Skill">

推荐使用 Vercel 开源的 [`npx skills`](https://github.com/vercel-labs/skills) CLI 来管理Skill。该工具会自动检测已安装的AI编程工具，将Skill安装到正确的目录。

**安装 Skill**

```shell
# 从 GitHub 仓库安装指定 skill
npx skills add vercel-labs/agent-skills --skill frontend-design

# 指定安装到特定工具
npx skills add vercel-labs/agent-skills -a claude-code
```

**其他常用命令**

```shell
npx skills find typescript     # 搜索
npx skills remove <skill-name> # 移除
npx skills check               # 检查更新
npx skills update              # 更新
```

支持的平台包括：Claude Code、OpenCode、Cursor、Codex、Gemini CLI、Windsurf、GitHub Copilot等。

  </accordion-item>
  <accordion-item title="Market: 技能市场">

**[The Agent Skills Directory](https://skills.sh/)** 是目前最主要的Skill发现和排行平台，按分类浏览和搜索社区贡献的Skill：

```shell
npx skills add vercel-labs/agent-skills
```

  </accordion-item>
</x-accordion>

**一些推荐的 Skill**

- [anthropics/skills](https://github.com/anthropics/skills)：Anthropic 官方 Skill 集合
- [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills)：为 Obsidian 设计的 Skill
- [slidev/skills/slidev](https://github.com/slidevjs/slidev/tree/main/skills/slidev)：Slidev 官方 Skill，用于制作幻灯片

[^1]: `--no-pager` Do not pipe Git output into a pager；意思就是直接输出plain text，对AI更友好。[Git - git Documentation](https://git-scm.com/docs/git/2.26.0)
[^2]: Frontmatter is a way to add metadata to your Markdown documents using YAML, TOML, or JSON at the beginning of the file. It's widely used in static site generators and content management systems. [Using Frontmatter in Markdown - Markdown Documentation](https://www.markdownlang.com/advanced/frontmatter.html)
[^3]: Tools allow the LLM to perform actions in your codebase. OpenCode comes with a set of built-in tools, but you can extend it with [custom tools](https://opencode.ai/docs/custom-tools) or [MCP servers](https://opencode.ai/docs/mcp-servers) . [Tools | OpenCode](https://opencode.ai/docs/tools/)