Required Fields in the Codex Plugin Manifest: Complete Schema Reference

The Codex plugin manifest requires nine top-level metadata fields—including name, version, description, author, homepage, repository, license, keywords, and skills—plus an interface object containing fifteen UI-specific fields such as displayName, category, capabilities, and brandColor to render correctly in the marketplace.

The Codex plugin manifest defines how your extension integrates with the Codex ecosystem. In the no-ai-slop repository by petergyang, the file .codex-plugin/plugin.json demonstrates the exact schema required for plugin validation and marketplace display, ensuring all required fields in the Codex plugin manifest are properly implemented.

Top-Level General Fields

These nine fields describe the plugin package, authorship, and discovery metadata. According to the source code in no-ai-slop, Codex expects these as direct properties of the manifest root object.

Core Identity

• name — The unique identifier of the plugin (e.g., "no-ai-slop").
• version — Semantic version string (e.g., "1.0.0").
• description — Short textual summary shown in plugin listings and search results.

Authorship and Legal

• author — Object containing name (required string) and optional url linking to the creator's profile.
• homepage — URL to the plugin's landing page or primary documentation.
• repository — Direct link to the source code repository (e.g., GitHub URL).
• license — SPDX-compatible license identifier (e.g., "MIT", "Apache-2.0").

Discovery and Structure

• keywords — Array of searchable tags used for plugin discovery (e.g., ["productivity", "editing"]).
• skills — Relative path string to the directory containing the plugin's skill definitions (e.g., "./skills").

Interface Configuration Fields

The interface object defines how Codex displays your plugin in the UI, handles legal compliance, and routes user requests. All fifteen sub-fields are required for marketplace submission.

Display and Branding

• displayName — Human-readable name shown in the Composer UI and plugin catalog.
• shortDescription — Concise tagline (typically one sentence) displayed in grid views.
• longDescription — Full markdown-enabled description explaining features and usage.
• brandColor — Hex color code (e.g., "#FF5733") used for UI borders and badges.
• composerIcon — Relative path to the icon displayed in the Composer interface (e.g., "assets/icon.png").
• logo — Relative path to the full-resolution plugin logo.

Compliance and Capabilities

• developerName — Name of the individual developer or organization responsible for the plugin.
• category — Broad functional classification (e.g., "Productivity", "Developer Tools").
• capabilities — Array of supported operation strings such as "Edit", "Detect", or "Preserve voice".
• websiteURL — Link to the developer's official website or product page.
• privacyPolicyURL — Direct URL to the privacy policy document.
• termsOfServiceURL — Direct URL to the terms of service agreement.
• defaultPrompt — Example prompt string illustrating how users should invoke the plugin.

Working with the Manifest in Code

The no-ai-slop repository includes build scripts and documentation referencing these fields. The manifest validation logic in scripts/build_plugin.py checks for presence of all required keys before packaging.

Loading and Inspecting the Manifest

This Node.js snippet demonstrates reading the manifest and accessing nested interface properties:

const fs = require('fs');
const path = require('path');

const manifestPath = path.join(__dirname, '.codex-plugin', 'plugin.json');
const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));

console.log(`Plugin "${manifest.name}" v${manifest.version}`);
console.log(`Category: ${manifest.interface.category}`);
console.log(`Capabilities: ${manifest.interface.capabilities.join(', ')}`);

Rendering UI Components

React applications can import the manifest directly to generate consistent branding:

import manifest from '../.codex-plugin/plugin.json';
import ComposerIcon from manifest.interface.composerIcon;

function PluginCard() {
  return (
    <div style={{ border: `2px solid ${manifest.interface.brandColor}` }}>
      <img src={ComposerIcon} alt={manifest.interface.displayName} />
      <h2>{manifest.interface.displayName}</h2>
      <p>{manifest.interface.shortDescription}</p>
      <a href={manifest.interface.websiteURL}>Learn more</a>
    </div>
  );
}

Pre-Submission Validation

Use this Python script to verify all required fields in the Codex plugin manifest before publishing, as implemented in the repository's build process:

import json, sys, pathlib

required = [
    "name", "version", "description", "author", "homepage",
    "repository", "license", "keywords", "skills", "interface"
]
interface_required = [
    "displayName", "shortDescription", "longDescription",
    "developerName", "category", "capabilities", "websiteURL",
    "privacyPolicyURL", "termsOfServiceURL", "defaultPrompt",
    "brandColor", "composerIcon", "logo"
]

manifest_path = pathlib.Path('.codex-plugin/plugin.json')
manifest = json.loads(manifest_path.read_text())

missing = [k for k in required if k not in manifest]
missing += [f"interface.{k}" for k in interface_required if k not in manifest["interface"]]

if missing:
    sys.exit(f"Missing required fields: {', '.join(missing)}")
print("All required fields present.")

Summary

• The Codex plugin manifest requires nine top-level fields covering identity, authorship, and code location, plus a comprehensive interface object with fifteen display and compliance fields.
• Validation scripts like those in scripts/build_plugin.py enforce the presence of privacyPolicyURL, termsOfServiceURL, and capabilities before marketplace submission.
• Asset paths such as composerIcon and logo must be relative to the repository root, allowing Codex to resolve files like assets/no-ai-slop.png correctly.
• The complete schema is demonstrated in .codex-plugin/plugin.json within the no-ai-slop repository, serving as the authoritative reference for plugin developers.

Frequently Asked Questions

What is the difference between description and interface.shortDescription?

The top-level description field provides a technical summary for developers browsing repository listings, while interface.shortDescription is the marketing tagline displayed in the Codex marketplace UI. The interface version should be punchy and user-focused, whereas the top-level version can be more technical or detailed.

Are author.url and all interface sub-fields strictly mandatory?

While author requires a name property, the url sub-field is optional. However, all fields listed within the interface object—including privacyPolicyURL, termsOfServiceURL, and brandColor—are strictly required for marketplace acceptance. Omitting any interface field causes validation failures in the submission pipeline referenced in plugin-submission.md.

How should I reference external assets like icons in the manifest?

Store assets in a dedicated directory such as assets/ and reference them using relative paths from the repository root. For example, "composerIcon": "assets/no-ai-slop.png" allows Codex to locate the file correctly during plugin packaging. The build process in scripts/build_plugin.py verifies these paths exist before generating the final distribution.

What license identifiers does the Codex manifest accept?

The license field accepts SPDX-compatible identifiers such as "MIT", "Apache-2.0", "GPL-3.0", or "BSD-3-Clause". Using non-standard strings or full license text instead of SPDX short codes will trigger validation warnings when submitting to the Codex marketplace.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}