Community tool: SKILL.md → Codex plugin bundle converter (MIT, stdlib-only)

[chenhz01]

Sharing a community tool, not an issue: https://github.com/chenhz01/zhengming-openai-plugins converts Agent Skills SKILL.md folders into compliant Codex plugin manifests (.codex-plugin/plugin.json + skills/ layout + marketplace index), enforcing the upload hard constraints (≤1024 description, reserved names) in CI, with behavior regression tests. Feedback welcome — especially on manifest fields we may have mapped conservatively.

Ref: AS-B03

[ooocooc]

One concrete validation gap: the description check needs to inspect the bundled SKILL.md front matter, not just the plugin manifest.

At commit 9521240, convert() copies the skill directory before truncating desc for plugin.json. The demo-longdesc fixture has a 1,200-character description, so that copy retains the overlong value. The CI test asserts the generated plugin description is 1,024 characters, but only checks that the bundled SKILL.md exists.

The official submission-error reference separately lists skill_description_too_long for the skill description, with a 1,024-character limit.

A focused regression would parse the front matter in out/plugins/demo-longdesc/skills/demo-longdesc/SKILL.md and validate that field too. Then either reject an overlong input clearly, or deliberately normalize the generated copy while proving the source remains unchanged. This would test the uploaded artifact rather than only its manifest metadata.

This is a source-and-fixture check; I haven't run the converter or attempted an upload.

[chenhz01]

Thanks for the precise report — you read the generated bundle more carefully than my CI did.

Fixed on main:

What changed

• convert() now normalizes the bundled skills/<name>/SKILL.md front-matter description to the same 1,024-character limit as the manifest (new normalize_bundled_frontmatter()), rewriting only the description: line. The uploaded artifact can no longer trip skill_description_too_long. The source SKILL.md is never modified.
• Regression added in tests/ci_check.py along the exact lines you suggested: it parses the front matter of out/plugins/demo-longdesc/skills/demo-longdesc/SKILL.md and asserts (a) normalized to 1,024 with ..., (b) identical to the manifest description, (c) the source fixture still carries the original 1,200-character description. The per-fixture loop now validates the bundled front matter for every fixture, and the self-host byte-identity check still passes — proving normalization only fires when the input is actually overlong. Full suite: ALL GREEN (25 checks).

Commits: 9ae29cc (fix + regressions), 7d471af (docs).

One design note: I chose "normalize the generated copy" over "reject the input", consistent with how the manifest field already behaves. If you think a submission-ready converter should instead fail loudly on overlong input, happy to switch to a hard reject with a clear error message.

[ooocooc]

Normalizing the generated copy is a reasonable policy if the transformation is reported and the source stays untouched. Before treating that policy as submission-ready, I would add one independent YAML-semantic regression.

At 9ae29cc, parse_frontmatter(), a valid folded description such as description: >- followed by an indented 1,200-character string is read as the literal >- (length 2); the indented content is skipped. normalize_bundled_frontmatter() therefore returns early, leaving the actual overlong YAML string in the copied bundle.

A small fixture can be generated with:

text = "---\nname: demo-folded\ndescription: >-\n  " + "x" * 1200 + "\n---\nInstructions.\n"

In an isolated in-memory check, an independent YAML parser reads a 1,200-character description, while the current line-splitting algorithm reads 2. The official constraint applies to the description string, not the block-scalar indicator.

The generic bundled-length assertion reuses the converter's parser, so it cannot detect this case by itself. This is not a claim that the whole suite was demonstrated to pass a modified fixture. I'd add a separate folded/block-scalar fixture and validate the bundled artifact with a real YAML parser, then either normalize that decoded value safely or reject unsupported representations explicitly.

Scope: source review plus the isolated parser comparison above; I did not run the converter, its full suite, or an upload.