Creating Custom Registries

Relevant source files

The following files were used as context for generating this wiki page:

• packages/cli/src/commands/init.ts
• packages/cli/src/lib/build-registry.ts
• examples/registry-starter/README.md
• examples/registry-starter/AGENTS.md
• CONTRIBUTING.md
• packages/cli/tests/build.test.ts

OCX registries are collections of reusable AI components—including skills, plugins, agents, and bundles—that extend the OpenCode environment. Following a "copy-and-own" philosophy, components in a registry are designed to be copied directly into a user's project, providing full ownership and local auditability of the code.

Creating a custom registry allows organizations or individuals to distribute specialized AI behaviors and tools. The process involves scaffolding a registry project, defining components in a manifest, organizing source files, and building the project into a versioned distribution format that can be hosted on platforms like Cloudflare Workers, Vercel, or Netlify.
Sources: examples/registry-starter/AGENTS.md:5-10, CONTRIBUTING.md:7-10

Registry Architecture and Structure

A registry consists of a source directory containing a mandatory manifest and a structured files/ directory. The OCX CLI processes these sources to generate a dist/ folder containing the registry index and individual component JSON files.

Directory Layout

The standard structure for an OCX registry project is as follows:

my-registry/
├── registry.jsonc         # Required: Metadata and component definitions
├── files/                 # Component source files
│   ├── skill/             # AI behavior instructions (Markdown)
│   ├── plugin/            # TypeScript extensions
│   ├── agent/             # Role definitions (Markdown)
│   └── bundle/            # Collections (JSON)
├── dist/                  # Built output (generated)
│   ├── index.json         # Main registry index
│   └── .well-known/
│       └── ocx.json       # Discovery endpoint
└── wrangler.jsonc         # Optional: Deployment configuration

Sources: examples/registry-starter/AGENTS.md:104-121, CONTRIBUTING.md:13-20

The Registry Manifest (registry.jsonc)

The registry.jsonc file serves as the source of truth for the registry. It defines the namespace, versioning, and the list of components available for installation.

Field	Type	Description
name	String	Human-readable name of the registry.
namespace	String	Unique identifier used for CLI references (e.g., ocx add namespace/component).
version	String	Semver-compliant version string.
components	Array	List of component objects defining metadata and file mappings.
Sources: examples/registry-starter/AGENTS.md:123-143, CONTRIBUTING.md:24-49

Scaffolding a New Registry

The OCX CLI provides an init command specifically for creating new registries. This scaffolds a project from a template, replacing placeholders with custom values.

The Initialization Flow

The runInitRegistry function handles the scaffolding process, including namespace validation and template extraction.

The CLI replaces placeholders like my-registry and Your Name across files such as registry.jsonc, package.json, and README.md.
Sources: packages/cli/src/commands/init.ts:145-207, packages/cli/src/commands/init.ts:275-300

Building the Registry

The build process transforms the developer-friendly source structure into a machine-readable distribution format. This is performed using the ocx build command, which internally calls the buildRegistry library function.

Build Logic and Data Transformation

The build process performs several key steps:

1. Manifest Validation: Parses registry.jsonc (preferring it over registry.json) and validates it against a Zod schema.
2. Packument Generation: For each component, it creates a "packument" JSON file in dist/components/ that includes versioning and metadata.
3. File Copying: Copies source files from the files/ directory into component-specific subdirectories in the output path.
4. Registry Indexing: Generates a top-level index.json containing the registry metadata and a summary of all components.
5. Discovery Setup: Creates a .well-known/ocx.json file pointing to the registry index, enabling client-side discovery.

Component Types and Requirements

Registries support four primary component types, each with specific purposes and file formats.

Type	Purpose	Standard File Format
ocx:skill	Instructions for AI behavior.	SKILL.md
ocx:plugin	Code extensions for OpenCode.	.ts (TypeScript)
ocx:agent	Specialized AI role definitions.	.md (Markdown)
ocx:bundle	Collections of other components.	JSON manifest
Sources: examples/registry-starter/AGENTS.md:147-154, CONTRIBUTING.md:21-23

Dependency Resolution

Components can declare dependencies on other components. Bare names (e.g., "my-other-skill") refer to components within the same registry, while qualified names (e.g., "kdco/background-agents") refer to external registries. The build process enforces that bare dependencies must exist within the local registry.
Sources: examples/registry-starter/AGENTS.md:316-330, packages/cli/tests/build.test.ts:133-157

Deployment and Distribution

Once built, the contents of the dist/ directory are hosted as static assets. The OCX ecosystem supports multiple deployment targets via pre-configured templates.

• Cloudflare Workers: Uses wrangler to serve the registry files.
• Vercel: Configured via vercel.json to serve the output directory.
• Netlify: Configured via netlify.toml for static site hosting.

The registry becomes usable by adding its URL via the CLI: ocx registry add <url> --name <alias>.
Sources: examples/registry-starter/README.md:12-25, examples/registry-starter/AGENTS.md:334-358

Summary

Creating a custom registry in OCX involves a structured workflow of scaffolding, manifest definition, and building. By utilizing the ocx init --registry and ocx build commands, developers can produce auditable, version-pinned component collections. This architecture ensures that AI extensions are easily distributable while remaining fully owned by the end-user upon installation.