Understand directories and marketplace sources

Understand the approach

A directory is where users discover plugins; a marketplace source is a catalog that tells a supported client which packages are available. ChatGPT and Codex share a universal public directory, while local or team catalogs can provide other packages. A listing is not the same as installation, enablement, connected-service authentication, or authorization for the task you want the plugin to perform.

The desktop app provides plugin browsing and installation. In Codex CLI, /plugins opens the plugin browser, and documented marketplace commands can inspect or register sources. The IDE extension does not provide plugin support. A repository catalog can live at .agents/plugins/marketplace.json, with entries pointing to package folders. source.path resolves relative to the marketplace root, not the catalog's nested .agents/plugins directory.

The lab now generates a complete active catalog in a new scratch root and provides a child-only native client helper. It runs the real marketplace commands with a disposable CODEX_HOME; it does not copy login data or edit the owner’s configuration. Inspect source ownership, contents, version, license and data destinations before using any remote source. Managed requirements may still restrict availability in ordinary clients.

Choose a reproducible source

For a real team rollout, record the package version and the source reference you reviewed. A moving branch can change after approval, and a display name alone is not a stable identifier. Keep the reviewed contents available for comparison with later updates. If policy blocks a source, treat that as a constraint to resolve with the owner rather than a reason to mirror or reinstall it through an unreviewed channel.

Try it step by step

1. Generate the complete marketplace; inspect .agents/plugins/marketplace.json and resolve ./plugins/workflow-review-practice from its marketplace root.
2. Run the native helper’s version, add-marketplace, marketplaces and available actions; inspect the actual native results.
3. Install and list the package in the same disposable profile, then inspect enabled/version/installedPath fields.
4. For app discovery open the generated marketplace project, refresh/restart as documented, choose the local source in Plugins Directory and use a new chat.
5. Remove the scratch plugin and source. For Git distribution inspect owner and pin a reviewed ref rather than treating a local draft as an active remote catalog.

A useful starting example

Illustration · adapt before use.

$pluginPracticeRoot = & {
  $ErrorActionPreference = 'Stop'
  $createdRoot = & node labs/workflow-plugin/create-workspace.cjs --path-only
  if ($LASTEXITCODE -ne 0 -or @($createdRoot).Count -ne 1 -or [string]::IsNullOrWhiteSpace($createdRoot)) { throw 'Plugin workspace creation failed; no native action was run.' }
  $resolvedRoot = (Resolve-Path -LiteralPath $createdRoot).Path
  if ((Split-Path $resolvedRoot -Leaf) -notlike 'codex-howto-workflow-*' -or -not (Test-Path -LiteralPath (Join-Path $resolvedRoot 'PRACTICE-WORKSPACE.json') -PathType Leaf)) { throw 'Expected generated workspace is missing.' }
  $resolvedRoot
}
node labs/workflow-plugin/native-client.cjs version $pluginPracticeRoot
if ($LASTEXITCODE -ne 0) { throw 'Native version check failed; stop here.' }

{
  "name": "workflow-review-practice",
  "source": {"source": "local", "path": "./"},
  "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
  "category": "Productivity"
}

Check your result

• The exact catalog resolves to the actual package and native discovery finds its version.
• Installation and removal are observed in the same disposable profile with no owner profile mutation.
• Local catalog, public directory, Git ref and app/CLI/IDE support are distinguished.

Common mistakes

• Copying the source's Anthropic marketplace commands into a Codex workflow.
• Treating a public listing, trusted-looking name, or installed state as proof of appropriate access and behavior.