Fix Codex skill version metadata (#703)

Move Codex and .agents skill versions under metadata while keeping all version readers compatible with legacy top-level frontmatter.\n\nAI assistance: prepared with Codex under maintainer direction.

scripts/lib/transformers/factory.js

@@ -241,6 +241,7 @@ export function createTransformer(config) {
     providerTags = [provider],
     writeOpenAIMetadata = false,
     includeVersion = true,
+    versionInMetadata = false,
   } = config;
   const placeholderKey = placeholderProvider || provider;
 
@@ -274,7 +275,9 @@ export function createTransformer(config) {
         name: skillName,
         description: skill.description,
       };
-      if (skillsVersion && includeVersion) frontmatterObj.version = skillsVersion;
+      if (skillsVersion && includeVersion && !versionInMetadata) {
+        frontmatterObj.version = skillsVersion;
+      }
 
       for (const spec of activeFields) {
         if (spec.condition && !spec.condition(skill)) continue;
@@ -282,6 +285,13 @@ export function createTransformer(config) {
         if (val) frontmatterObj[spec.yamlKey] = val;
       }
 
+      if (skillsVersion && includeVersion && versionInMetadata) {
+        frontmatterObj.metadata = {
+          ...(frontmatterObj.metadata || {}),
+          version: skillsVersion,
+        };
+      }
+
       // Replace {{command_hint}} in argument-hint with command names from metadata,
       // grouped by category with middle dots between groups for natural line-breaking.
       if (frontmatterObj['argument-hint']?.includes('{{command_hint}}')) {

scripts/lib/transformers/providers.js

@@ -48,6 +48,9 @@ export const PROVIDERS = {
     configDir: '.codex',
     displayName: 'Codex',
     frontmatterFields: [],
+    // Codex's validator rejects unknown top-level keys. Version remains
+    // available to Impeccable's updater under the spec-defined metadata map.
+    versionInMetadata: true,
     writeOpenAIMetadata: true,
     // No agentFormat: the Codex subagent ships nested inside the skill's own
     // agents/ folder (see CODEX_SKILL_PROVIDERS in factory.js), which Codex
@@ -63,6 +66,7 @@ export const PROVIDERS = {
     displayName: 'Codex Repo Skills',
     placeholderProvider: 'codex',
     frontmatterFields: [],
+    versionInMetadata: true,
     writeOpenAIMetadata: true,
   },
   github: {

scripts/lib/utils.js

@@ -787,6 +787,9 @@ export function generateYamlFrontmatter(data) {
           lines.push(`  - ${formatYamlScalar(item)}`);
         }
       }
+    } else if (value && typeof value === 'object') {
+      lines.push(`${key}:`);
+      appendYamlObject(lines, value, 2);
     } else if (typeof value === 'boolean') {
       lines.push(`${key}: ${value}`);
     } else {

scripts/lib/validate-plugin-versions.js

@@ -25,17 +25,43 @@ import fs from 'fs';
 import path from 'path';
 
 /**
- * Pull the `version:` value out of a SKILL.md leading frontmatter block.
+ * Pull the version value out of a SKILL.md leading frontmatter block.
  * CRLF-tolerant (`\r?\n`) to match the shared parseFrontmatter in
  * scripts/lib/utils.js — a bundle saved with CRLF line endings must not read
- * as a null version and trip a false mismatch. `(.+)` stops at the line
- * terminator (so a trailing `\r` is excluded), and `.trim()` mops up the rest.
+ * as a null version and trip a false mismatch. Codex builds carry the version
+ * under `metadata.version`; legacy provider builds keep the top-level key.
  */
 export function readSkillFrontmatterVersion(content) {
-  const fm = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  const fm = String(content).match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---(?:[ \t]*\r?\n|[ \t]*$)/);
   if (!fm) return null;
-  const line = fm[1].match(/^version:\s*(.+)/m);
-  return line ? line[1].trim().replace(/^['"]|['"]$/g, '') : null;
+
+  let metadataVersion = null;
+  let topLevelVersion = null;
+  let inMetadata = false;
+  let metadataIndent = null;
+
+  for (const line of fm[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    const indentText = line.match(/^[ \t]*/)[0];
+    const indent = indentText.replace(/\t/g, '  ').length;
+
+    if (indent === 0) {
+      inMetadata = /^metadata:\s*(?:#.*)?$/.test(line);
+      metadataIndent = null;
+      const version = line.match(/^version:\s*(.+?)\s*$/);
+      if (version) topLevelVersion = version[1];
+      continue;
+    }
+
+    if (!inMetadata) continue;
+    if (metadataIndent === null) metadataIndent = indent;
+    if (indent !== metadataIndent) continue;
+    const version = line.trim().match(/^version:\s*(.+?)\s*$/);
+    if (version) metadataVersion = version[1];
+  }
+
+  const value = metadataVersion || topLevelVersion;
+  return value ? value.trim().replace(/^(["'])(.*)\1$/, '$2') : null;
 }
 
 /**