OpenCode CLI Plugins, Skills, and Agents: The Complete Extensibility Guide

Mar 6, 2026

I kept typing the same code review prompt every day. “Check for security issues, look for performance problems, verify error handling…” Twenty minutes of my life, gone, every single time I needed a review.

Then I discovered OpenCode CLI’s extensibility system. Three hours later, I had a code-review skill that did the same work in seconds. That’s when I realized: a good AI coding tool should adapt to your workflow, not force you to adapt to it.

OpenCode CLI’s three-tier extensibility system—skills, agents, and plugins—transforms a generic AI assistant into a specialized development tool. Let me show you how each tier works and when to use which.

The Three Tiers: Skills, Agents, and Plugins

Here’s the mental model:

┌─────────────────────────────────────────────┐
│              PLUGINS (Heavy)                │
│   npm packages, full tool integrations      │
│   Database connectors, API clients          │
├─────────────────────────────────────────────┤
│              AGENTS (Medium)                │
│   Specialized AI personas, focused tasks    │
│   Security reviewer, architect, TDD guide   │
├─────────────────────────────────────────────┤
│              SKILLS (Light)                 │
│   Reusable prompt templates, quick wins     │
│   Code review, commit messages, docs        │
└─────────────────────────────────────────────┘

Skills are prompt templates stored as markdown files. You create them for repetitive prompt patterns—code reviews, commit messages, documentation generators. They’re lightweight, easy to share, and perfect for standardizing workflows across a team.

Agents are specialized AI personas with focused instruction sets. An agent maintains context across a conversation and has specific tool permissions. Use agents when you need consistent, specialized behavior—a security reviewer that always checks OWASP Top 10, or an architect that focuses on scalability.

Plugins are full npm packages that integrate external tools. When you need to connect OpenCode to your database, deploy to your infrastructure, or add custom CLI commands, you build a plugin. This requires TypeScript/JavaScript development but gives you complete control.

Creating Your First Skill

I started with a simple problem: I wanted consistent code reviews without re-typing the same instructions every time.

Step 1: Create the Skill File

OpenCode looks for skills in ~/.opencode/skills/. I created a file called code-review.md:

---
name: code-review
description: Perform comprehensive code review with security and performance focus
tags:
  - review
  - security
  - performance
---

You are conducting a thorough code review. Analyze the provided code for:

## Security Issues
- Authentication and authorization flaws
- Input validation gaps
- SQL injection / XSS vulnerabilities
- Secret exposure (API keys, passwords)

## Performance Concerns
- N+1 queries
- Unnecessary re-renders
- Memory leaks
- Inefficient algorithms

## Code Quality
- Naming conventions
- Function complexity (max 50 lines)
- DRY violations
- Missing error handling

Provide actionable feedback with:
1. Severity level (CRITICAL, HIGH, MEDIUM, LOW)
2. Specific line references
3. Code examples showing the fix

Format output as a structured review with clear sections.

The YAML frontmatter between --- markers is required. The name field must match the filename (without .md). Everything after the frontmatter becomes the prompt template.

Step 2: Use the Skill

# Apply skill to a file
opencode run --skill code-review src/auth/login.ts

# Apply skill to recent changes
git diff HEAD~1 | opencode run --skill code-review

The first command feeds login.ts into the skill. The second pipes git diff output—perfect for reviewing pull requests.

Adding Parameters to Skills

A static skill works, but what if I want to customize the review focus? I needed parameters.

---
name: generate-api
description: Generate REST API endpoint with validation
parameters:
  - name: resource
    description: Resource name (e.g., users, products)
    required: true
  - name: methods
    description: HTTP methods to implement
    default: "GET, POST, PUT, DELETE"
---

Generate a complete REST API for the {{resource}} resource with:

## Endpoints
{{#each methods}}
- {{this}}: /api/{{resource}}
{{/each}}

## Requirements
- Zod validation schemas
- Error handling middleware
- Request/response TypeScript types
- OpenAPI documentation comments

Include:
- Route handler
- Validation middleware
- Service layer
- Repository pattern interface

Use TypeScript with Express.js patterns.

Now I can invoke it with:

opencode run --skill generate-api --param resource=products --param methods="GET,POST"

The templating uses Handlebars syntax. Parameters with required: true cause an error if you forget to provide them.

Skill Inheritance: Composing Multiple Skills

After building separate skills for code review, security audit, and performance checks, I wanted to run all three at once. OpenCode supports skill inheritance:

---
name: full-review
description: Comprehensive review combining multiple analysis types
extends:
  - code-review
  - security-review
  - performance-review
---

Perform a comprehensive review that includes all checks from:
- Code quality and style
- Security vulnerabilities
- Performance bottlenecks

Synthesize findings into a single prioritized report.

When you run opencode run --skill full-review, it loads all three parent skills and combines their prompts.

Configuring Specialized Agents

Skills are great for one-shot prompts. But I needed something that maintains context across multiple interactions—a security reviewer that doesn’t forget it’s supposed to check for OWASP vulnerabilities.

Creating an Agent

Agents live in ~/.opencode/agents/. Here’s my security-reviewer.json:

{
  "name": "security-reviewer",
  "description": "Specialized agent for security analysis and vulnerability detection",
  "model": "anthropic/claude-sonnet-4-5",
  "systemPrompt": "You are a security-focused code reviewer with expertise in:\n\n- OWASP Top 10 vulnerabilities\n- Authentication and authorization patterns\n- Cryptographic best practices\n- Secure coding standards (CWE, CERT)\n- Threat modeling (STRIDE)\n\nWhen reviewing code:\n1. Identify security vulnerabilities with severity ratings\n2. Provide exploit scenarios for critical issues\n3. Suggest specific mitigations with code examples\n4. Reference relevant CWE/CVE identifiers\n\nAlways prioritize:\n- Authentication/authorization flaws\n- Input validation issues\n- Secret management problems\n- Injection vulnerabilities\n\nBe thorough but practical. Focus on actionable remediation.",
  "tools": [
    "read",
    "grep",
    "glob"
  ],
  "temperature": 0.3,
  "maxTokens": 8000
}

The key fields:

model: Which AI model to use. I use claude-sonnet-4-5 for balanced performance. Opus for complex architecture, Haiku for lightweight tasks.
systemPrompt: The agent’s “personality.” This gets prepended to every conversation.
tools: What tools the agent can use. read, grep, glob let it explore codebases. I didn’t give it write or bash—security reviewers shouldn’t modify files.
temperature: Lower values (0.2-0.3) make output more deterministic, which is what you want for security analysis. Higher values (0.5+) for creative tasks like architecture design.

Using the Agent

# Invoke agent for security review
opencode agent security-reviewer "Review authentication flow in src/auth/"

# Use agent with specific file
opencode agent security-reviewer --file src/api/payment.ts

# Combine agent with skill
opencode agent security-reviewer --skill security-audit src/

The agent maintains context. If you ask a follow-up question, it remembers the previous conversation and its role as a security reviewer.

Building Multiple Specialized Agents

I created three agents for different stages of development:

Architect Agent (~/.opencode/agents/architect.json):

{
  "name": "architect",
  "description": "System design and architecture planning agent",
  "model": "anthropic/claude-opus-4-5",
  "systemPrompt": "You are a senior software architect specializing in:\n\n- Distributed systems design\n- Microservices architecture\n- Database schema design\n- API design patterns\n- Scalability and performance\n\nProvide:\n1. Architecture decision records (ADRs)\n2. System diagrams using Mermaid\n3. Trade-off analysis\n4. Migration strategies\n5. Cost-benefit considerations\n\nFocus on:\n- Separation of concerns\n- Single responsibility\n- Dependency inversion\n- Interface segregation\n\nAlways consider:\n- Scalability implications\n- Maintenance burden\n- Team velocity impact",
  "tools": [
    "read",
    "write",
    "glob",
    "grep"
  ],
  "temperature": 0.5
}

TDD Guide Agent (~/.opencode/agents/tdd-guide.json):

{
  "name": "tdd-guide",
  "description": "Test-driven development workflow guide",
  "model": "anthropic/claude-sonnet-4-5",
  "systemPrompt": "You are a TDD practitioner following Kent Beck's principles:\n\n## Red-Green-Refactor Cycle\n1. RED: Write failing test first\n2. GREEN: Write minimal code to pass\n3. REFACTOR: Improve while keeping tests green\n\n## Workflow Rules\n- Never write production code without a failing test\n- Write the simplest code that makes the test pass\n- Refactor only when tests are green\n- Commit after each cycle\n\n## Test Quality\n- 80%+ coverage required\n- Unit tests for isolated logic\n- Integration tests for workflows\n- E2E tests for critical paths\n\n## Tools\n- Jest/Vitest for unit tests\n- Testing Library for components\n- Playwright for E2E\n\nGuide the user through each step, explaining the reasoning.",
  "tools": [
    "read",
    "write",
    "edit",
    "bash"
  ],
  "temperature": 0.2
}

Notice the different model selections: Opus for architecture (needs deep reasoning), Sonnet for TDD (balanced coding). Notice the different temperature values: 0.5 for architecture (creative solutions), 0.2 for TDD (strict adherence to methodology).

Agent Workflows: Sequential and Parallel

Here’s where agents shine. I can chain them together for complex workflows:

Sequential Workflow

# Design, implement, then audit
opencode agent architect "Design payment system" \
  && opencode agent tdd-guide "Implement with tests" \
  && opencode agent security-reviewer "Audit implementation"

Each agent hands off to the next. The architect creates the design, TDD guide implements it, security reviewer audits the result.

Parallel Workflow

# Analyze different aspects simultaneously
opencode run "Analyze this codebase" \
  --agent security-reviewer:security \
  --agent architect:architecture \
  --agent tdd-guide:test-coverage

The :suffix notation creates separate conversation threads. Each agent analyzes the codebase from its specialized perspective, and you get three reports in the time it would take to run one.

Plugin Development: When Skills and Agents Aren’t Enough

Skills and agents operate within OpenCode’s existing capabilities. When you need to connect to external systems—databases, deployment pipelines, third-party APIs—you build a plugin.

Plugin Structure

opencode-plugin-database/
  package.json
  src/
    index.ts          # Plugin entry point
    commands/         # Custom CLI commands
      query.ts
      migrate.ts
    tools/            # Tool integrations
      database-client.ts
    hooks/            # Lifecycle hooks
      validate-query.ts
  README.md
  LICENSE

Plugin Package.json

{
  "name": "opencode-plugin-database",
  "version": "1.0.0",
  "description": "Database integration plugin for OpenCode CLI",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "opencode": {
    "commands": ["db:query", "db:migrate", "db:seed"],
    "tools": ["database-client"],
    "hooks": {
      "preToolUse": "validateQuery",
      "postToolUse": "logQuery"
    }
  },
  "peerDependencies": {
    "opencode": "^2.0.0"
  },
  "keywords": ["opencode", "plugin", "database", "postgresql"]
}

The opencode field tells OpenCode what commands, tools, and hooks the plugin provides.

Using Plugin Commands

# Use plugin command
opencode db:query "SELECT * FROM users WHERE active = true"

# Plugin tool in conversation
opencode run "Analyze user activity patterns" --tool database-client

# Plugin with skill combination
opencode run --skill api-generator --plugin database-plugin

Plugins require more upfront work than skills, but they unlock integration with your entire infrastructure.

Common Mistakes I Made

Mistake 1: Overloading Skills with Context

My first code-review skill had 50 lines of instructions covering every possible issue. The result? The AI got overwhelmed and produced generic, unfocused reviews.

Fix: Keep skills focused. One skill for security, another for performance, another for code style. Use skill inheritance to combine them when needed.

Mistake 2: Hardcoding Values Instead of Parameters

I created separate skills for generating user APIs, product APIs, and order APIs. Same prompt, different resource name.

Fix: Use parameters. One generate-api skill with a resource parameter replaces three separate skills.

Mistake 3: Giving Agents Too Many Tools

My first security-reviewer agent had access to write and bash. During a review, it decided to “fix” the vulnerabilities it found—deleting code and running commands without asking.

Fix: Grant minimal tool access. Security reviewers don’t need write. TDD guides need bash to run tests. Match tool access to the agent’s purpose.

Mistake 4: Wrong Temperature Settings

I set my TDD-guide agent’s temperature to 0.7 because I wanted “creative” test ideas. The result: it suggested tests that didn’t match the requirements.

Fix: Lower temperature (0.2-0.3) for tasks requiring adherence to methodology. Higher temperature (0.5+) for tasks requiring creative solutions like architecture design.

Troubleshooting Guide

Skill Not Loading

Symptoms: opencode run --skill my-skill returns “skill not found”

Checks:

File location: Must be in ~/.opencode/skills/
Filename match: If file is my-skill.md, the name field must be my-skill
File format: YAML frontmatter must be between --- markers

Agent Producing Unexpected Output

Symptoms: Security reviewer is suggesting code improvements instead of finding vulnerabilities

Checks:

System prompt: Is it focused enough?
Temperature: Is it too high? (Lower to 0.2-0.3 for focused tasks)
Model: Are you using the right model for the task?

Plugin Permission Errors

Symptoms: Plugin commands fail with “permission denied”

Checks:

Plugin is installed: npm list -g opencode-plugin-name
Plugin is enabled: Check ~/.opencode/config.json
Tool permissions: Some tools require explicit approval in settings

When to Use Each Tier

Scenario	Solution	Why
Standardize code review prompts	Skill	Lightweight, easy to share across team
Consistent security analysis	Agent	Maintains context, enforces OWASP focus
Connect to PostgreSQL database	Plugin	Requires external tool integration
Generate commit messages	Skill	Simple prompt template suffices
TDD workflow enforcement	Agent	Needs persistent context and methodology adherence
Deploy to Kubernetes	Plugin	Requires external CLI commands and API calls
Combine multiple review types	Skill inheritance	Compose existing focused skills

The Workflow I Use Now

My typical development flow combines all three tiers:

Start with the architect agent for design decisions
Use the TDD-guide agent for implementation
Run the full-review skill before committing
Deploy with a plugin that handles Kubernetes

What used to take hours of context-switching now happens in a unified workflow. The AI adapts to my needs, not the other way around.

Start simple: create one skill for your most repetitive prompt. Then add an agent for a specialized workflow. As your needs grow, explore plugins for deep integrations. The open-source foundation means you can audit every component and share your creations with the community.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

OpenCode CLI Plugins, Skills, and Agents: The Complete Extensibility Guide

The Three Tiers: Skills, Agents, and Plugins

Creating Your First Skill

Step 1: Create the Skill File

Step 2: Use the Skill

Adding Parameters to Skills

Skill Inheritance: Composing Multiple Skills

Configuring Specialized Agents

Creating an Agent

Using the Agent

Building Multiple Specialized Agents

Agent Workflows: Sequential and Parallel

Sequential Workflow

Parallel Workflow

Plugin Development: When Skills and Agents Aren’t Enough

Plugin Structure

Plugin Package.json

Using Plugin Commands

Common Mistakes I Made

Mistake 1: Overloading Skills with Context

Mistake 2: Hardcoding Values Instead of Parameters

Mistake 3: Giving Agents Too Many Tools

Mistake 4: Wrong Temperature Settings

Troubleshooting Guide

Skill Not Loading

Agent Producing Unexpected Output

Plugin Permission Errors

When to Use Each Tier

The Workflow I Use Now

Final Words + More Resources

Comments