Skip to content

πŸŽ₯ Make videos programmatically with React

Add skill for updating the published Codex plugin

Jonny Burger117faa475e3a
diff --git a/.agents/skills/update-codex-plugin/SKILL.md b/.agents/skills/update-codex-plugin/SKILL.md
new file mode 100644
index 0000000000..5d8f73a6b2
--- /dev/null
+++ b/.agents/skills/update-codex-plugin/SKILL.md
@@ -0,0 +1,118 @@
+---
+name: update-codex-plugin
+description: Update Remotion's published Codex and ChatGPT directory plugin to a released Remotion version. Prepare the ZIP from the official Codex plugin repository, preserve its listing metadata, and upload and publish through OpenAI Platform.
+---
+
+# Update the Codex plugin
+
+Update the existing public Remotion plugin, whose identity is
+`plugins~Plugin_efd07789186881918253a50acfc32762`.
+
+- Dashboard: https://platform.openai.com/plugins/manage/plugins~Plugin_efd07789186881918253a50acfc32762
+- Public listing: https://chatgpt.com/plugins/plugins~Plugin_efd07789186881918253a50acfc32762
+- Release source: https://github.com/remotion-dev/codex-plugin
+
+The monorepo release pipeline updates this GitHub repository but does not update
+the public directory. `codex plugin add` and marketplace upgrades manage local
+installations, not the public listing. Do not use the old `packages/codex-plugin`
+build directory, `openai/plugins`, or the portable `cursor-plugin` package for this
+upload.
+
+As checked on 2026-10-08, OpenAI documents a dashboard ZIP upload workflow, and
+the available CLI has no public-directory publishing command. Use browser tools
+for this part. Prefer a documented publishing API if one becomes available;
+do not replay private dashboard requests or extract browser credentials.
+Current reference: [OpenAI plugin submission](https://developers.openai.com/plugins/deploy/submission).
+
+## Inspect the current release
+
+Use the browser's signed-in OpenAI Platform session. Confirm the Remotion
+organization and the existing plugin identity. The dashboard's **Publication
+Version** is authoritative; the local plugin cache can lag behind it.
+
+Read the version selector and review state before uploading. If the requested
+version is already published, report that. If its draft or review already exists,
+continue that version instead of making a duplicate. Do not cancel another
+active review just to upload again.
+
+Select the **Published** version under **Metadata & Skills**, then use **More
+plugin actions β†’ Download release ZIP**. Use the actual downloaded file path.
+This is the baseline for preserving listing text, branding, and publication
+settings. An installed cache is not a substitute for the published package.
+
+## Prepare the ZIP
+
+Run from the monorepo root:
+
+```bash
+python3 .agents/skills/update-codex-plugin/scripts/prepare-release.py \
+ --published-zip /absolute/path/to/downloaded-release.zip
+```
+
+By default, the helper resolves the latest stable Remotion GitHub release. To
+use a user-requested release, add `--version 4.0.534`. It requires `gh` and Python
+3, fetches the corresponding tag from `remotion-dev/codex-plugin`, pins its commit,
+and creates a temporary staging directory and upload ZIP outside the checkout.
+It does not publish, install, or modify the monorepo.
+
+The helper uses the released package and preserves the published `interface`,
+assigned `id`, and OpenAI `extensions`, including referenced listing assets.
+Inspect its JSON report, particularly `preserved_manifest_differences`. Keep
+those overrides for a skills update; change them only when the task includes a
+listing change. If the source package structure has changed incompatibly, adapt
+the helper before uploading instead of silently dropping components.
+
+Check the reported source commit, version, skill names, and ZIP path. With the
+monorepo dependencies installed, lint the staged package from
+`packages/agent-plugin` using the existing Vally library:
+
+```bash
+bun -e 'import {runLint, LintConsoleReporter} from "@microsoft/vally"; const result = await runLint({rootPath: process.argv[1]}); await new LintConsoleReporter({verbose: true}).report(result); if (!result.passed) process.exit(1);' /absolute/path/to/staged/remotion
+```
+
+`@microsoft/vally` is a library; it does not provide a `vally` CLI. Fix actual
+packaging findings before uploading. Do not change skill content merely to
+bypass a safety finding.
+
+## Upload and publish in the browser
+
+An instruction to update this published plugin covers its normal upload and
+publication workflow. Honor narrower requests such as preparing a ZIP, creating
+a skill, or uploading a draft; those alone do not authorize publication.
+
+1. Open the existing plugin and click **Upload new version**, **Upload plugin to
+ make changes**, or **Upload plugin to fix issues**, whichever the dashboard shows.
+2. In **Upload new version**, keep the existing verified Remotion developer
+ identity. Choose the helper's ZIP using the browser tool's file-upload API,
+ reading its upload documentation first. Choosing the file can start the upload
+ immediately; inspect the result before clicking **Upload plugin** or retrying.
+ If Chrome's extension upload requires **Allow access to file URLs**, the native
+ picker also works: select the correct Chrome tab through the native app tool,
+ click **Choose file**, press Command-Shift-G, read the new accessibility state,
+ set the path field to the exact ZIP, press Return, verify the selected filename,
+ then click **Open**. Do not change extension permissions just for this fallback.
+3. Confirm the new version under **Metadata & Skills**. Read metadata and skill
+ check results for that version, not the older published version. Refresh the
+ browser state after actions; do not reuse stale element indices.
+4. Follow the displayed review workflow. Read findings before deciding whether
+ they block submission. A skill can show **Needs attention** while the version
+ is **Approved** and **Ready to publish**; a warning alone does not establish
+ that review failed. If a new ZIP is needed, fix the staged package and
+ recreate it, preserving the release's provenance. Do not keep uploading the
+ same ZIP to retry pending scans.
+5. When the requested version is approved and publication is authorized, select
+ **Publish plugin**. If policy attestations include accepting legal terms,
+ obtain the confirmation required by the active browser tool before accepting
+ them. Do not claim unperformed tests or invent review information.
+6. Verify **Publication Version** shows the target version as **Published**.
+ A selected draft, successful upload, approval, or GitHub tag does not establish
+ publication. Save browser evidence using the active tool's supported method.
+
+Scans and human review may outlast the current turn. Report the exact version,
+state, findings, and dashboard URL; keep the dashboard available for follow-up.
+Only set up a scheduled follow-up when the user asks for one. On an uncertain
+upload result, inspect the version list before retrying.
+
+Finish with the prepared or published version, source commit, validation result,
+and any remaining dashboard step. Clearly distinguish **prepared**, **uploaded**,
+**under review**, **approved**, and **published**.
diff --git a/.agents/skills/update-codex-plugin/scripts/prepare-release.py b/.agents/skills/update-codex-plugin/scripts/prepare-release.py
new file mode 100644
index 0000000000..6b5d495272
--- /dev/null
+++ b/.agents/skills/update-codex-plugin/scripts/prepare-release.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+"""Prepare an immutable Remotion Codex release while preserving its public listing."""
+
+import argparse
+import hashlib
+import io
+import json
+import re
+import subprocess
+import tarfile
+import tempfile
+import zipfile
+from pathlib import Path, PurePosixPath
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("--published-zip", type=Path, required=True)
+ parser.add_argument("--version", help="Released version; defaults to latest stable")
+ args = parser.parse_args()
+
+ def api(endpoint):
+ result = subprocess.run(["gh", "api", endpoint], capture_output=True)
+ if result.returncode:
+ raise SystemExit(result.stderr.decode("utf-8", errors="replace"))
+ return result.stdout
+
+ version = args.version
+ if version is None:
+ version = json.loads(api("repos/remotion-dev/remotion/releases/latest"))[
+ "tag_name"
+ ]
+ version = version.removeprefix("v")
+ if not re.fullmatch(r"\d+\.\d+\.\d+", version):
+ raise ValueError("Expected a stable Remotion version such as 4.0.534")
+
+ manifest_path = ".codex-plugin/plugin.json"
+ unsupported = {"plugin.json", "mcp.json", ".mcp.json", ".app.json", "hooks/hooks.json"}
+ with zipfile.ZipFile(args.published_zip) as archive:
+ candidates = [
+ name for name in archive.namelist()
+ if name == manifest_path or name.endswith("/" + manifest_path)
+ ]
+ if len(candidates) != 1:
+ raise ValueError("Published ZIP must contain exactly one Codex manifest")
+ prefix = candidates[0][:-len(manifest_path)]
+ published_files = {
+ name[len(prefix):]: archive.read(name)
+ for name in archive.namelist()
+ if name.startswith(prefix) and not name.endswith("/")
+ }
+
+ published = json.loads(published_files[manifest_path])
+ if published.get("name") != "remotion":
+ raise ValueError("The baseline ZIP is not the published Remotion plugin")
+ old_version = published.get("version", "")
+ if not re.fullmatch(r"\d+\.\d+\.\d+", old_version):
+ raise ValueError("Published version is not a stable semantic version")
+ if tuple(map(int, version.split("."))) <= tuple(map(int, old_version.split("."))):
+ raise ValueError(f"Target {version} must be newer than published {old_version}")
+ if unsupported.intersection(published_files) or any(
+ key in published for key in ("mcpServers", "apps", "hooks")
+ ):
+ raise ValueError("The baseline is not a standalone skills-only Codex package")
+
+ repo = "remotion-dev/codex-plugin"
+ commit = json.loads(api(f"repos/{repo}/commits/v{version}"))["sha"]
+ files = {}
+ with tarfile.open(fileobj=io.BytesIO(api(f"repos/{repo}/tarball/{commit}"))) as archive:
+ for entry in archive:
+ parts = PurePosixPath(entry.name).parts[1:]
+ if not parts or entry.isdir():
+ continue
+ if not entry.isfile() or ".." in parts:
+ raise ValueError(f"Unexpected archive entry: {entry.name}")
+ files["/".join(parts)] = archive.extractfile(entry).read()
+
+ manifest = json.loads(files[manifest_path])
+ if manifest.get("name") != "remotion" or manifest.get("version") != version:
+ raise ValueError("The tagged Codex manifest does not match the requested release")
+ if manifest.get("skills") != "./skills/":
+ raise ValueError("The skill layout changed; review the packaging workflow")
+ if unsupported.intersection(files) or any(
+ key in manifest for key in ("mcpServers", "apps", "hooks")
+ ):
+ raise ValueError("The source is no longer a standalone skills-only Codex package")
+
+ preserved_differences = {}
+ for key in ("interface", "id", "extensions"):
+ if key in published:
+ if manifest.get(key) != published[key]:
+ preserved_differences[key] = {
+ "released_source": manifest.get(key), "published": published[key]
+ }
+ manifest[key] = published[key]
+
+ # Listing image paths may have been normalized by the directory. Copy the
+ # exact files those preserved paths reference from the downloaded release.
+ pending = [manifest.get("interface", {}), manifest.get("extensions", {})]
+ while pending:
+ value = pending.pop()
+ if isinstance(value, dict):
+ pending.extend(value.values())
+ elif isinstance(value, list):
+ pending.extend(value)
+ elif isinstance(value, str) and value.startswith("./"):
+ relative = PurePosixPath(value[2:])
+ if relative.is_absolute() or ".." in relative.parts:
+ raise ValueError(f"Invalid manifest path: {value}")
+ key = str(relative)
+ if key.startswith("skills/"):
+ if key not in files:
+ raise ValueError(f"Preserved metadata references a missing skill: {key}")
+ elif key in published_files:
+ files[key] = published_files[key]
+ else:
+ raise ValueError(f"Missing published listing asset: {key}")
+
+ skill_paths = sorted(path for path in files if path.endswith("/SKILL.md"))
+ if not skill_paths or any(
+ not path.startswith("skills/") or len(PurePosixPath(path).parts) != 3
+ for path in skill_paths
+ ):
+ raise ValueError("Expected discoverable skills directly inside skills/<name>/")
+ for path in skill_paths:
+ text = files[path].decode("utf-8")
+ match = re.match(r"\A---\r?\n(.*?)\r?\n---", text, re.S)
+ if not match or not re.search(
+ rf"^version:\s*{re.escape(version)}\s*$", match[1], re.M
+ ):
+ raise ValueError(f"Skill version does not match {version}: {path}")
+
+ files[manifest_path] = (json.dumps(manifest, indent=2) + "\n").encode()
+ output = Path(tempfile.mkdtemp(prefix=f"remotion-codex-{version}-"))
+ staging = output / "remotion"
+ zip_path = output / f"remotion-{version}.zip"
+ with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as archive:
+ for name, contents in sorted(files.items()):
+ relative = PurePosixPath(name)
+ if relative.is_absolute() or ".." in relative.parts:
+ raise ValueError(f"Invalid package path: {name}")
+ target = staging / name
+ target.parent.mkdir(parents=True, exist_ok=True)
+ target.write_bytes(contents)
+ archive.writestr(name, contents)
+
+ report = {
+ "version": version,
+ "previous_version": old_version,
+ "source_commit": commit,
+ "source_url": f"https://github.com/{repo}/tree/{commit}",
+ "staging_directory": str(staging),
+ "zip_path": str(zip_path),
+ "zip_sha256": hashlib.sha256(zip_path.read_bytes()).hexdigest(),
+ "file_count": len(files),
+ "skills": [PurePosixPath(path).parts[1] for path in skill_paths],
+ "preserved_manifest_differences": preserved_differences,
+ }
+ (output / "preparation.json").write_text(json.dumps(report, indent=2) + "\n")
+ print(json.dumps(report, indent=2))
+
+
+if __name__ == "__main__":
+ main()