awesome-opencode/docs/schema-design.md

OpenCode Extension Schema Design

This document describes the YAML schema for the awesome-opencode registry, a data-driven catalog of OpenCode extensions. It covers extension types, configuration locations, schema fields, and downstream compatibility.

---

1. Overview

The awesome-opencode registry is a curated collection of extensions that enhance the OpenCode editor. The registry follows a data-driven approach where YAML files in data/{category}/ directories serve as the source of truth.

Design Principles

• Human Readable: YAML format ensures contributors can easily read and edit entries
• Downstream Ready: Schema designed for seamless consumption by platforms like opencode.cafe
• Discoverable: Tags and metadata support filtering and search
• Extensible: Schema allows additional fields for future enhancements
• Type by Location: Extension type is derived from directory, not stored in YAML

Directory Structure

awesome-opencode/
├── data/
│   ├── plugins/
│   │   └── *.yaml
│   ├── themes/
│   │   └── *.yaml
│   ├── agents/
│   │   └── *.yaml       # Agent configurations and skills
│   ├── projects/
│   │   └── *.yaml
│   ├── resources/
│   │   └── *.yaml       # Guides, configs, MCP servers, tools, commands
│   └── examples/
│       └── *.yaml       # Exemplar files showing all fields
└── docs/
    └── schema-design.md

---

2. OpenCode Extension Types

Extensions in awesome-opencode fall into distinct categories, each serving a specific purpose in the OpenCode ecosystem.

2.1 Plugin (plugin)

JavaScript or TypeScript modules that extend OpenCode's core functionality. Plugins can be installed via npm or as local files.

Installation Methods:

• NPM package: npm install <plugin-name>
• Local path: Reference to local .js or .ts file

Example Use Cases:

• Authentication providers
• Custom UI components and panels
• Integration with external services

2.2 Theme (theme)

Visual themes that customize the OpenCode editor appearance. Themes are distributed as JSON files containing color schemes and styling rules.

Installation Methods:

• JSON file placed in themes directory
• Referenced from remote URL

Example Use Cases:

• Dark/light mode variations
• Syntax highlighting for specific languages
• Custom UI color schemes

2.3 Agent (agent)

Custom AI agent configurations and skills that define behavior, tools, and instructions for specialized tasks. This category includes both agent configurations and reusable skill instruction sets.

Includes:

• Agent configurations (system prompts, available tools, behavior)
• Skills (reusable instruction sets in SKILL.md format)

Example Use Cases:

• Security-focused code reviewers
• Documentation generators
• Interview question generators
• Bug reproduction assistants

2.4 Project (project)

Standalone applications, utilities, and tools built for or with OpenCode. These are complete projects rather than extensions.

Example Use Cases:

• Web interfaces for OpenCode
• Session management tools
• Proxy servers and API wrappers
• Companion applications

2.5 Resource (resource)

Guides, configurations, MCP servers, tools, and commands that enhance the OpenCode experience without being installable plugins.

Includes:

• Configuration starters and examples
• MCP servers (Model Context Protocol servers)
• CLI tools and utilities
• Custom slash commands
• How-to guides and tutorials

Example Use Cases:

• Database access MCP servers
• API integrations (GitHub, Slack, etc.)
• Project-specific build commands
• Starter configuration templates

2.6 Fork (fork)

Modified builds of OpenCode itself with custom features or patches. Forks maintain compatibility while adding functionality. They live in data/projects/ with kind: fork.

Example Use Cases:

• Custom builds with enterprise features
• Experimental feature branches
• Distribution-specific variants

---

3. OpenCode Configuration Locations

OpenCode extensions can be installed in multiple locations depending on their scope and purpose. Understanding these locations is crucial for proper installation and management.

3.1 Global Configuration (User-Wide)

Global installations apply to all projects for the current user.

Path	Purpose
~/.config/opencode/opencode.json	Main configuration file
~/.config/opencode/plugin/	Plugin modules
~/.config/opencode/themes/	Theme JSON files
~/.config/opencode/command/	Custom slash commands
~/.config/opencode/agent/	Custom agent configurations
~/.config/opencode/skill/<name>/SKILL.md	Global skills

Note: On Windows, the equivalent is %APPDATA%/opencode/.

3.2 Project-Level Configuration

Project-level installations are scoped to specific repositories.

Path	Purpose
<project>/opencode.json	Project-specific configuration
<project>/.opencode/plugin/	Project plugins
<project>/.opencode/themes/	Project themes
<project>/.opencode/command/	Project commands
<project>/.opencode/agent/	Project agents
<project>/.opencode/skill/<name>/SKILL.md	Project skills

3.3 Claude-Compatible Paths

OpenCode maintains compatibility with Claude's skill system for portability.

Path	Purpose
~/.claude/skills/<name>/SKILL.md	Global Claude skills
.claude/skills/<name>/SKILL.md	Project Claude skills

3.4 Remote and Custom Configurations

Extensions can also be fetched from remote sources or custom locations.

Path/Variable	Purpose
.well-known/opencode	Organizational defaults fetched remotely
OPENCODE_CONFIG	Environment variable pointing to custom config file
OPENCODE_CONFIG_DIR	Environment variable pointing to custom config directory

3.5 Precedence Order

When multiple configuration sources exist, OpenCode follows this precedence (later sources override earlier ones):

1. Remote config (.well-known/opencode)
2. Global config (~/.config/opencode/)
3. Custom config (OPENCODE_CONFIG env var)
4. Project config (opencode.json)
5. Project local directories (.opencode/)
6. Inline config (environment variables)

Resolution Example: If scope is set to [global, project] and both global and project configs define the same extension, the project-level configuration takes precedence for that project.

---

4. YAML Schema

data/schema.json defines the fields; scripts/utils/catalog.js adds rules that need the whole catalog (one entry per repository and path, kind must fit the category directory, compat required for plugins, no placeholder repo owners, no mis-encoded text). Unknown fields are rejected (additionalProperties: false).

Required Fields

Field	Type	Description
name	string	Display name, max 80 characters
repo	string	Repository root URL on GitHub, GitLab, Codeberg or Gitee (gists and GitHub discussions also accepted). No /tree/ or /blob/ paths, npm pages or websites
tagline	string	Short summary, max 120 characters
description	string	Full description, max 1500 characters
kind	enum	plugin, theme, agent, skill, mcp-server, client, tool, config, guide, fork
topics	array	1–3 of the fixed topic list (see data/schema.json); the first is the primary topic used for README grouping
compat	enum	Required for data/plugins/ only: v2, v1 or unknown (verified by CI). Other categories: optional, v2/v1 when they use the SDK, otherwise n/a

Optional Fields

Field	Type	Default	Description
path	string	-	Folder inside a monorepo, e.g. packages/my-plugin
npm	string	-	npm package name; used for the V2 check, health checks and the npm link
also	array	-	Secondary kinds (e.g. [mcp-server]), cross-listed on the site
scope	array	[global]	Installation scope: [global], [project], or [global, project]
tags	array	[]	Free-form search keywords (not rendered; use topics for categorization)
min_version	string	-	Minimum OpenCode version required (semver, e.g., "2.0.0")
homepage	string	-	Documentation URL if different from repository
installation	string	-	Detailed installation instructions (markdown format)

Kind per Category

The directory is the coarse bucket (and the type downstream consumers see); kind says what the entry actually is.

Directory	Allowed kind
data/plugins/	plugin
data/themes/	theme
data/agents/	agent, skill
data/projects/	client, tool, mcp-server, skill, agent, fork
data/resources/	guide, config, mcp-server, skill, tool

Minimal Valid Entry

name: My Extension
repo: https://github.com/user/my-extension
tagline: A brief description of what this does
description: A longer explanation of the extension.
kind: plugin
topics:
  - workflow
compat: v2

Complete Entry (All Fields)

name: My Extension
repo: https://github.com/user/my-monorepo
path: packages/my-extension
npm: opencode-my-extension
homepage: https://example.com/docs
tagline: "A brief tagline: quote it when it contains a colon"
description: |
  A longer description explaining
  the extension in detail.
kind: plugin
also:
  - mcp-server
topics:
  - memory
  - context
compat: v2
scope:
  - global
  - project
tags:
  - productivity
min_version: "2.0.0"
installation: |
  Add `opencode-my-extension` to the `plugin` list in `opencode.json`.

Use npm run new to scaffold an entry and npm run fmt to rewrite entries in canonical key order with safe quoting.

Examples Directory

Full exemplar files for each extension type are available in data/examples/:

Type	Example File
Plugin	data/examples/plugin.yaml
Theme	data/examples/theme.yaml
Agent	data/examples/agent.yaml
Project	data/examples/project.yaml
Resource	data/examples/resource.yaml
Fork	data/examples/fork.yaml (forks now live in data/projects/ with kind: fork)

---

5. Installation Template

The installation field uses a structured template that contributors fill in. Not all sections are required—include what's relevant for the extension.

Template Structure

## Prerequisites
- OpenCode version requirements
- Other dependencies (Node.js, Python, CLI tools, etc.)

## Installation

### Global (all projects)
Steps for installing to ~/.config/opencode/

### Project-only
Steps for installing to .opencode/ within a project

## Configuration
Config options to add to opencode.json

## Files Modified
List of files created/modified (for backup purposes)
- ~/.config/opencode/opencode.json
- ~/.config/opencode/plugin/codegpt.js

## Removal
How to uninstall the extension

Template Guidelines

1. Prerequisites: List minimum versions and dependencies
2. Installation: Provide both global and project-specific instructions if scope includes both
3. Configuration: Show exact JSON/config snippets needed
4. Files Modified: Help users understand what will change for backup/restore
5. Removal: Include cleanup steps for uninstallation

Section Requirements by Type

Extension Type	Key Sections
plugin	Installation, Configuration
theme	Installation, Files Modified
agent	Installation, Configuration
project	Prerequisites, Installation
resource	Prerequisites, Installation, Configuration
fork	Installation, Files Modified

---

6. Downstream Compatibility

The awesome-opencode schema is designed for seamless conversion to downstream platforms like opencode.cafe.

Field Mapping

awesome-opencode YAML	opencode.cafe JSON	Notes
name	displayName	Display name for UI
repo	repoUrl	Repository URL
tagline	tagline	Short summary
description	description	Full description
(directory)	type	Derived from directory path
(filename)	productId	Derived from filename
scope	scope	Defaults to ["global"]
tags	tags	Array of strings
homepage	homepageUrl	Documentation URL
installation	installation	Markdown content
min_version	minVersion	Semver string
path	repoPath	Monorepo folder (added 2026-10)
npm	npmPackage	npm package name (added 2026-10)
kind	kind	What the entry is (added 2026-10)
also	also	Secondary kinds (added 2026-10)
topics	topics	Use-case topics (added 2026-10)
compat	compat	v2, v1, unknown or n/a; plugins default to unknown (added 2026-10)

Conversion Example

YAML Input (data/plugins/codegpt.yaml):

name: CodeGPT
repo: https://github.com/company/codegpt
tagline: AI-powered code completion
description: Intelligent code completion using GPT models.

JSON Output (opencode.cafe format):

{
  "productId": "codegpt",
  "type": "plugin",
  "displayName": "CodeGPT",
  "repoUrl": "https://github.com/company/codegpt",
  "tagline": "AI-powered code completion",
  "description": "Intelligent code completion using GPT models.",
  "scope": ["global"],
  "tags": []
}

Note: type is derived from data/plugins/ → plugin, and productId from filename codegpt.yaml → codegpt.

---

7. Future Vision

This section outlines planned features and improvements for the awesome-opencode ecosystem.

7.1 Agent-Powered Plugin Manager

A future plugin/agent that uses the installation markdown as context to assist with setup. The agent would:

• Parse the installation instructions
• Know which files will be modified (for backup purposes)
• Guide users through the installation interactively
• Handle scope selection based on user preference

This is not an automated CLI executor - it's an AI assistant with context about how to install the extension.

7.2 Interactive TUI with Scope Selection

A terminal UI that:

• Reads the scope field to present appropriate options
• Shows extension metadata and readme preview
• Handles multi-step installations interactively

┌─────────────────────────────────────────┐
│  Install Extension                      │
├─────────────────────────────────────────┤
│  Name:     CodeGPT                      │
│  Type:     plugin                       │
│  Scope:    [X] Global  [ ] Project      │
│                                         │
│  [Install]  [Cancel]  [View Readme]     │
└─────────────────────────────────────────┘

7.3 Automatic Backup and Restore

When an agent assists with installation, it can:

• Read the "Files Modified" section to know what to backup
• Store backups before making changes
• Enable clean removal with rollback capability

7.4 Contributing Workflow Improvements

Future improvements to the contribution process:

Implemented in 2026-10; see policy.md:

1. Schema Validation: the required validate check runs on every PR
2. V2 Compatibility Check: plugins are probed for @opencode/* and Plugin.define
3. Link Checking: the nightly health job tracks renamed, archived, missing and deprecated targets

---

8. Quick Reference

Extension Type to Directory Mapping

Type	Directory
plugin	data/plugins/
theme	data/themes/
agent	data/agents/
project	data/projects/
resource	data/resources/

Forks are entries in data/projects/ with kind: fork; see "Kind per Category" in section 4.

Minimal Valid Entry

name: My Extension
repo: https://github.com/user/my-extension
tagline: A brief description
description: A longer explanation of what this extension does.

Complete Entry (All Fields)

See data/examples/ directory for full exemplar files.

name: My Extension
repo: https://github.com/user/my-extension
tagline: A brief tagline (max 120 chars)
description: |
  A longer description explaining
  the extension in detail.
scope:
  - global
  - project
tags:
  - productivity
  - ai
min_version: "1.0.0"
homepage: https://example.com/docs
installation: |
  ## Installation
  ```bash
  git clone https://github.com/user/my-extension ~/.config/opencode/plugin/my-extension

### Commands

```bash
npm run validate   # schema and catalog rules for every entry
npm run generate   # regenerate README.md
npm run new -- --category plugins --repo <url> --tagline "..." --topics memory
npm run fmt        # canonical formatting for all entries

---

9. Status

The contributing guide, README enhancements (topic/kind grouping, V1/V2 badges, counts, recently added) and the JSON export described in earlier versions of this document are implemented. Catalog rules are in policy.md.

---

Document Version: 2.0 Last Updated: 2026-10-17