Design the plugin around one user journey

Understand the approach

Plugin architecture should start with a user journey: what information enters, which operation is needed, what result is returned, and how it is checked. The package is a delivery unit, not an architecture by itself. For a README review plugin, a skill may read a user-selected document and produce evidence-linked suggestions without a server. For live records, an MCP server supplies the controlled service boundary.

Keep responsibilities explicit. Skills define the method, expected output, decision points, and fallback behavior. MCP tools expose actual operations and enforce service-side authentication and authorization. Optional UI can help users inspect structured results, but is not necessary for a text-only workflow. Hooks attach to documented lifecycle points and require reviewed definitions plus runnable scripts in the execution environment.

The source architecture bundles commands, agents, MCP, hooks, and configuration. Codex plugin architecture provides related building blocks, but a source component does not automatically map one-to-one. Turn reusable command or agent procedures into an appropriate supported skill when needed. Treat local hook execution and cloud-orchestrated Work as different paths. Installing a package on the web does not deploy its local executable scripts.

Design the unhappy path first

For a document review, specify what happens when the document is missing, its instructions conflict with the user's request, or its examples contain private credentials. A useful result identifies the missing or suspicious material without executing it. If a later server is disconnected, the plugin should explain the gap instead of replacing live facts with invented data. These behaviors belong in the architecture because they shape the user's experience, not just developer diagnostics.

An installed copy can differ from the source

The marketplace points to authoring files, while native installation may use a cached copy. Inspect the returned installed path/version; changing the source alone does not prove an existing session is using it. The extension task changes the server and manifest to 0.3.0 so this distinction is observable.

Try it step by step

1. Trace fixture-review/SKILL.md through list/review tool calls to exact fixture findings.
2. Run demo.cjs and retain a real successful result and rejected traversal request.
3. Identify what the skill instructs, what the server enforces, and what informational hooks can contribute.
4. Install through the generated marketplace track and inspect the actual cached version before native invocation.
5. In the app’s new chat select the skill, request missing-checks, and inspect the actual tool call/evidence when supported; label any unavailable stage.

A useful starting example

Illustration · adapt before use.

node labs/workflow-plugin/demo.cjs

Trace labs/workflow-plugin from skill instructions through MCP initialization, discovery, tool call, and evidence.
Map the client, server, checker, fixed fixtures, and optional informational hooks.
Explain successful, rejected, and unavailable-data paths with actual outputs where available.
Identify which component could be omitted for a simpler single-user workflow.
Do not install or connect external services.

Check your result

• The architecture uses the real packaged components and observed protocol sequence.
• Read/write and arbitrary-path boundaries are explicit.
• The failure trace preserves the error instead of manufacturing a successful review.

Common mistakes

• Putting access-control rules only in a skill while the service accepts unrestricted operations.
• Treating optional UI, hooks, agents, and a server as mandatory plugin boilerplate.