OpenCode Template

Comprehensive template repository for OpenCode CLI - a powerful AI-assisted development environment with agents, commands, and skills.

What is OpenCode?

OpenCode is an AI-powered development CLI that helps you build software faster through:

• Agents: Specialized AI assistants for different development tasks
• Commands: Pre-built workflows for common operations
• Skills: Reusable knowledge modules that enhance agent capabilities
• Plugins: Extensions that add custom functionality

Quick Start

Prerequisites

• OpenCode CLI installed
• Node.js 18+ (for MCP servers)
• Git

Installation

1. Install OpenCode CLI (if not already installed)

2. Clone this template:

git clone https://github.com/julianromli/opencode-template.git
cd opencode-template

3. Setup Environment Variables (IMPORTANT):

   Windows (PowerShell as Administrator):

   cd scripts
   .\setup-env-windows.ps1

   macOS/Linux:

   cd scripts
   bash setup-env-mac.sh
   source ~/.zshrc  # or ~/.bashrc

   See scripts/README.md for detailed instructions and troubleshooting.

4. Initialize your project:

opencode init

5. Restart your terminal or IDE for environment variables to take effect

Required Environment Variables

The setup scripts configure these essential variables:

OPENCODE_EXPERIMENTAL_PLAN_MODE=1    # Enable experimental features
OPENCODE_UNSAFE_ALLOW_OUTSIDE=1      # Allow operations outside workspace
OPENCODE_UNSAFE_FILES=1              # Enable file operations
OPENCODE_UNSAFE_INCLUDE_GIT=1        # Enable git operations

Why these are needed:

• Enable advanced OpenCode features
• Allow AI agents to perform file and git operations
• Required for full template functionality

Basic Usage

Start OpenCode in your project:

opencode

Invoke an agent:

opencode agent <agent-name>

Run a command:

opencode command <command-name>

Repository Structure

.
├── agent/              # AI agent definitions
│   ├── core/          # Core system agents
│   ├── development/   # Development-focused agents
│   ├── content/       # Content creation agents
│   ├── data/          # Data analysis agents
│   ├── meta/          # Meta-level agents
│   └── subagents/     # Specialized sub-agents
├── command/           # Command definitions
│   ├── openagents/    # OpenAgents-specific commands
│   └── prompt-engineering/ # Prompt optimization commands
├── skill/             # Skill modules
│   ├── backend-dev/   # Backend development patterns
│   ├── frontend-design/ # Frontend design guidelines
│   ├── next-best-practices/ # Next.js best practices
│   └── ...            # Many more specialized skills
├── plugin/            # Plugin scripts
├── tool/              # Custom tools
└── opencode.json      # OpenCode configuration

Core Components

Agents

Agents are specialized AI assistants that handle specific tasks:

• Core Agents (agent/core/):

  • openagent.md - General-purpose agent
  • opencoder.md - Coding-focused agent

• Development Agents (agent/development/):

  • backend-specialist.md - Backend development
  • frontend-specialist.md - Frontend development
  • devops-specialist.md - DevOps and infrastructure
  • codebase-agent.md - Codebase analysis

• Specialized Agents:

  • Database architects
  • Security coders
  • Code reviewers
  • Content writers
  • Data analysts

Commands

Pre-built workflows for common tasks:

• Development:

  • build-context-system.md - Build context management
  • debug.md - Debugging workflows
  • fix.md - Bug fixing procedures
  • refactor-clean.md - Code refactoring
  • test.md - Testing workflows

• Planning:

  • brainstorm.md - Ideation sessions
  • write-plan.md - Project planning
  • execute-plan.md - Plan execution

• Quality:

  • review.md - Code review
  • optimize.md - Performance optimization
  • validate-repo.md - Repository validation

• Content:

  • design-system.md - Design system creation
  • seo.md - SEO optimization
  • enhance.md - Content enhancement

Skills

Reusable knowledge modules that enhance agent capabilities:

• Backend Development:

  • backend-dev/ - Backend patterns and practices
  • database-design/ - Database architecture
  • llm-application-dev/ - LLM app development

• Frontend Development:

  • frontend-design/ - UI/UX design principles
  • frontend-ui-animator/ - Animation patterns
  • next-best-practices/ - Next.js optimization
  • vercel-react-best-practices/ - React performance

• Development Practices:

  • test-driven-development/ - TDD methodology
  • code-refactoring/ - Refactoring strategies
  • systematic-debugging/ - Debugging techniques
  • subagent-driven-development/ - Multi-agent workflows

• Tools & Utilities:

  • skill-creator/ - Create new skills
  • shadcn-management/ - shadcn/ui component management
  • browser/ - Browser automation
  • using-git-worktrees/ - Git worktree workflows

Configuration

opencode.json

Main configuration file for OpenCode:

{
  "version": "1.0",
  "agents": {
    "directory": "agent"
  },
  "commands": {
    "directory": "command"
  },
  "skills": {
    "directory": "skill"
  },
  "plugins": {
    "directory": "plugin"
  }
}

Creating Custom Components

Creating an Agent

1. Create a new .md file in agent/ directory
2. Define agent capabilities and behavior
3. Reference relevant skills and tools

Example structure:

# Agent Name

## Purpose
Brief description of what this agent does

## Capabilities
- Capability 1
- Capability 2

## Skills Used
- skill-name-1
- skill-name-2

## Instructions
Detailed instructions for the agent...

Creating a Command

1. Create a new .md file in command/ directory
2. Define command workflow and steps
3. Specify required inputs and outputs

Creating a Skill

1. Create a new directory in skill/
2. Add SKILL.md with skill documentation
3. Add reference materials in references/ subdirectory
4. Add scripts in scripts/ subdirectory if needed

Use the skill-creator skill to automate this:

opencode skill create <skill-name>

Advanced Features

Subagents

Subagents are specialized agents that can be invoked by other agents:

• Code Subagents (agent/subagents/code/):

  • Build agent
  • Coder agent
  • Reviewer
  • Tester

• Core Subagents (agent/subagents/core/):

  • Context retriever
  • Documentation generator
  • Task manager

Agent Categories

Organize agents using 0-category.json files:

{
  "name": "Category Name",
  "description": "Category description",
  "icon": "icon-name"
}

Best Practices

Agent Development

1. Single Responsibility: Each agent should have one clear purpose
2. Skill Composition: Leverage existing skills rather than duplicating knowledge
3. Clear Instructions: Provide explicit, step-by-step instructions
4. Error Handling: Include error handling and recovery strategies

Command Development

1. Modular Steps: Break commands into clear, sequential steps
2. Validation: Include validation checks at each step
3. Documentation: Document inputs, outputs, and side effects
4. Idempotency: Commands should be safe to run multiple times

Skill Development

1. Focused Scope: Keep skills focused on specific domains
2. Reference Materials: Include examples and reference documentation
3. Versioning: Track skill versions and changes
4. Testing: Test skills with multiple agents and scenarios

Common Workflows

Starting a New Project

# Initialize project
opencode init

# Generate project structure
opencode command design-system

# Set up development environment
opencode agent backend-specialist "Set up project structure"

Code Review Workflow

# Request code review
opencode command review

# Or use the code reviewer agent directly
opencode agent code-reviewer "Review recent changes"

Debugging Workflow

# Use systematic debugging
opencode command debug

# Or invoke debugging skill
opencode agent opencoder "Use systematic-debugging skill to fix issue"

Troubleshooting

Agent Not Found

Ensure agent file exists in agent/ directory and is properly formatted.

Skill Not Loading

Check:

1. Skill directory contains SKILL.md
2. Skill is referenced correctly in agent/command
3. File permissions are correct

Command Fails

1. Check command syntax in .md file
2. Verify all required inputs are provided
3. Review error logs in .opencode/ directory

Contributing

Adding New Agents

1. Create agent file in appropriate subdirectory
2. Follow naming convention: kebab-case.md
3. Include comprehensive documentation
4. Test with multiple scenarios

Adding New Skills

1. Use skill-creator skill as template
2. Include SKILL.md with clear documentation
3. Add reference materials and examples
4. Test with multiple agents

Submitting Changes

1. Fork the repository
2. Create feature branch
3. Make changes with clear commits
4. Submit pull request with description

Model Context Protocol (MCP)

What is MCP?

Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to large language models (LLMs). It enables AI applications to connect with various data sources and tools in a consistent, structured manner.

MCP Architecture

MCP follows a client-server architecture:

• MCP Hosts: Applications like AI assistants or IDEs (e.g., OpenCode CLI)
• MCP Clients: Connectors within the host that maintain 1:1 connections with servers
• MCP Servers: Services that provide context, tools, and capabilities through the standardized protocol

Available MCP Integrations

OpenCode CLI supports various MCP servers that extend AI capabilities:

1. Context7 MCP (mcp_context7)

Purpose: Up-to-date library documentation and code examples

Tools:

• resolve-library-id: Find Context7-compatible library IDs (e.g., /mongodb/docs, /vercel/next.js)
• query-docs: Query documentation with specific questions

Use Cases:

• Getting latest API documentation
• Finding code examples for libraries
• Learning framework-specific patterns
• Checking version-specific features

Example:

# First resolve library ID
resolve-library-id libraryName="next.js" query="Next.js documentation"

# Then query specific docs
query-docs libraryId="/vercel/next.js" query="How to use App Router in Next.js 15"

2. Exa Web Search MCP (mcp_exa)

Purpose: Advanced web search and research capabilities

Tools:

• exa: General web search with clean, LLM-ready content
• company_research_exa: Research companies and business information
• crawling_exa: Extract content from specific URLs
• get_code_context_exa: Find code examples and documentation
• deep_researcher_start: Start AI research agent for complex topics
• deep_researcher_check: Check research task status and results

Use Cases:

• Finding current information and news
• Researching companies and technologies
• Extracting content from web pages
• Finding code examples from GitHub/Stack Overflow
• Deep research on complex topics

Example:

# Web search
exa query="Next.js 15 new features" numResults=5

# Code search
get_code_context_exa query="React Server Components examples" tokensNum=5000

# Deep research
deep_researcher_start instructions="Research best practices for microservices architecture"

3. Next.js DevTools MCP (mcp_next_devtools)

Purpose: Next.js development server integration and diagnostics

Tools:

• init: Initialize Next.js DevTools context
• nextjs_docs: Fetch official Next.js documentation
• nextjs_index: Discover running Next.js dev servers and available tools
• nextjs_call: Call specific MCP tools on running dev server
• browser_eval: Browser automation for testing
• upgrade_nextjs_16: Guide for upgrading to Next.js 16
• enable_cache_components: Migrate to Cache Components mode

Use Cases:

• Real-time Next.js error diagnostics
• Querying running dev server state
• Browser-based page verification
• Next.js version upgrades
• Cache Components migration

Example:

# Initialize
init project_path="."

# Get errors from running dev server
nextjs_index
nextjs_call port="3000" toolName="get_errors"

# Query Next.js docs
nextjs_docs path="/docs/app/api-reference/functions/refresh"

Configuring MCP Servers

MCP servers are configured in .kiro/settings/mcp.json (workspace-level) or ~/.kiro/settings/mcp.json (user-level):

{
  "mcpServers": {
    "context7": {
      "command": "uvx",
      "args": ["context7-mcp-server@latest"],
      "disabled": false,
      "autoApprove": ["resolve-library-id", "query-docs"]
    },
    "exa": {
      "command": "uvx",
      "args": ["exa-mcp-server@latest"],
      "env": {
        "EXA_API_KEY": "your-api-key-here"
      },
      "disabled": false
    }
  }
}

MCP Best Practices

1. Always call resolve-library-id before query-docs (Context7)
2. Limit MCP calls to 3 per question to avoid excessive API usage
3. Use specific queries - "How to set up JWT auth in Express" not just "auth"
4. Check dev server status before calling Next.js MCP tools
5. Use browser automation for real page verification (not curl)

Installing MCP Servers

Most MCP servers use uvx (Python package runner):

# Install uv (Python package manager)
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Once installed, uvx will auto-download MCP servers on first use

Troubleshooting MCP

Server not connecting:

• Check MCP config file syntax
• Verify uvx is installed
• Check server logs in OpenCode output

Tools not available:

• Restart OpenCode after config changes
• Check disabled: false in config
• Verify API keys for services that require them

Performance issues:

• Limit concurrent MCP calls
• Use specific queries to reduce response size
• Consider caching frequently accessed data

Resources

• OpenCode Documentation: [Official Docs]
• MCP Official Site: https://modelcontextprotocol.io
• Agent Examples: See agent/ directory
• Skill Examples: See skill/ directory
• Command Examples: See command/ directory

License

See individual skill/component licenses in their respective directories.

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation in docs/ directories
• Review skill-specific README files
• Visit MCP documentation for protocol-specific questions

---

Note: This template is designed to be customized for your specific needs. Feel free to add, remove, or modify agents, commands, and skills based on your workflow.