Verify Plugin
Combine deterministic structural checks with live documentation and behavioral
review. A passing script is a baseline, not proof that a changing product
contract or repository-adaptation design is correct.
Workflow
Locate either a marketplace root containing
.agents/plugins/marketplace.json or a plugin root containing
.codex-plugin/plugin.json.
Complete the repository's official-documentation preflight. Fetch current
official architecture, packaging, skills, hooks, MCP/app, AGENTS.md, and
security documentation relevant to the package. Record URLs and date; copy
no upstream prose.
Run the bundled validator with Node.js 20 or newer:
node <skill-directory>/scripts/validate-marketplace.mjs <target-root>
Add --json when machine-readable output is useful.
Fix structural errors before judgment-based review. Do not weaken the
validator to accept a malformed package.
Review the user-goal and architecture contract:
- each plugin is an independently useful, cohesive vertical slice;
- each skill has one recognizable trigger and outcome;
- domain decisions are separated from host and environment adapters where
variation is material;
- ports expose the smallest required capability and keep reads distinct from
writes where possible;
- optional adapters are replaceable and have useful fallbacks; and
- no speculative framework or sibling-plugin coupling was introduced.
Review context and configuration behavior:
- current request and active
AGENTS.md context precede plugin defaults;
- native project evidence is inspected proportionally;
- native Codex configuration is preferred over custom config;
- defaults are quiet, safe, reversible, and non-blocking; and
- no user, employer, machine, subscription, credential, or source-install
assumption leaked into runtime behavior.
Review safety and operations:
- writes preserve unrelated changes and follow approval boundaries;
- hooks expose trust requirements;
- secrets remain outside the package;
- unsupported platforms and missing tools fail safely; and
- non-retryable or partial-failure behavior is explicit.
Run the built-in $plugin-creator validator and $skill-creator quick
validator for every changed skill when those workflows are available.
Exercise direct, indirect, negative, incomplete, root/nested context,
missing-dependency, platform, existing-change, partial-failure, and isolated-
install cases. For migrations, disable source and sibling marketplaces.
Report
Report errors first, then warnings and untested behavior. Include exact file
paths, commands, live upstream URLs and date checked, context cases, adapter and
fallback decisions, and behavioral evidence.
1---2name: verify-plugin3description: Validate a Codex plugin package or repo marketplace for manifest, catalog, skill, context-discovery, architecture, path, and portability defects. Use when reviewing, testing, publishing, migrating, or troubleshooting `.codex-plugin/plugin.json` or `.agents/plugins/marketplace.json` content.4---56# Verify Plugin78Combine deterministic structural checks with live documentation and behavioral9review. A passing script is a baseline, not proof that a changing product10contract or repository-adaptation design is correct.1112## Workflow13141. Locate either a marketplace root containing15 `.agents/plugins/marketplace.json` or a plugin root containing16 `.codex-plugin/plugin.json`.172. Complete the repository's official-documentation preflight. Fetch current18 official architecture, packaging, skills, hooks, MCP/app, `AGENTS.md`, and19 security documentation relevant to the package. Record URLs and date; copy20 no upstream prose.213. Run the bundled validator with Node.js 20 or newer:2223 ```text24 node <skill-directory>/scripts/validate-marketplace.mjs <target-root>25 ```2627 Add `--json` when machine-readable output is useful.284. Fix structural errors before judgment-based review. Do not weaken the29 validator to accept a malformed package.305. Review the user-goal and architecture contract:31 - each plugin is an independently useful, cohesive vertical slice;32 - each skill has one recognizable trigger and outcome;33 - domain decisions are separated from host and environment adapters where34 variation is material;35 - ports expose the smallest required capability and keep reads distinct from36 writes where possible;37 - optional adapters are replaceable and have useful fallbacks; and38 - no speculative framework or sibling-plugin coupling was introduced.396. Review context and configuration behavior:40 - current request and active `AGENTS.md` context precede plugin defaults;41 - native project evidence is inspected proportionally;42 - native Codex configuration is preferred over custom config;43 - defaults are quiet, safe, reversible, and non-blocking; and44 - no user, employer, machine, subscription, credential, or source-install45 assumption leaked into runtime behavior.467. Review safety and operations:47 - writes preserve unrelated changes and follow approval boundaries;48 - hooks expose trust requirements;49 - secrets remain outside the package;50 - unsupported platforms and missing tools fail safely; and51 - non-retryable or partial-failure behavior is explicit.528. Run the built-in `$plugin-creator` validator and `$skill-creator` quick53 validator for every changed skill when those workflows are available.549. Exercise direct, indirect, negative, incomplete, root/nested context,55 missing-dependency, platform, existing-change, partial-failure, and isolated-56 install cases. For migrations, disable source and sibling marketplaces.5758## Report5960Report errors first, then warnings and untested behavior. Include exact file61paths, commands, live upstream URLs and date checked, context cases, adapter and62fallback decisions, and behavioral evidence.
melodic-software