OpenCode使用指南
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/
- Slash Commands：
- 项目级别：
.opencode/- Slash Commands：
.opencode/commands/ - Agent：
.opencode/agents/ - Skills：
.opencode/skills/
- Slash Commands：
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.
作用就是将常用的prompt指令封装成快捷命令，避免每次都要重复输入相同的prompt内容。
例如，可以让AI根据git暂存区的变更内容，生成符合规范的Git Commit Message，并执行提交操作。 在 对于多个参数，可分别用 ---description: create git commitsubtask: 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"`
<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"，“要使用 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.
Agent 可以当成对LLM的"角色设定"，OpenCode比较流行的Oh My OpenCode插件就内置了一些实用的 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的角色设定---mode: primaryhidden: truemodel: opencode/claude-haiku-4-5color: "#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 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.
Skill类似于工作中所说的SOP（标准作业程序），将任务执行步骤与规范封装在Markdown文件中：
- 复用 & 共享：Skill本质上是一个目录，可以提交到代码库进行版本控制，团队共享统一的开发规范
- 渐进式披露：AI初始只加载
SKILL.md中的FrontMatter（名称和描述），实际调用时才加载完整内容，防止上下文过载 - 跨平台：Agent Skills已成为开放标准，同一个Skill可在Claude Code、OpenCode、Cursor、Codex等30+工具中使用
根据 Anthropic 官方的 Complete Guide，创建Skill需关注以下要点。
目录结构
一个标准的Skill由以下文件组成：
your-skill-name/├── SKILL.md # 必须，主指令文件（区分大小写）├── scripts/ # 可选，可执行脚本（Python, Bash等）├── references/ # 可选，参考文档└── assets/ # 可选，模板、字体等资源YAML Frontmatter
Frontmatter是AI决定是否加载该Skill的依据，name 和 description 为必填字段：
---name: your-skill-namedescription: What it does. Use when user asks to [specific trigger phrases].---name：kebab-case，不能有空格或大写（notion-project-setup而非Notion Project Setup），与文件夹名一致description：同时说明做什么 & 何时触发，包含用户可能使用的关键短语，不超过1024字符- 禁止在Frontmatter中使用XML角尖括号
< >
Description 好坏示例
# 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格式基本没问题，但内容建议自己审查一遍。
推荐使用 Vercel 开源的 npx skills CLI 来管理Skill。该工具会自动检测已安装的AI编程工具，将Skill安装到正确的目录。
安装 Skill
# 从 GitHub 仓库安装指定 skillnpx skills add vercel-labs/agent-skills --skill frontend-design# 指定安装到特定工具npx skills add vercel-labs/agent-skills -a claude-code其他常用命令
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等。
The Agent Skills Directory 是目前最主要的Skill发现和排行平台，按分类浏览和搜索社区贡献的Skill：
npx skills add vercel-labs/agent-skills一些推荐的 Skill
- anthropics/skills：Anthropic 官方 Skill 集合
- kepano/obsidian-skills：为 Obsidian 设计的 Skill
- slidev/skills/slidev：Slidev 官方 Skill，用于制作幻灯片
--no-pagerDo not pipe Git output into a pager；意思就是直接输出plain text，对AI更友好。Git - git Documentation ↩︎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 ↩︎
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 or MCP servers . Tools | OpenCode ↩︎
OpenCode使用指南