--- title: A Practical Guide to OpenCode date: 2026-01-07 tags: - Agent - Skill - AI excerpt: "OpenCode is an open-source AI coding tool with free models like MiniMax 2.1, GLM 4.7, and Grok Code Fast 1. Here are the lessons from my own daily use." updated: 2026-07-08 21:17:39 lang: en i18n: cn: /ai_skills translation: 2 --- ## Intro This post covers slash commands, agents, and agent skills, the most important feature modules in OpenCode. ### Location All of them are stored and managed as Markdown files, at two levels: - Global: `~/.config/opencode/` - Slash Commands: `~/.config/opencode/commands/` - Agent: `~/.config/opencode/agents/` - Skills: `~/.config/opencode/skills/` - Project-level: `.opencode/` - Slash Commands: `.opencode/commands/` - Agent: `.opencode/agents/` - Skills: `.opencode/skills/` ### Usage Scenarios - Slash Commands: package frequently used prompts as commands, e.g. creating Git commits or checking spelling - Skill: for tasks that need multiple steps with strict requirements on how each step is done, wrap them into a Skill. For example, processing Office files (`.pptx`, `.docx`) breaks down into several steps: read the file content, analyze it, generate change suggestions, output the result, and some steps need helper Python scripts ## 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/) The point is to package frequently used prompts as shortcut commands, so you don't have to retype the same prompt every time. For example, you can have the AI generate a well-formed Git commit message from the staged changes and run the commit. ```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 arguments > > In `.md`, use `$ARGUMENTS` to refer to command-line arguments. For example, when you run `/ Button`, OpenCode replaces `$ARGUMENTS` with `Button` > > For multiple arguments, use `$1`, `$2`, and so on The pain points this Command solves: - Commit messages auto-generated by VSCode's Copilot tend to be too terse - Cline generates detailed commit messages, but it diffs all current changes, while I only want to commit what's staged. With this Command, I just type `/git-commit` in the chat box and the AI produces a well-formed commit message. No more repeating "follow the Conventional Commit specification" or "use `{shell} git --no-pager diff --cached` [^1] to get the changes" every time. ## 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/) You can think of an Agent as a "persona" for the LLM. Oh My OpenCode, a popular OpenCode plugin, ships with several useful [AGENTS](https://ohmyopencode.com/agents/), for example: - **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. You configure an agent in the frontmatter[^2] of ``, such as which model to use and which Tools[^3] it can access, and define the agent's persona in the body ```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's web interface design guideline agent. There is an `AGENTS.md` at the bottom of the page; it can check whether your UI follows Vercel's design guidelines ## 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) A Skill is like an **SOP** (standard operating procedure) at work: it packages the steps and conventions of a task into Markdown files: - **Reuse & sharing**: a Skill is essentially a directory, so it can be committed to a repo for version control and the whole team shares the same conventions - **Progressive disclosure**: the AI initially loads only the frontmatter of `SKILL.md` (name and description), and loads the full content only when the skill is actually invoked, preventing context overload - **Cross-platform**: Agent Skills has become an [open standard](https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem); the same Skill works across 30+ tools including Claude Code, OpenCode, Cursor, and Codex
Build: creating a Skill According to Anthropic's official [Complete Guide](https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf), these are the key points when building a Skill. **Directory structure** A standard Skill consists of the following files: ``` your-skill-name/ ├── SKILL.md # Required, the main instruction file (case-sensitive) ├── scripts/ # Optional, executable scripts (Python, Bash, etc.) ├── references/ # Optional, reference docs └── assets/ # Optional, templates, fonts, and other assets ``` **YAML Frontmatter** The frontmatter is what the AI uses to decide whether to load the Skill. `name` and `description` are required: ```yaml --- name: your-skill-name description: What it does. Use when user asks to [specific trigger phrases]. --- ``` - `name`: **kebab-case**, no spaces or uppercase (`notion-project-setup`, not `Notion Project Setup`), and it must match the folder name - `description`: state both **what it does** and **when to trigger it**, include key phrases the user might type, no more than 1024 characters - Do not use XML angle brackets `< >` in the frontmatter > [!TIP]- Good and bad description examples > > ```yaml > # Bad - too vague > description: Helps with projects. > > # Bad - missing trigger conditions > description: Creates sophisticated multi-page documentation systems. > > # Good - specific, includes trigger phrases > 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". > ``` **Best practices for writing instructions** - Make instructions **specific and executable**: `Run python scripts/validate.py --input {filename}` beats "Validate the data before proceeding" - Put critical instructions at the top, and emphasize them with `## Important` or `## Critical` headings - Move detailed docs into `references/` and reference them from SKILL.md, keeping the main file under 5000 words - Include error-handling notes and solutions to common problems **Quick start**: use the built-in `skill-creator` and let the AI draft one for you: ``` "Use the skill-creator skill to help me build a skill for [your use case]" ``` The format of AI-generated Skills is usually fine, but you should review the content yourself.
Install: installing Skills I recommend Vercel's open-source [`npx skills`](https://github.com/vercel-labs/skills) CLI for managing Skills. It auto-detects which AI coding tools you have installed and puts Skills in the right directory. **Install a Skill** ```shell # Install a specific skill from a GitHub repo npx skills add vercel-labs/agent-skills --skill frontend-design # Install into a specific tool npx skills add vercel-labs/agent-skills -a claude-code ``` **Other common commands** ```shell npx skills find typescript # search npx skills remove # remove npx skills check # check for updates npx skills update # update ``` Supported platforms include Claude Code, OpenCode, Cursor, Codex, Gemini CLI, Windsurf, GitHub Copilot, and more.
Market: skill marketplace **[The Agent Skills Directory](https://skills.sh/)** is currently the main platform for discovering and ranking Skills, where you can browse and search community-contributed Skills by category: ```shell npx skills add vercel-labs/agent-skills ```
**Some recommended Skills** - [anthropics/skills](https://github.com/anthropics/skills): Anthropic's official Skill collection - [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills): Skills designed for Obsidian - [slidev/skills/slidev](https://github.com/slidevjs/slidev/tree/main/skills/slidev): the official Slidev Skill for building slides [^1]: `--no-pager` Do not pipe Git output into a pager; that is, output plain text directly, which is friendlier to 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/)