Skip to main content
This page documents all available fields for YAML entries in the Awesome OpenCode list.

​
Required Fields

All entries must include these four fields:
​
name
string
required
Display name of the project or tool.
  • Use title case (e.g., “My Plugin Name”)
  • Be descriptive and specific
  • Avoid marketing buzzwords
Example:
name: Security Review Agent
​
repo
string (URI)
required
URL to the repository.
  • Must be a valid HTTPS URL
  • Typically a GitHub repository
  • Must be publicly accessible
Example:
repo: https://github.com/example/opencode-security-agent
​
tagline
string
required
Short punchy summary shown in collapsed view.
  • Maximum 120 characters
  • Clearly explain what the project does
  • Avoid redundant category names
Example:
tagline: AI agent specialized in security code review
​
description
string
required
Full description of the project shown when expanded.
  • Can be multiple lines
  • Explain what it does and why it’s useful
  • Highlight key features and use cases
  • Use proper markdown formatting
Example:
description: A custom agent configuration for security-focused code review.
  Includes
  - Custom system prompts for security analysis
  - Predefined tools for vulnerability scanning
  - Skills for OWASP Top 10 detection

​
Optional Fields

​
scope
array
default:"[global]"
Installation scope indicating where the extension can be installed.
  • global - System-wide installation (~/.config/opencode/)
  • project - Project-specific installation (.opencode/)
  • Defaults to [global] if omitted
  • Can specify both if applicable
  • Must include at least one value if specified
Examples:
# Plugin that works in both locations
scope:
  - global
  - project

# Theme that's typically global-only
scope:
  - global
​
tags
array of strings
Tags for filtering and discoverability.
  • Use lowercase with hyphens for multi-word tags
  • Be specific and relevant
  • Include technology names if applicable
  • Avoid overly generic tags
Example:
tags:
  - security
  - code-review
  - owasp
  - agent
​
min_version
string (semver)
Minimum OpenCode version required.
  • Must follow semantic versioning format: major.minor.patch
  • Pattern: ^[0-9]+\.[0-9]+\.[0-9]+
Example:
min_version: "1.0.0"
Always use quotes around version numbers to ensure YAML parses them as strings, not numbers.
​
homepage
string (URI)
Documentation URL if different from the repository.
  • Must be a valid HTTPS URL
  • Use for dedicated documentation sites
  • Omit if docs are in the repository README
Example:
homepage: https://example.com/docs/security-agent
​
installation
string
Detailed installation instructions in markdown format.Use the multiline string format (|) for readability.Recommended sections:
  • Prerequisites
  • Installation steps
  • Configuration
  • Files modified
  • Removal/uninstallation
Example:
installation: |
  ## Prerequisites
  - OpenCode 1.0.0 or later
  - Node.js 18+
  
  ## Installation
  
  ### Global (all projects)
  npm install -g @example/mcp-server
  
  ## Configuration
  Add to your opencode.json configuration file.
  
  ## Files Modified
  - ~/.config/opencode/opencode.json
  
  ## Removal
  npm uninstall -g @example/mcp-server

​
Complete Examples

Here are complete examples for different categories: 
# data/plugins/example-plugin.yaml
name: Example Plugin
repo: https://github.com/example/opencode-example-plugin
tagline: A brief description of what this plugin does (max 120 chars)
description: A longer description explaining the plugin in detail.
  - Can be multiple lines and include
  - Feature highlights
  - Use cases
  - Key benefits

scope:
  - global
  - project

tags:
  - productivity
  - ai
  - authentication

min_version: "1.0.0"

homepage: https://example.com/docs/opencode-plugin

installation: |
  ## Prerequisites
  - OpenCode 1.0.0 or later
  - Node.js 18+ (for local development)
  
  ## Installation
  
  ### Global (all projects)
  git clone https://github.com/example/opencode-example-plugin ~/.config/opencode/plugin/example-plugin
  
  ### Project-only
  git clone https://github.com/example/opencode-example-plugin .opencode/plugin/example-plugin
  
  ## Configuration
  Add to your opencode.json configuration file.
  
  ## Removal
  1. Remove the plugin directory
  2. Remove the config entry from opencode.json

​
Validation

All entries are validated against this schema using the validation script: 
node scripts/validate.js data/category/your-file.yaml
The validator checks:
  • YAML syntax is correct
  • All required fields are present
  • Field types match the schema
  • tagline is 120 characters or less
  • URLs are valid and properly formatted
  • min_version follows semver pattern if specified
  • scope contains valid values (global or project)
Validation runs automatically on all pull requests. Ensure your entry passes validation before submitting.

​
Additional Notes

  • The schema allows additionalProperties: true, so you can include custom fields if needed
  • YAML files use the .yaml extension (not .yml)
  • File names should use kebab-case (e.g., my-plugin.yaml)
  • The README.md is auto-generated from YAML files - never edit it directly
For questions about specific fields or validation errors, see the contribution guidelines or review existing entries in the repository.