fix(cli): transform codex marketplace skills

aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/phase-1.md

@@ -0,0 +1,51 @@
+---
+status: done
+---
+
+# Instruction: Apply and prove skill transformation
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+✏️ cli/src/application/use-cases/framework/strategies/marketplace-build-strategy.ts
+✏️ cli/src/application/use-cases/framework/strategies/marketplace-strategy-helpers.ts
+✏️ cli/src/application/use-cases/framework/strategies/tool-contracts.ts
+✏️ cli/src/domain/tools/ai/codex.ts
+✏️ cli/tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[Framework source skill] --> B[Codex marketplace build]
+  B --> C[Codex-transformed SKILL.md]
+  C --> D[Native marketplace artifact]
+```
+
+## Tasks to do
+
+### `1)` Reuse the Codex skill converter during marketplace builds
+
+> Route markdown skill files through the target artifact transform after link rewriting.
+
+1. Extend the marketplace skill-tree writer to receive and apply the skill artifact transform.
+2. Expose or extract the existing Codex frontmatter allowlist as the build transform's source of truth.
+3. Configure the Codex marketplace contract to transform skill markdown while preserving non-markdown assets and existing link rewriting.
+
+### `2)` Lock the regression with an integration test
+
+> Assert the native Codex marketplace artifact omits `model` and unsupported frontmatter.
+
+1. Add a fixture-backed test covering a skill with Claude model metadata.
+2. Assert supported Codex frontmatter remains and `model` is absent.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| --- | --- |
+| 1 | A Codex marketplace build emits every markdown skill using the Codex frontmatter allowlist, while source skills remain unchanged. |
+| 2 | The build integration suite fails if a native Codex marketplace `SKILL.md` contains `model`. |

aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/phase-2.md

@@ -0,0 +1,47 @@
+---
+status: done
+---
+
+# Instruction: Verify installed origin marketplace
+
+## Architecture projection
+
+> Tree of the final files. ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[Build current origin] --> B[Install its Codex marketplace]
+  B --> C[Inspect installed skills]
+  C --> D[No model frontmatter]
+```
+
+## Tasks to do
+
+### `1)` Build and test the current origin
+
+> Run the targeted regression suite and create a fresh Codex marketplace output from this worktree.
+
+1. Run the Codex marketplace integration tests.
+2. Build a fresh Codex marketplace from the worktree.
+3. Scan the generated `SKILL.md` files for a `model` frontmatter key.
+
+### `2)` Install and identify the local origin artifact
+
+> Use Codex to install the marketplace generated from this worktree in an isolated Codex home, then inspect installed skills and marketplace metadata.
+
+1. Install from a local artifact or an origin-addressable ref that names this repository, never the upstream repository.
+2. Assert installed skill files contain no `model` frontmatter key.
+3. Assert installation metadata identifies this origin artifact, not `ai-driven-dev/framework`.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| --- | --- |
+| 1 | The current-worktree Codex marketplace build and targeted integration tests succeed, and generated skills have no `model` key. |
+| 2 | An isolated Codex installation sourced from this origin artifact has no `model` key in installed `SKILL.md` files and carries origin-specific marketplace identity. |

aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/plan.md

@@ -0,0 +1,32 @@
+---
+objective: "Codex marketplace installs from this origin distribute transformed SKILL.md files with no model frontmatter."
+status: reviewed
+---
+
+# Plan: Transform Codex marketplace skills
+
+## Overview
+
+| Field | Value |
+| --- | --- |
+| **Goal** | Make native Codex marketplace output use the same skill-frontmatter conversion as the AIDD CLI install path. |
+| **Source** | [upstream issue #570](https://github.com/ai-driven-dev/framework/issues/570) |
+
+## Phases
+
+| # | Phase | File |
+| --- | --- | --- |
+| 1 | Apply and prove skill transformation | [phase-1.md](./phase-1.md) |
+| 2 | Verify installed origin marketplace | [phase-2.md](./phase-2.md) |
+
+## Resources
+
+| Source | Verified |
+| --- | --- |
+| https://github.com/ai-driven-dev/framework/issues/570 | Native Codex marketplace currently bypasses `stripCodexSkillFrontmatter`; installed skills must omit `model`. |
+
+## Decisions
+
+| Decision | Why |
+| --- | --- |
+| Make marketplace skill writes honor each target's existing skill artifact transform. | It reuses the target contract rather than adding a Codex-only branch, keeps Claude source untouched, and makes native marketplace output follow the same conversion policy as the CLI install path. |

aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/review.md

@@ -0,0 +1,34 @@
+# Review: Transform Codex marketplace skills
+
+- **Verdict**: approve
+- **Diff**: `main...20e46f31967a308c795015c975fd89967ba2cdf1 + worktree`
+- **Axes run**: code, functional, relevancy
+- **Date**: 2026-08-03
+- **Findings**: 0 critical, 0 warning, 0 minor
+
+## Phases
+
+### Phase 1 — Apply and prove skill transformation
+
+- [x] A Codex marketplace build emits every `SKILL.md` using the Codex frontmatter allowlist while source skills remain unchanged; auxiliary Markdown assets remain byte-preserved. — `cli/src/application/use-cases/framework/strategies/marketplace-build-strategy.ts:80-84`, `cli/src/application/use-cases/framework/strategies/marketplace-strategy-helpers.ts:93-102`, `cli/src/application/use-cases/framework/strategies/tool-contracts.ts:337-360`, `cli/tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts:227-263`
+- [x] The build integration suite fails if a native Codex marketplace `SKILL.md` contains `model`. — `cli/tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts:227-243`, `cli/tests/fixtures/framework-codex/plugins/aidd-codex-fixture/skills/sample/SKILL.md:1-8`
+
+### Phase 2 — Verify installed origin marketplace
+
+- [x] The current-worktree Codex marketplace build and targeted integration tests succeed, and generated `SKILL.md` files have no `model` key. — `aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/validation.md:3-10`, `aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/validation.md:31-32`; `pnpm vitest run tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts` => `30 passed`
+- [x] An isolated Codex installation sourced from the local artifact has no `model` in installed `SKILL.md` and carries origin-specific marketplace identity. — `aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/validation.md:17-32` (`sourceType: local`, local artifact path, 13 installed `SKILL.md`, scan clean)
+
+## Findings
+
+| Sev | Kind | Phase | Location | Issue | Fix |
+| --- | ---- | ----- | -------- | ----- | --- |
+| — | — | — | — | None. | — |
+
+## Verification
+
+| Metric | Value |
+| --- | --- |
+| Verified | 100% (4/4) |
+| Files checked | `cli/src/application/use-cases/framework/strategies/marketplace-build-strategy.ts`, `cli/src/application/use-cases/framework/strategies/marketplace-strategy-helpers.ts`, `cli/src/application/use-cases/framework/strategies/tool-contracts.ts`, `cli/src/domain/tools/ai/codex.ts`, `cli/tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts`, `cli/tests/fixtures/framework-codex/plugins/aidd-codex-fixture/skills/sample/SKILL.md`, `cli/tests/fixtures/framework-codex/plugins/aidd-codex-fixture/skills/sample/assets/template.md`, `aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/validation.md` |
+| Unchecked | none |
+| Unplanned | `aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/review.md` is the required review deliverable; none otherwise |

aidd_docs/tasks/2026_08/2026_08_03_codex-marketplace-skill-transform/validation.md

@@ -0,0 +1,32 @@
+# Native Codex installation validation
+
+Observed on 2026-08-03 from a locally built marketplace artifact:
+
+```json
+{
+  "marketplaceName": "aidd-framework",
+  "installedRoot": "/private/tmp/aidd-codex-marketplace.EOuI9t/marketplace",
+  "alreadyAdded": false
+}
+```
+
+Installed plugin identity:
+
+```json
+{
+  "pluginId": "aidd-context@aidd-framework",
+  "installedPath": "/tmp/aidd-codex-marketplace.EOuI9t/home/.codex/plugins/cache/aidd-framework/aidd-context/2.5.0",
+  "source": {
+    "source": "local",
+    "path": "/private/tmp/aidd-codex-marketplace.EOuI9t/marketplace/plugins/aidd-context"
+  },
+  "marketplaceSource": {
+    "sourceType": "local",
+    "source": "/private/tmp/aidd-codex-marketplace.EOuI9t/marketplace"
+  }
+}
+```
+
+`sourceType: "local"` and the temporary artifact path prove this is not the upstream
+`ai-driven-dev/framework` marketplace. The installed cache contained 13 `SKILL.md` files;
+the completed `^model:` scan returned no matches.

cli/src/application/use-cases/framework/strategies/marketplace-build-strategy.ts

@@ -78,9 +78,10 @@ export class MarketplaceBuildStrategy implements BuildOutputStrategy {
   }
 
   async writeSkills(pluginName: string, pluginSrc: string, outDir: string): Promise<number> {
-    if (!this.contract.artifacts.skills.supported) return 0;
+    const artifact = this.contract.artifacts.skills;
+    if (!artifact.supported) return 0;
     const pluginOut = join(outDir, "plugins", pluginName);
-    return writeSkillTree(this.fs, pluginName, pluginSrc, pluginOut);
+    return writeSkillTree(this.fs, pluginName, pluginSrc, pluginOut, artifact.transform);
   }
 
   async writeHooks(pluginName: string, pluginSrc: string, outDir: string): Promise<number> {

cli/src/application/use-cases/framework/strategies/marketplace-strategy-helpers.ts

@@ -1,15 +1,17 @@
-import { join, relative } from "node:path";
+import { basename, join, relative } from "node:path";
 import { InvalidSourceMarketplaceError } from "../../../../domain/errors.js";
 import { rewriteRelativeLinks } from "../../../../domain/formats/relative-link-rewrite.js";
 import {
   PLUGIN_AGENT_INPUT_EXT,
   PLUGIN_HOOKS_RELATIVE,
   PLUGIN_MCP_RELATIVE,
+  PLUGIN_SKILL_ENTRY_FILE,
 } from "../../../../domain/models/framework-build.js";
 import type { FileReader } from "../../../../domain/ports/file-reader.js";
 import type { FileWriter } from "../../../../domain/ports/file-writer.js";
 import { assertNoToolsPlaceholder } from "../shared-plugin-helpers.js";
 
+type SkillContentTransform = (content: string, plugin: string, basename: string) => string;
 export interface PluginPresenceFlags {
   readonly hasAgents: boolean;
   /** Agent markdown files relative to the plugin's `agents/` dir (e.g. "planner.md"), sorted. */
@@ -40,7 +42,11 @@ export async function listSkillNames(
   const files = await fs.listFilesRecursive(skillsDir);
   const names = new Set<string>();
   for (const f of files) {
-    if (!f.endsWith("/SKILL.md") && !f.endsWith("\\SKILL.md") && !f.endsWith("SKILL.md")) {
+    if (
+      !f.endsWith(`/${PLUGIN_SKILL_ENTRY_FILE}`) &&
+      !f.endsWith(`\\${PLUGIN_SKILL_ENTRY_FILE}`) &&
+      !f.endsWith(PLUGIN_SKILL_ENTRY_FILE)
+    ) {
       continue;
     }
     const rel = relative(skillsDir, f);
@@ -66,14 +72,15 @@ export async function writeSkillTree(
   fs: FileReader & FileWriter,
   pluginName: string,
   pluginSrc: string,
-  pluginOut: string
+  pluginOut: string,
+  transform?: SkillContentTransform
 ): Promise<number> {
   const skillsSrc = join(pluginSrc, "skills");
   if (!(await fs.fileExists(skillsSrc))) return 0;
   const files = await fs.listFilesRecursive(skillsSrc);
   let count = 0;
   for (const absPath of files) {
-    count += await writeSkillFile(fs, pluginName, absPath, skillsSrc, pluginOut);
+    count += await writeSkillFile(fs, pluginName, absPath, skillsSrc, pluginOut, transform);
   }
   return count;
 }
@@ -83,18 +90,26 @@ async function writeSkillFile(
   pluginName: string,
   absPath: string,
   skillsSrc: string,
-  pluginOut: string
+  pluginOut: string,
+  transform?: SkillContentTransform
 ): Promise<number> {
   const relPath = relative(skillsSrc, absPath).replace(/\\/g, "/");
   const destPath = join(pluginOut, "skills", relPath);
   const content = await fs.readFile(absPath);
-  if (absPath.endsWith(".md")) {
-    assertNoToolsPlaceholder(content, pluginName, relPath);
-    const currentFilePluginRelative = `skills/${relPath}`;
-    await fs.writeFile(destPath, rewriteRelativeLinks(content, { currentFilePluginRelative }));
-  } else {
+  if (!absPath.endsWith(".md")) {
     await fs.writeFile(destPath, content);
+    return 1;
   }
+
+  assertNoToolsPlaceholder(content, pluginName, relPath);
+  const rewritten = rewriteRelativeLinks(content, {
+    currentFilePluginRelative: `skills/${relPath}`,
+  });
+  let output = rewritten;
+  if (transform && basename(absPath) === PLUGIN_SKILL_ENTRY_FILE) {
+    output = transform(rewritten, pluginName, PLUGIN_SKILL_ENTRY_FILE);
+  }
+  await fs.writeFile(destPath, output);
   return 1;
 }
 

cli/src/application/use-cases/framework/strategies/tool-contracts.ts

@@ -57,7 +57,10 @@ import {
 } from "../../../../domain/models/framework-build.js";
 import type { FileReader } from "../../../../domain/ports/file-reader.js";
 import type { FileWriter } from "../../../../domain/ports/file-writer.js";
-import { mergeCodexConfigToml } from "../../../../domain/tools/ai/codex.js";
+import {
+  mergeCodexConfigToml,
+  stripCodexSkillFrontmatter,
+} from "../../../../domain/tools/ai/codex.js";
 import { transformMcpToOpencode } from "../../../../domain/tools/ai/opencode.js";
 import type { PluginPresence, ToolBuildContract } from "../../../../domain/tools/build-contract.js";
 import {
@@ -331,6 +334,11 @@ function buildCodexManifest(
   return manifest;
 }
 
+function transformCodexSkill(content: string): string {
+  const { frontmatter, body } = parseFrontmatter(content);
+  return serializeFrontmatter(stripCodexSkillFrontmatter(frontmatter), body);
+}
+
 export function buildCodexContract(): ToolBuildContract {
   const manifestRelative = OUTPUT_CODEX_MANIFEST_RELATIVE;
   const marketplaceRelative = OUTPUT_CODEX_MARKETPLACE_RELATIVE;
@@ -348,6 +356,7 @@ export function buildCodexContract(): ToolBuildContract {
         supported: true,
         source: { kind: "fullTree", srcDir: "skills" },
         path: (_p, rel) => rel,
+        transform: transformCodexSkill,
       },
       agents: {
         supported: true,

cli/src/domain/models/framework-build.ts

@@ -70,6 +70,7 @@ export const OUTPUT_MARKETPLACE_RELATIVE = ".plugin/marketplace.json";
 export const PLUGIN_HOOKS_RELATIVE = "hooks/hooks.json";
 export const PLUGIN_MCP_RELATIVE = ".mcp.json";
 export const PLUGIN_AGENT_INPUT_EXT = ".md";
+export const PLUGIN_SKILL_ENTRY_FILE = "SKILL.md";
 
 /** Subdirectory names that are out-of-scope for MVP1 and receive a warn+skip. */
 export const OUT_OF_SCOPE_PLUGIN_SECTIONS: readonly ["commands", "rules"] = ["commands", "rules"];

cli/src/domain/tools/ai/codex.ts

@@ -173,7 +173,7 @@ function buildCodexSkillFilePath(fileName: string): string {
   return `${AGENTS_SKILLS_PREFIX}aidd-${skillNameFromPath(fileName)}/SKILL.md`;
 }
 
-function stripCodexSkillFrontmatter(fm: Record<string, unknown>): Record<string, unknown> {
+export function stripCodexSkillFrontmatter(fm: Record<string, unknown>): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   if (fm.name !== undefined) result.name = fm.name;
   if (fm.description !== undefined) result.description = fm.description;

cli/tests/application/use-cases/framework/marketplace-build-strategy.codex.integration.test.ts

@@ -9,6 +9,7 @@ import {
   InvalidBuildPathsError,
   JsonSchemaValidationError,
 } from "../../../../src/domain/errors.js";
+import { parseFrontmatter } from "../../../../src/domain/formats/markdown.js";
 import { parseToml } from "../../../../src/domain/formats/toml.js";
 import type { AssetProvider } from "../../../../src/domain/ports/asset-provider.js";
 import { AjvSchemaValidatorAdapter } from "../../../../src/infrastructure/adapters/ajv-schema-validator-adapter.js";
@@ -223,6 +224,44 @@ describe("CodexOutputStrategy", () => {
   });
 
   describe("skill rewrite (AC #6)", () => {
+    it("uses the skill frontmatter allowlist without changing the source", async () => {
+      const fs = await makeSeededFsFromCodex();
+      const sourcePath = `${CODEX_FIXTURE_DIR}/plugins/aidd-codex-fixture/skills/sample/SKILL.md`;
+      const sourceBefore = await fs.readFile(sourcePath);
+      const uc = makeUseCase(fs);
+
+      await uc.execute({ sourceDir: CODEX_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
+
+      const output =
+        fs.getFile(`${OUT_DIR}/plugins/aidd-codex-fixture/skills/sample/SKILL.md`) ?? "";
+      expect(parseFrontmatter(output).frontmatter).toEqual({
+        name: "sample",
+        description: "Sample skill for testing reference rewriting.",
+        allowed_tools: ["Read"],
+      });
+      expect(output).not.toMatch(/^model:/m);
+      expect(await fs.readFile(sourcePath)).toBe(sourceBefore);
+    });
+
+    it("preserves auxiliary Markdown frontmatter", async () => {
+      const fs = await makeSeededFsFromCodex();
+      const sourcePath = `${CODEX_FIXTURE_DIR}/plugins/aidd-codex-fixture/skills/sample/assets/template.md`;
+      const source = await fs.readFile(sourcePath);
+      const uc = makeUseCase(fs);
+
+      await uc.execute({ sourceDir: CODEX_FIXTURE_DIR, outDir: OUT_DIR, target: "codex" });
+
+      const output = fs.getFile(
+        `${OUT_DIR}/plugins/aidd-codex-fixture/skills/sample/assets/template.md`
+      );
+      expect(output).toBe(source);
+      expect(parseFrontmatter(output ?? "").frontmatter).toEqual({
+        name: "template",
+        model: "opus",
+        custom: "keep-this",
+      });
+    });
+
     it("rewrites @./ references in skill SKILL.md to markdown links", async () => {
       const fs = await makeSeededFsFromCodex();
       const uc = makeUseCase(fs);