YAML Schema Reference

Complete reference for all fields in Awesome OpenCode YAML entries

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:

Plugin

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