template-skill

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

Prerequisites

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

Installation

1. Install OpenCode CLI (if not already installed)

1. Clone this template:

```bash

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

cd opencode-template

```

1. Setup Environment Variables (IMPORTANT):

Windows (PowerShell as Administrator):

```powershell

cd scripts

.\setup-env-windows.ps1

```

macOS/Linux:

```bash

cd scripts

bash setup-env-mac.sh

source ~/.zshrc # or ~/.bashrc

```

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

1. Initialize your project:

```bash

opencode init

```

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

Required Environment Variables

The setup scripts configure these essential variables:

```bash

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:

```bash

opencode

```

Invoke an agent:

```bash

opencode agent

```

Run a command:

```bash

opencode command

```

```

.

├── 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

```

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

opencode.json

Main configuration file for OpenCode:

```json

{

"version": "1.0",

"agents": {

"directory": "agent"

},

"commands": {

"directory": "command"

},

"skills": {

"directory": "skill"

},

"plugins": {

"directory": "plugin"

}

}

```

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:

```markdown

# Agent Name

Brief description of what this agent does

• Capability 1
• Capability 2

• skill-name-1
• skill-name-2

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:

```bash

opencode skill create

```

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:

```json

{

"name": "Category Name",

"description": "Category description",

"icon": "icon-name"

}

```

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

Starting a New Project

```bash

# 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 Wo