OpenCode in 25 Minutes: Setup, Modes & Skills
OpenCode is an open-source, provider-agnostic AI coding assistant with 105,000 GitHub stars. Install it on WSL, connect any AI model (ChatGPT, Claude, local), use Plan mode to think safely and Build mode to execute, configure your repo with agents.md, then create reusable Skills and Commands to automate workflows.
Why OpenCode Matters Right Now
OpenCode Outpaces Claude Code in Community Adoption
OpenCode has 105,000 GitHub stars compared to Claude Code's 67,000, and gained 36,517 stars in a single month, demonstrating rapid ecosystem momentum and indicating it's not just a trend but a genuinely adopted tool.
Fast Ecosystem Growth Means Better Support
When tools move quickly, they attract better documentation, more tutorials, community configurations, and bug-fix posts, which dramatically shortens the learning curve for new users.
What Is OpenCode
OpenCode: Open-Source, MIT-Licensed Alternative to Claude Code
OpenCode is the open-source version of Claude Code with an MIT license, capable of doing almost everything Claude Code does, but with the added benefit of being 100% open source and provider agnostic.
Provider Agnostic—Switch Between Any AI Model
OpenCode works with Claude, OpenAI (including GPT-5.3 Codeex), Google, and local models, letting you test multiple providers and switch when new models launch without changing your workflow.
Installation & Setup on Windows
Install OpenCode on WSL for Best Performance
OpenCode recommends installing on Windows Subsystem for Linux (WSL) for optimal performance and terminal compatibility. Run 'wsl --install' in your terminal, then install OpenCode in the WSL environment.
Unified Workflow: Cursor Editor + WSL Runtime
Use Cursor as your code editor connected to WSL, and run OpenCode in the same WSL terminal. This ensures one repository copy, one set of credentials, and consistent tooling across editor and agent.
The Three Layers of OpenCode
Layer 1: Agents—Build Mode vs. Plan Mode
Agents are the AI workers. Build mode gives full tool access for implementation (edits, bash, file changes); Plan mode restricts permissions and asks before risky actions. Start in Plan mode to design safely, then switch to Build mode to execute.
Layer 2: Rules—agents.md File
agents.md is a living document in your repo root that tells the AI your project structure, conventions, code style, do's and don'ts, and how to run tests. It acts like onboarding notes for a new teammate, preventing you from repeating instructions every prompt.
Layer 3: Extensions—Skills and Commands
Skills are reusable playbooks the agent loads for specific task types (e.g., how to write migrations, create endpoints). Commands are one-shot buttons you run (e.g., /test, /review) that execute fixed prompts. Start with agents.md and basic modes; build skills only when you notice repetition.
Connecting AI Models & Providers
OpenCode Includes Free Models by Default
OpenCode ships with free models like Big Pickle, Miniax, Kimmy, and GLM5 already available, though they are slower (e.g., 16 seconds for a simple hello). You can also connect paid providers like ChatGPT Plus or Anthropic via browser login.
Switch Models Instantly with Ctrl+P
Press Ctrl+P to open the command palette and select from available models or connect new providers. This lets you test different AI models (e.g., GPT-5.3 Codeex vs. Claude) without leaving OpenCode.
agents.md: Your Repo's AI Playbook
Initialize agents.md with /init Command
Run '/init' in OpenCode to auto-generate an agents.md file in your repo root. This file documents setup commands, code style, folder structure, formatting rules, testing procedures, and what not to touch.
agents.md Is a Living Document, Not Write-Once
agents.md evolves as your project grows. It starts as a bootstrap template with placeholders for JavaScript, Python, Go, and Rust, but you customize it to match your actual repo structure and team standards. Commit it so your whole team gets consistent agent behavior.
agents.md Supports Nested Files for Sub-Projects
You can create nested agents.md files in subdirectories to apply different rules to different parts of your codebase, allowing fine-grained control over agent behavior per module or service.
Skills: Reusable Knowledge Playbooks
Skills Are Knowledge Modules, Not Commands
Skills are playbooks the agent loads when it encounters a specific task type (e.g., 'how to write a migration' or 'how to create a new endpoint'). Unlike commands, you don't explicitly run them; the agent loads them automatically based on context.
Build Skills Incrementally, Not Upfront
Don't create a giant skills library on day one. Start with a solid agents.md and use the agents effectively. As you repeat prompts, capture those patterns as skills. This prevents over-engineering and keeps skills relevant.
Skills Live in .opencode/ Folder (Per-Repo) or Config (Global)
Per-project skills go in .opencode/ folder in your repo root; global skills go in your OpenCode config directory. OpenCode walks up the git tree and loads matching skills. Global skills are always available in every repo.
Skill Structure: Name, Description, and Custom Instructions
Each skill requires front matter with a name and description, then you add your custom instructions. Example: a copywriting skill can include guidelines for high-focus language, and the agent will apply those rules when asked to adjust copy.
Commands: Repeatable Prompt Buttons
Commands Are Workflow Shortcuts, Not Playbooks
Commands are explicit buttons you press (e.g., /test, /review, /ship) that run fixed prompts. They reduce typing and prompt mistakes by codifying repeatable workflows into one-word shortcuts.
Command Structure: Description, Agent, Model, and Prompt
Each command specifies which agent to use (build or plan), which model, and the exact prompt to run. You can add arguments using $ placeholders (e.g., /component button creates a React component named 'button').
Commands Live Per-Repo or Globally, Like Skills
Per-project commands go in .opencode/commands; global commands go in your OpenCode config. Commands are stored as JSON files in a config.json structure, making them easy to version control and share with your team.
Multi-Argument Commands Use Numbered Placeholders
For commands with multiple arguments, use $1, $2, etc. in your prompt. Example: /create-component $1 $2 would let you run '/create-component Button primary' to create a Button component with a primary variant.
Practical Workflow & Advanced Features
Recommended Workflow: Plan → Confirm → Build → Review
Always start in Plan mode to design your approach and make it bulletproof. Once confirmed, switch to Build mode to implement. After implementation, switch back to Plan mode to review the changes before committing.
Voice Input: Windows Key + H for Hands-Free Coding
Press Windows+H in OpenCode to activate voice recording and dictate your prompts hands-free. This is useful for quick iterations or accessibility.
Context Management: Track Tokens and Compact Sessions
OpenCode displays token usage, context window percentage, and cost in the right sidebar. When context gets high, run '/compact' to summarize the session and free up tokens without losing conversation history.
Adjust Thinking Level with Ctrl+T
Press Ctrl+T to adjust the AI's reasoning depth (e.g., from regular to extended thinking). This lets you trade speed for deeper analysis on complex tasks.
Language Server Protocol (LSP) Assists Code Writing
OpenCode uses LSP to give the agent smart code features like autocomplete, go-to-definition, hover docs, and linting without needing language-specific logic. The editor and agent communicate via JSON RPC to analyze changes and suggest fixes in real time.
Scaffolding New Skills and Commands
Use /scaffold to Bootstrap New Skills and Commands
Run '/scaffold skill [name]' or '/scaffold command [name]' to auto-generate a template for a new skill or command. OpenCode creates the file structure and front matter, so you only need to customize the instructions.
Restart OpenCode After Adding New Commands
After creating a new command file, press Ctrl+C to exit and reopen OpenCode to reload the command registry. This ensures your new command is available immediately.
Example: Custom Copywriting Skill with High-Focus Language
You can create a skill that encodes your brand voice (e.g., high-focus language guidelines) and reference external documents. The agent then applies those rules consistently when asked to adjust copy, ensuring brand alignment.
Getting Started Checklist
First-Time Setup Steps
Install WSL, open your repo in Cursor via WSL, run OpenCode in WSL terminal, connect your preferred AI model, run '/init' to generate agents.md, then start using Plan and Build modes. Add skills and commands only after you identify repeating patterns.
Notable quotes
When a tool is moving this fast, you usually get better documentation, more tutorials, more community configurations. — Brandon Melville
Really using open code effectively comes down to using both the build mode and the plan mode effectively. — Brandon Melville
agents.md is not a write it once and forget it. agents.md is this file that's living. It's going to change as your repository changes. — Brandon Melville
Action items
- Install WSL on Windows using 'wsl --install' command
- Create a new project directory in WSL and open it in Cursor
- Install OpenCode in WSL and connect your preferred AI model (ChatGPT, Claude, or local)
- Run '/init' in OpenCode to generate agents.md for your repo
- Practice using Plan mode (Tab key) to design features before switching to Build mode
- Create your first custom command using '/scaffold command [name]'
- Create your first custom skill using '/scaffold skill [name]' once you identify a repeating pattern
- Commit agents.md to version control so your team gets consistent agent behavior
- Use '/compact' when context window usage gets high to summarize and free up tokens
- Explore the agents.md documentation at agents.mmd online for advanced configurations