Skip to content

Fix public Codex skill interface packaging - #73

Merged
TerminallyLazy merged 2 commits into
mainfrom
codex/public-skill-interface
Sep 17, 2026
Merged

TerminallyLazy merged 2 commits into
mainfrom
codex/public-skill-interface

Conversation

@TerminallyLazy

@TerminallyLazy TerminallyLazy commented Sep 17, 2026

Copy link
Copy Markdown
Owner

The public skills-only ZIP copied legacy SKILL.md metadata that OpenAI ignores and omitted the skill interface file. Codex plugin 0.3.10 now renders public front matter without that metadata, adds supported agents/openai.yaml interface fields, and uses a directory subtitle within the 30-character submission limit. The complete skill body and native lifecycle hooks remain unchanged.

The public and native profiles remain separate; no Rust runtime or Claude/Agent Zero release changes are required. Documentation identifies the exact public-upload artifact and correctly describes skill_metadata_ignored as a warning.

Validation: repository plugin-package checks pass, including deterministic ZIPs, unchanged executable hooks, public interface schema and body preservation, and negative metadata/interface cases. OpenAI skill-creator validation passes for the unpacked public skill. Public portal acceptance remains a separate verification step.

High-level PR Summary

This PR fixes the public Codex skills-only ZIP packaging to properly support OpenAI's plugin submission requirements. The build script now strips legacy metadata from skill front matter (which OpenAI ignores), adds a new agents/openai.yaml interface file with supported fields, and updates the directory shortDescription to fit the 30-character submission limit. The skill body and native lifecycle hooks remain unchanged. The plugin version is bumped from 0.3.9 to 0.3.10. Comprehensive validation checks are added to ensure public interface schema compliance, metadata filtering correctness, skill body preservation, and descriptor length limits.

⏱️ Estimated Review Time: 5-15 minutes

💡 Review Order Suggestion
Order File Path
1 plugins/tree-ring-memory/.codex-plugin/plugin.json
2 plugins/tree-ring-memory/packaging/codex-skills-only/.codex-plugin/plugin.json
3 plugins/tree-ring-memory/packaging/codex-skills-only/skills/tree-ring-memory/agents/openai.yaml
4 plugins/tree-ring-memory/packaging/build-codex-skills-only.py
5 scripts/validate-plugin-packages.py
6 plugins/tree-ring-memory/README.md
7 plugins/AGENTS.md
8 scripts/AGENTS.md

Need help? Join our Discord

Summary by CodeRabbit

  • New Features
    • Added public skill packaging with supported interface details, including display name, description, and default prompt.
    • Public packages now preserve skill content while omitting legacy metadata.
    • Added a concise public listing description within platform length limits.
  • Documentation
    • Updated installation and submission guidance for the 0.3.10 package.
    • Clarified public profile requirements and metadata warnings.
  • Chores
    • Updated the plugin and packaged artifact version to 0.3.10.

@coderabbitai

coderabbitai Bot commented Sep 17, 2026

Copy link
Copy Markdown

Review Change StackReview Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: de21e488-77d2-4926-a44a-d72713bb4b64

📥 Commits

Reviewing files that changed from the base of the PR and between 00591d4 and 3b985c3.

📒 Files selected for processing (9)
  • README.md
  • plugins/AGENTS.md
  • plugins/tree-ring-memory/.codex-plugin/plugin.json
  • plugins/tree-ring-memory/README.md
  • plugins/tree-ring-memory/packaging/build-codex-skills-only.py
  • plugins/tree-ring-memory/packaging/codex-skills-only/.codex-plugin/plugin.json
  • plugins/tree-ring-memory/packaging/codex-skills-only/skills/tree-ring-memory/agents/openai.yaml
  • scripts/AGENTS.md
  • scripts/validate-plugin-packages.py

📝 Walkthrough

Walkthrough

The PR updates the plugin to version 0.3.10, builds a public skills-only package without legacy metadata, adds OpenAI interface settings, and validates the transformed skill, manifest, interface, and ZIP contents.

Changes

Public skills-only packaging

Layer / File(s) Summary
Public profile contract
plugins/tree-ring-memory/.codex-plugin/plugin.json, plugins/tree-ring-memory/packaging/codex-skills-only/..., plugins/tree-ring-memory/README.md, plugins/AGENTS.md, README.md
The Codex package uses version 0.3.10. Its public listing uses a 30-character shortDescription limit. The OpenAI interface file defines display metadata and a default prompt. Documentation describes the versioned package and metadata handling.
Skills-only package builder
plugins/tree-ring-memory/packaging/build-codex-skills-only.py
The builder removes canonical metadata front matter from public SKILL.md files, preserves the remaining content, rejects malformed input and path collisions, and archives public profile skill files.
Package validation
scripts/validate-plugin-packages.py, scripts/AGENTS.md
Validation checks public front matter, interface fields, description and prompt constraints, manifest limits, preserved skill bodies, and generated ZIP contents.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant SourceSkills
  participant build_codex_skills_only
  participant PublicProfile
  participant validate_codex_skills_only
  SourceSkills->>build_codex_skills_only: Read source SKILL.md
  build_codex_skills_only->>PublicProfile: Apply public front matter and interface files
  PublicProfile->>validate_codex_skills_only: Provide generated ZIP contents
  validate_codex_skills_only->>validate_codex_skills_only: Validate metadata, interface, body, and manifest
Loading
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/public-skill-interface

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@qodo-code-review

Copy link
Copy Markdown

PR Summary by Qodo

Fix public Codex skill interface packaging

🐞 Bug fix 🧪 Tests 📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

Grey Divider

AI Description

• Render public SKILL.md without ignored metadata while preserving canonical instructions.
• Package supported OpenAI interface fields and directory-compliant listing text.
• Expand validation and documentation for the versioned skills-only upload.
Diagram

graph TD
  A["Native Skill"] --> B["ZIP Builder"] --> C["Public ZIP"] --> D["Package Validator"]
  E["Public Profile"] --> B
  C --> F["OpenAI Portal"]
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Maintain a separate public SKILL.md
  • ➕ Makes the exact public skill directly inspectable without build-time transformation.
  • ➕ Avoids custom front-matter filtering logic.
  • ➖ Duplicates the complete skill body and creates a substantial drift risk.
  • ➖ Requires synchronizing every native instruction change across profiles.
2. Parse front matter with a YAML library
  • ➕ Supports arbitrary YAML structures and future metadata layouts.
  • ➕ Can identify metadata semantically instead of relying on canonical indentation.
  • ➖ Adds a packaging dependency solely for a constrained transformation.
  • ➖ Serialization could reorder or reformat supported front matter unnecessarily.

Recommendation: Keep the PR's narrow build-time transformation and separate public interface profile. It preserves one canonical instruction body, avoids a new YAML dependency, and is appropriately protected by idempotence, body-preservation, schema, collision, and negative-case checks.

Files changed (8) +130 / -12

Bug fix (1) +38 / -3
build-codex-skills-only.pyRender a dedicated public skill profile +38/-3

Render a dedicated public skill profile

• Adds a constrained, idempotent front-matter renderer that removes canonical legacy metadata while preserving the skill body. The builder now overlays public profile skill files, rejects source collisions, and retains deterministic archive permissions and timestamps.

plugins/tree-ring-memory/packaging/build-codex-skills-only.py

Tests (1) +64 / -2
validate-plugin-packages.pyValidate the complete public skill artifact +64/-2

Validate the complete public skill artifact

• Updates expected versions and validates transformed front matter, interface field names and values, listing limits, body preservation, and profile equality. Adds idempotence and negative cases while retaining deterministic ZIP and executable-hook checks.

scripts/validate-plugin-packages.py

Documentation (3) +18 / -4
AGENTS.mdDocument public skill packaging contracts +1/-1

Document public skill packaging contracts

• Adds repository guidance requiring metadata-free public front matter, an 'agents/openai.yaml' interface, a 30-character directory subtitle, and separation from native skill sources.

plugins/AGENTS.md

README.mdClarify the public Skills-only release workflow +16/-2

Clarify the public Skills-only release workflow

• Updates the Codex version and generated archive name. Identifies the exact portal upload artifact, explains public interface placement and metadata omission, and clarifies that 'skill_metadata_ignored' is a warning.

plugins/tree-ring-memory/README.md

AGENTS.mdRecord public package validation requirements +1/-1

Record public package validation requirements

• Extends script-level contracts to cover interface schema, metadata omission, instruction-body preservation, and public directory listing limits.

scripts/AGENTS.md

Other (3) +10 / -3
plugin.jsonBump the native Codex plugin to 0.3.10 +1/-1

Bump the native Codex plugin to 0.3.10

• Advances the repository Codex manifest version for the corrected public packaging release.

plugins/tree-ring-memory/.codex-plugin/plugin.json

plugin.jsonUpdate the public manifest and directory subtitle +2/-2

Update the public manifest and directory subtitle

• Bumps the public profile to version 0.3.10 and replaces the listing subtitle with text that fits the portal's 30-character limit.

plugins/tree-ring-memory/packaging/codex-skills-only/.codex-plugin/plugin.json

openai.yamlAdd the supported OpenAI skill interface +7/-0

Add the supported OpenAI skill interface

• Introduces the public skill's display name, UI description, and default invocation prompt using supported snake_case interface fields. JSON syntax is used as a valid YAML subset for dependency-free validation.

plugins/tree-ring-memory/packaging/codex-skills-only/skills/tree-ring-memory/agents/openai.yaml

@qodo-code-review

qodo-code-review Bot commented Sep 17, 2026

Copy link
Copy Markdown

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (1) 📜 Skill insights (0)

Grey Divider


Remediation recommended

1. Readers see stale plugin version ✓ Resolved 🐞 Bug ≡ Correctness
Description
README.md still identifies the current Codex plugin as version 0.3.9, while the manifests and
package validation now require 0.3.10. After this release, readers following the top-level Quick
Start receive version information that conflicts with the shipped artifacts and plugin-specific
documentation.
Code

plugins/tree-ring-memory/.codex-plugin/plugin.json[3]

+  "version": "0.3.10",
Relevance

●●● Strong

Recent releases explicitly synchronize manifest versions with plugin README documentation.

PR-#49
PR-#61

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The changed native manifest declares 0.3.10, the public skills-only manifest and validator agree on
0.3.10, but the top-level Quick Start still presents 0.3.9 as current.

plugins/tree-ring-memory/.codex-plugin/plugin.json[1-4]
plugins/tree-ring-memory/packaging/codex-skills-only/.codex-plugin/plugin.json[1-4]
scripts/validate-plugin-packages.py[70-74]
README.md[114-120]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The top-level Quick Start still names Codex plugin version 0.3.9 after the release manifests were advanced to 0.3.10.

## Fix Focus Areas
- README.md[117-120]

## Recommended Fix
Change the Codex plugin version in the Quick Start lifecycle-hook paragraph from `0.3.9` to `0.3.10`, keeping the Claude version unchanged.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Public plugin repo stays broken 🔗 Cross-repo conflict ≡ Correctness
Description
plugin.json advances the bundled Codex package to 0.3.10 and the release instructions identify its
skills-only ZIP as the corrected public artifact, but the separately published
tree-ring-memory-codex-plugin repository remains at 0.3.9. Anyone building or submitting from that
wrapper still gets a ZIP that copies SKILL.md verbatim with metadata, omits
agents/openai.yaml, and retains the over-limit listing subtitle, so the fix does not reach that
distribution channel.
Code

plugins/tree-ring-memory/.codex-plugin/plugin.json[3]

+  "version": "0.3.10",
Relevance

●● Moderate

External wrapper drift is plausible, but no repository precedent establishes ownership of separately
published repositories.

PR-#63
PR-#47

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The PR declares version 0.3.10 and documents that release as containing filtered front matter and
the OpenAI interface file. The standalone plugin repository remains version 0.3.9; its builder
copies every skill file unchanged, while its checked-in skill still contains the legacy metadata
block, and its public manifest retains the longer subtitle.

plugins/tree-ring-memory/.codex-plugin/plugin.json[1-4]
plugins/tree-ring-memory/README.md[131-140]
External repo: TerminallyLazy/tree-ring-memory-codex-plugin, .codex-plugin/plugin.json [1-10]
External repo: TerminallyLazy/tree-ring-memory-codex-plugin, packaging/build-codex-skills-only.py [26-39]
External repo: TerminallyLazy/tree-ring-memory-codex-plugin, skills/tree-ring-memory/SKILL.md [1-9]
External repo: TerminallyLazy/tree-ring-memory-codex-plugin, packaging/codex-skills-only/.codex-plugin/plugin.json [24-29]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The standalone `tree-ring-memory-codex-plugin` repository still publishes version 0.3.9 using the obsolete public ZIP builder, despite Tree_Ring_Memory declaring the corrected package as 0.3.10.

## Fix Focus Areas
- plugins/tree-ring-memory/.codex-plugin/plugin.json[1-4]
- plugins/tree-ring-memory/packaging/build-codex-skills-only.py[61-71]
- /cross_repos/tree-ring-memory-codex-plugin/.codex-plugin/plugin.json[1-4]
- /cross_repos/tree-ring-memory-codex-plugin/packaging/build-codex-skills-only.py[26-39]

## Recommended Fix
Coordinate a 0.3.10 update in `tree-ring-memory-codex-plugin`: port the public front-matter renderer, add `skills/tree-ring-memory/agents/openai.yaml`, shorten the public manifest subtitle, update validation and documentation, and publish both repositories or their release artifacts together.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
✅ Cross-repo context — repo relationships
  Explored: repo: TerminallyLazy/tree-ring-memory-codex-plugin (sha: a75de0c8)
Review mode: ⚖️ Balanced: This changes public plugin packaging and validation logic across multiple files, with interface and artifact compatibility implications that warrant a complete review.

Grey Divider

Tip of the day
💡 Did you know, you can enable the Remediation agent and Qodo fixes findings in a dedicated fix PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

Comment thread plugins/tree-ring-memory/.codex-plugin/plugin.json
{
"name": "tree-ring-memory",
"version": "0.3.9",
"version": "0.3.10",

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remediation recommended

2. Public plugin repo stays broken 🔗 Cross-repo conflict ≡ Correctness

plugin.json advances the bundled Codex package to 0.3.10 and the release instructions identify its
skills-only ZIP as the corrected public artifact, but the separately published
tree-ring-memory-codex-plugin repository remains at 0.3.9. Anyone building or submitting from that
wrapper still gets a ZIP that copies SKILL.md verbatim with metadata, omits
agents/openai.yaml, and retains the over-limit listing subtitle, so the fix does not reach that
distribution channel.
Agent Prompt
## Issue description
The standalone `tree-ring-memory-codex-plugin` repository still publishes version 0.3.9 using the obsolete public ZIP builder, despite Tree_Ring_Memory declaring the corrected package as 0.3.10.

## Fix Focus Areas
- plugins/tree-ring-memory/.codex-plugin/plugin.json[1-4]
- plugins/tree-ring-memory/packaging/build-codex-skills-only.py[61-71]
- /cross_repos/tree-ring-memory-codex-plugin/.codex-plugin/plugin.json[1-4]
- /cross_repos/tree-ring-memory-codex-plugin/packaging/build-codex-skills-only.py[26-39]

## Recommended Fix
Coordinate a 0.3.10 update in `tree-ring-memory-codex-plugin`: port the public front-matter renderer, add `skills/tree-ring-memory/agents/openai.yaml`, shorten the public manifest subtitle, update validation and documentation, and publish both repositories or their release artifacts together.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

@TerminallyLazy
TerminallyLazy merged commit 31d7aaf into main Sep 17, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant