OpenAI Plugins: package examples, portable formats and connection boundaries
Read the Figma plugin example: its draft parity hook prints a reminder
Trace the manifest, app mapping and hook script without mistaking a declared workflow or echoed reminder for an executed visual regression check.
What you will learn
- Follow references instead of assuming an implementation
- The hook is a reminder, not a screenshot comparator
- Test the contract that actually exists
Before you start
- Basic JSON and directory-path knowledge
- Understanding of skills and external-service permissions
Distinguish source examples from current format guidance and inspect a package without confusing metadata with runtime proof.
Key takeaways
- The app mapping identifies a connection; it does not implement its tools.
- The draft hook prints a reminder and performs no image comparison.
- Test claims must match the specific code that ran.
Follow references instead of assuming an implementation
The pinned Figma manifest declares version 2.0.20, skills at ./skills and apps at ./.app.json. The app mapping contains a connector identifier, not an API secret or an implementation of Figma tools. The package README describes app-backed workflows and labels the command, hook and UI directories as example scaffolding.
A manifest capability such as Read or Write describes presentation metadata. It does not implement access checks or prove a tool was called. To understand an example, trace the referenced resource and distinguish configuration, natural-language workflow and executable behavior before assigning any runtime guarantee.
The hook is a reminder, not a screenshot comparator
hooks.json declares a PostToolUse matcher for Write or Edit and names scripts/post_write_figma_parity_check.sh. The script has a Bash shebang, enables strict shell options and echoes a reminder to recheck Figma parity after UI-related writes. Its own header calls it a draft example for future hook runtimes.
There is no screenshot capture, image comparison or threshold decision in that script. Successful execution would only show that the reminder was printed; it would not establish visual fidelity. Its existence alongside the package also does not prove that current hosts automatically discover this legacy example hook file.
Test the contract that actually exists
For the configuration lesson, our synthetic model tests whole-object overlay selection and fixed portable component paths. Those tests are not tests of Figma, the draft hook or the Codex loader. We did not run the shell script, install the package or compare a real design against an implementation.
If you extend the reminder into a real parity check, define image acquisition, viewport, baseline revision, tolerances and review output first. A nonzero failure path and a reproducible artifact would be necessary for a useful gate. That extension is a proposal, not behavior present in the inspected script.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Trace manifest references to actual package files.
- 2
Read the hook declaration and complete script.
- 3
List operations the script performs and does not perform.
- 4
Design visual evidence separately before claiming a parity gate.
Copy-ready example
Inspected draft hook behavior:
1. Start Bash with strict options.
2. Print a parity-review reminder.
Not present: screenshot capture, pixel comparison, pass/fail threshold.Frequently asked questions
Does the checked-in hook verify screenshots?
No. The inspected script only prints a reminder.
Did the model tests exercise the real plugin loader?
No. They execute a separate synthetic configuration model.
Sources
- OpenAI Plugins / plugins/figma/.codex-plugin/plugin.jsonSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/.app.jsonSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/README.mdSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/hooks.jsonSource checked 2026-09-14
- OpenAI Plugins / plugins/figma/scripts/post_write_figma_parity_check.shSource checked 2026-09-14
- OpenAI — Package your plugin (checked 2026-09-14)Source checked 2026-09-14