Install a Codex Plugin and Verify Which Skill Runs

Plugin installation becomes reviewable when package identity, selected component, and actual runtime source are visible.

Rick Hightower

Cover image for “Install a Codex Plugin and Verify Which Skill Runs” by Rick Hightower

Package the existing readiness workflow, inspect its local catalog, and invoke the installed copy by its qualified name.

An installed badge is useful, but the skill's actual source path tells you which workflow ran.

In this article: Package the existing readiness skill, register its local catalog, and inspect the installation. Select the qualified skill, verify its installed path and seven-test result, and keep hook support separately scoped.

Tested on Codex CLI 0.169.0, macOS, Node.js 22.22.1, and Git 2.47.1.

Desktop plugin controls are not run; use the labeled route for the app.

Yesterday you trusted a hook, observed its denial, verified the disposable file survived, and removed the experiment to restore a clean seven-test project.

If the previous Codex conversation is still open, enter /quit at its idle composer. Start the terminal command from your ticket-triage directory.

Start here

codex

From ticket-triage, install a local plugin, select its readiness skill, and verify its installed source and tests without changing the project.

Starting fresh or fell behind? Run git switch -C main codex/day-12. This replaces your main with the end of Day 12; to keep your own work, run git branch my-backup first.

A plugin is an installable set of capabilities. Its package directory contains components and identifying settings; a marketplace catalogs installable packages. Build a one-entry local catalog around the existing ship skill, without a new external account.

Check the starting project

If Codex asks Trust this folder?, confirm the Ticket Triage path and choose Trust and continue. Keep Ask for approval, the permission mode that asks when an action needs approval under its rules.

Enter the session-settings command:

/status

Check: Confirm that Directory identifies Ticket Triage, Agents.md lists AGENTS.md, and Permissions shows Workspace (Ask for approval). Use a normal launch without changing the model or permission mode.

From the composer, Codex's input box, run the starting check. The leading ! executes a shell command you provide:

!git status --short && npm test

git status --short lists changed or untracked files. A clean working tree prints no file entries. The && runs the next command after the Git command succeeds. npm test runs Ticket Triage's test script.

Check: Expect seven tests, seven passes, and zero failures before continuing.

Package the existing readiness skill

You will create ticket-triage-marketplace beside the project. In a relative path, .. means the parent directory, so this sibling folder stays outside Ticket Triage's tracked files. The package contains the existing skill plus a manifest, a file describing the package. A second file describes the marketplace's one entry. Both settings files use JSON, a structured data format.

Create them with this exact line:

!mkdir -p ../ticket-triage-marketplace/.agents/plugins ../ticket-triage-marketplace/plugins/triage-tools/skills/ship && cp .agents/skills/ship/SKILL.md ../ticket-triage-marketplace/plugins/triage-tools/skills/ship/SKILL.md && printf '%s\n' '{"$schema":"https://agent-plugins.org/schemas/1.0.0/plugin.schema.json","name":"triage-tools","version":"0.1.0","description":"Ticket Triage readiness workflow"}' > ../ticket-triage-marketplace/plugins/triage-tools/plugin.json && printf '%s\n' '{"name":"codex2-local","plugins":[{"name":"triage-tools","source":{"source":"local","path":"./plugins/triage-tools"},"policy":{"installation":"AVAILABLE","authentication":"ON_INSTALL"},"category":"Productivity"}]}' > ../ticket-triage-marketplace/.agents/plugins/marketplace.json

mkdir -p creates the directories and any missing parents. cp copies the tested skill file. printf writes each supplied string followed by a newline, and > sends it into the named file.

The manifest's $schema identifies its format, name identifies triage-tools, version records 0.1.0, and description describes the readiness workflow. The catalog's name is codex2-local; its plugins list points to ./plugins/triage-tools from the marketplace root. The policies mark the entry AVAILABLE for installation and select authentication ON_INSTALL when needed. category groups it under Productivity.

Inspect both files and compare the skill copies:

!cat ../ticket-triage-marketplace/plugins/triage-tools/plugin.json ../ticket-triage-marketplace/.agents/plugins/marketplace.json && cmp .agents/skills/ship/SKILL.md ../ticket-triage-marketplace/plugins/triage-tools/skills/ship/SKILL.md

cat prints the files, and cmp compares the skill contents.

Check: Expect the two JSON records and no difference report. The packaged ten-line procedure retains its no-edit, no-commit, no-push, and no-publish limits.

The catalog locates a package containing the readiness skill.

Register and inspect the catalog

Register the sibling directory as a marketplace source:

!codex plugin marketplace add ../ticket-triage-marketplace

codex plugin marketplace add registers the catalog for your Codex environment.

Check: Look for Added marketplace codex2-local and the sibling directory's resolved path.

Open the plugin browser:

/plugins

Wait for the browser to load. If it stays on Loading, press Escape and enter /plugins again. The browser tabs are All Plugins, Installed, OpenAI Curated, Workspace, codex2-local, and Add Marketplace. Use the arrow keys to select codex2-local. From All Plugins with these six tabs, Right four times selects it. Choose by the visible source name.

Find triage-tools, marked Available, and press Enter for details. Wait for the details to finish loading.

Check: Confirm Source: Local, Auth: Auth on install, Version: local 0.1.0, and Skills: triage-tools:ship. It should also show No plugin hooks and No plugin apps.

From the initially selected Back to plugins row, press Down to highlight Install plugin, then Enter.

Check: Confirm the installed state: the catalog reports Installed 1 of 1 codex2-local plugins, with triage-tools marked Installed. Confirm that no additional app authentication is required. Press Escape to close the browser.

Start a fresh chat and select the installed skill

Enter the new-conversation command:

/new

A Git worktree is a checkout directory holding your project files. When Codex asks where the conversation should run, leave Use current Git worktree selected and press Enter. Wait until the normal composer appears. The fresh chat discovers the installation in the same project.

Open the skill actions:

/skills

Select List skills with Enter. In the skill picker, type triage-tools and check for ship (triage-tools) with the readiness description. Press Enter to insert it.

Check: The composer contains $triage-tools:ship without submitting a request yet.

This is a qualified skill name: the plugin namespace, triage-tools, followed by the component name, ship. It identifies the packaged copy even though your project also has a skill named ship.

Append the request so the composer reads:

$triage-tools:ship  Check the current Ticket Triage work without changing files. Identify the exact SKILL.md path you read.

Check: Press Enter to send it. Inspect the actual reads for AGENTS.md and triage-tools:ship, the Git status and diff commands, and an actual npm test run. Check the answer for a skill path under Codex's plugin cache, its local store of installed package copies, ending in triage-tools/0.1.0/skills/ship/SKILL.md.

Expect no changed files, all seven tests passing, and Ready. This bounded review ran without an approval dialog in Workspace mode. Verify the installed source path as well as the name.

Check package identity, qualified selection, and runtime evidence.

The installed path identifies which copy supplied the workflow.

The desktop path

Not run: desktop steps. Create and inspect the same sibling package through the integrated terminal, the app's built-in shell. Run shell commands there without the CLI's initial !.

Open Plugins, select the registered local catalog, inspect triage-tools and its skill, then install it. Start a new Local chat for the same project and use the app's @ picker to select the packaged workflow.

Check: Confirm the source, authentication message, skill read, and test action. Stop this route if a required control is unavailable.

Finish with the independent check

Back in the CLI composer, run:

!git status --short && npm test

Check: Expect no changed-file entries, seven passes, and zero failures. Leave the base triage-tools plugin installed for reuse, with its catalog beside the project. No project commit is needed because today's package files live outside Ticket Triage and the review changed no tracked files.

What you proved

  • The local catalog installs the inspected skill-only package.
  • The qualified invocation reads the installed copy and returns Ready after seven tests.
  • The independent check confirms a clean, unchanged project.

You can stop here. Going deeper explains why this works and where it breaks.

Going deeper

Read this section to share skills across tools, choose a portable package layout, or assess plugin-hook support separately from skill execution.

OS-1: Know the roots and collision rules

Codex reads .agents/skills from the working directory up to the Git root, personal ~/.agents/skills, administrator /etc/codex/skills, and bundled system skills. Symlinked folders work. Duplicate names are not merged; both can appear in selectors. Locations

CLI 0.169.0 also discovered $CODEX_HOME/skills, normally ~/.codex/skills, alongside the same-named project skill with another description. Controlled .claude/skills and CLAUDE.md markers were ignored. This establishes discovery, not a universal duplicate winner.

Codex receives names, descriptions, and paths before loading a selected body. agents/openai.yaml controls interface metadata, dependencies, and policy.allow_implicit_invocation: default true permits automatic selection; false allows explicit invocation only. Permissions remain unchanged. Metadata

OS-2 and OS-3: Separate portable identity from vendor extensions

Agent Skills defines the SKILL.md workflow. Agent Plugins 1.0 defines an installable package: root plugin.json requires only $schema and name; skills/ contains workflows; optional mcp.json declares connected tools. Today's instruction-only package needs no MCP component. Its separate catalog resolves source.path from the marketplace root.

Vendor namespaces hold host-specific parts, such as Copilot's com.github.copilot/. OpenAI's inline extensions.com.openai replaces the entire .codex-plugin/plugin.json compatibility overlay; they do not merge. The fallback applies when inline settings are absent. Portable identity and components remain canonical. OpenAI overlay

The creator scaffolds compatibility layout; inspect its output before assuming portable root-manifest creation. Register a marketplace, install plugin@marketplace, and inspect its manifest. Creator output, CLI directory

Assess hooks independently

Skill execution and absent hook inventories support separate claims.

A separate CLI 0.169.0 check installed triage-hooks 0.1.0 with inline OpenAI hooks and a compatibility fallback. Both files reached the cache, but new chat and reload inventories showed zero hooks. A harmless shell call produced no marker; seven tests passed. Fallback-only 0.1.1 also showed zero hooks and no runtime marker after reload.

The cause remains unresolved: absent inventories establish neither precedence nor universal lack of hook support. The replacement rule is documentation-backed. The positive skill result remains separate. Cleanup disabled triage-hooks, restored the triage-tools-only catalog, and verified a clean seven-test project. Documented hook packaging

Keep the positive skill result separate from unresolved hook behavior.

A successful skill cannot establish that optional plugin hooks ran.

OS-4: Verify the installed workflow

A qualified name distinguishes the installed and project copies.

The same ship ran from a portable package with the project copy moved aside: seven tests passed, and Needs work identified the missing committed file. Restoring it returned clean status. Today’s qualified invocation keeps both copies and verifies the installed path with Ready.

Two Codex delivery paths ran the workflow. Cross-tool execution and optional components need separate verification. Packaging

OS-5: Compare five hosts before sharing

Sources were checked November 17, 2026. The comparison includes companion tests on Copilot CLI 1.0.112, Claude Code 2.1.325, and OpenCode 2.3.0; Pi's behavior is documentation-backed.

  • GitHub Copilot CLI: reads .github/skills, .agents/skills, and .claude/skills; first found wins. Companion 1.0.112 loaded portable packages. Reference
  • Claude Code: reads .claude/skills; enterprise, personal, then project wins. Companion 2.1.325 loaded overlapping skills but ignored portable identity and root MCP settings. Skills
  • OpenCode: reads .opencode/skills, .claude/skills, and .agents/skills; later source wins. Companion 2.3.0 loaded no portable package; native plugins use another API. Skills
  • Pi: reads .pi/skills and .agents/skills; first found wins with a warning. No native portable-package loader exists; a community adapter adds support. Skills, configuration, adapter
  • Codex CLI: reads .agents/skills up to the Git root; duplicates remain unmerged and both can be listed. The marketplace-installed workflow ran on 0.169.0. Skills

OS-6: Preserve existing shared folders

Shared text still depends on each host’s discovery and extensions.

Keep common instructions in .agents/skills and preserve a correct Claude .claude/skills symbolic link. Reconcile existing real directories before changing them; never overwrite their work. Avoid duplicates and supply required native formats.

CLI import copies supported assets while leaving the original setup unchanged. Desktop import separately offers optional automatic updates. Neither establishes identical hook behavior or a live shared-folder link for CLI imports. Import

Optional layout inspection, not run: identify existing folders and links without changing or importing anything. Reset: close views, preserve files, links, global settings, and the base plugin; check Ask for approval, clean status, and seven passes.

OS-7 and OS-8: Accept evidence at the correct stage

Verify source, installation, skill reads, and tests.

Optional evidence inspection, not run: compare catalog identity, package details, installation state, and the runtime path. Reset: close plugin and skill views without toggling settings, preserve the sibling catalog and base installation, and verify clean status with seven passing tests and Ask for approval.

Illustration: a developer traces the selected installed skill to its source.

Match the selected component to the file read during execution.

Do this today

Everyone

  • Register the catalog, inspect and install triage-tools, and select its qualified skill in a fresh chat.
  • Verify its installed-source read and seven-test result, then independently check clean status.

If you read Going deeper

  • Inspect shared folders without changing them. Reset by preserving the layout, base plugin, and global settings.
  • Compare installation with runtime evidence. Reset by closing views and checking Ask for approval plus the clean seven-test project.

Coming up in Part 14: Parallel work, creating two isolated checkouts and inspecting each branch's changes.