A Codex plugin needs a valid package layout and a clear relationship between skills and tool connections. Keep local execution requirements visible to users before they install.

Manifest → Bundled guidance → Tool configuration → Installed verification
  1. 1Manifest
  2. 2Bundled guidance
  3. 3Tool configuration
  4. 4Installed verification

Work through the example

Validate the .codex-plugin manifest and resolve its paths from the package root. Check the official packaging documentation before release.

Start with a disposable branch and synthetic data. Write the expected outcome before changing the implementation, then keep the first failing result. This prevents a later repair from quietly redefining the task. The procedure below is grounded in the repository reference; its examples must still be checked against your project and installed toolchain.

Build the package directory

Use a separate package root so the manifest's relative paths resolve consistently:

my-swift-plugin/
  .codex-plugin/
    plugin.json
  .mcp.json
  skills/
    swift-review/
      SKILL.md

The repository's existing package uses this same separation between plugin metadata, skill content and MCP configuration. A small manifest for the exercise is:

{
  "name": "my-swift-plugin",
  "version": "0.1.0",
  "description": "Focused Swift review guidance for this project.",
  "skills": "./skills/",
  "mcpServers": "./.mcp.json"
}

Keep the public name lowercase and stable. The version belongs to your plugin; it does not have to match the server version. The MCP file can pin the released package used in the existing setup:

{
  "mcpServers": {
    "ios-agent": {
      "command": "npx",
      "args": ["-y", "ios-agent-mcp@2.7.0"]
    }
  }
}

Create skills/swift-review/SKILL.md with a name, a task-specific description and a short review procedure. Start with a synthetic Swift file, request located findings and require an explicit distinction between static inspection and a build result.

Validate before installing

Run JSON parsing and path checks from the package root:

python3 -m json.tool .codex-plugin/plugin.json >/dev/null
python3 -m json.tool .mcp.json >/dev/null
test -f skills/swift-review/SKILL.md

These commands validate syntax and file presence, not the entire client schema. Then follow the current official plugin installation/development workflow for your client. Confirm the installed package exposes the skill and exactly one server connection. Remove or disable a duplicate direct MCP registration before judging duplicate tools as a server bug.

For a reproducible artifact, create an archive from the package contents rather than accidentally nesting the root twice:

zip -r ../my-swift-plugin.zip .codex-plugin .mcp.json skills
unzip -l ../my-swift-plugin.zip

Inspect the archive inventory for local paths, logs or account files. A distributable package should contain the declared inputs, not your whole development checkout. This example is a package construction exercise; installation and marketplace review remain separate validation steps.

Acceptance and failure review

Checkpoint What to inspect If it does not match
Manifest Confirm the input and environment Preserve the failure and return to this step
Bundled guidance Inspect the intermediate artifact Preserve the failure and return to this step
Tool configuration Run the focused check Preserve the failure and return to this step
Installed verification Record the observed result Preserve the failure and return to this step

Ask the agent to explain the smallest change that resolves the observed mismatch. Keep unrelated refactors out of the repair. A change that makes a warning disappear is not enough if the behavior or ownership contract has changed. Re-run the same acceptance check so the before and after results are comparable.

Check the current package contract

Use the official plugin architecture documentation for the package contract. A local manifest check and an accepted directory listing are distinct results. Keep the plugin’s executable requirements visible, and test the installed package rather than only a source checkout.

Evidence and limits

No new marketplace acceptance is claimed by this chapter.

This is an educational guide. Its presence in the series does not certify a completed client-specific lab. The series evidence record separates executed checks from exercises and blocked environments.

Inspect the source used in this lesson.

What to do next

Next: Cross-client packaging: verified Muse scope and an Antigravity test boundary