Jan 06·8 min· PV

A Practical Guide to OpenCode

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.

Agent·Skill·AI

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

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.

git-commit.md

---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 arguments

In <command_name>.md, use $ARGUMENTS to refer to command-line arguments. For example, when you run /<command> 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 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

You can think of an Agent as a “persona” for the LLM. Oh My OpenCode, a popular OpenCode plugin, ships with several useful 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 <agent-name.md>, such as which model to use and which Tools^[3] it can access, and define the agent’s persona in the body

---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’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

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; 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, 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:

---name: your-skill-namedescription: 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

Good and bad description examples

# Bad - too vaguedescription: Helps with projects.# Bad - missing trigger conditionsdescription: Creates sophisticated multi-page documentation systems.# Good - specific, includes trigger phrasesdescription: 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 CLI for managing Skills. It auto-detects which AI coding tools you have installed and puts Skills in the right directory.

Install a Skill

# Install a specific skill from a GitHub reponpx skills add vercel-labs/agent-skills --skill frontend-design# Install into a specific toolnpx skills add vercel-labs/agent-skills -a claude-code

Other common commands

npx skills find typescript     # searchnpx skills remove <skill-name> # removenpx skills check               # check for updatesnpx 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 is currently the main platform for discovering and ranking Skills, where you can browse and search community-contributed Skills by category:

npx skills add vercel-labs/agent-skills

Some recommended Skills

anthropics/skills: Anthropic’s official Skill collection
kepano/obsidian-skills: Skills designed for Obsidian
slidev/skills/slidev: the official Slidev Skill for building slides

--no-pager Do not pipe Git output into a pager; that is, output plain text directly, which is friendlier to 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 ↩︎