From 51d9976610ed737658dcb42e9b6eaa1ffaf2b78e Mon Sep 17 00:00:00 2001 From: Charles Wiltgen Date: Sun, 29 Mar 2026 11:28:12 -0700 Subject: [PATCH] fix: address code review issues in Codex build script and docs Build script: - Escape backslashes before quotes in YAML output - Handle Windows-style line endings in frontmatter parsing - Use dir.name (not fm.name) for display_name consistency - Warn when openai.yaml is skipped due to missing frontmatter - Compute actual skipped count from filesystem, not set size Docs: - Add Deno prerequisite - Clarify that axiom-codex/ is created by the build step - Remove unverified $skill-name invocation syntax - Add Troubleshooting section - Improve Also Available with relationship explanations - Change "Not yet supported" to "Not supported" for accuracy --- docs/guide/codex-install.md | 38 +++++++++++++++++++++++++++++-------- scripts/build-codex.ts | 15 +++++++++------ 2 files changed, 39 insertions(+), 14 deletions(-) diff --git a/docs/guide/codex-install.md b/docs/guide/codex-install.md index db14942a..dc3f353f 100644 --- a/docs/guide/codex-install.md +++ b/docs/guide/codex-install.md @@ -19,6 +19,7 @@ The Codex plugin includes 164 specialized skills covering: ## Prerequisites - **Codex CLI** or Codex web app +- **Deno** — required to build the plugin. Check with `deno --version` or install from [deno.com](https://deno.com) ## Installation @@ -36,6 +37,8 @@ cd Axiom npm run build:codex ``` +This creates the `axiom-codex/` directory containing the plugin. Use its full path in the config below. + Add to your personal marketplace at `~/.agents/plugins/marketplace.json`: ```json @@ -91,8 +94,6 @@ Skills activate automatically based on your questions. Just ask: "I need to add a database column safely" ``` -You can also invoke skills explicitly with `$skill-name` in Codex. - ## Updating Pull the latest changes and rebuild: @@ -112,14 +113,35 @@ The Codex plugin includes the same skill content as the Claude Code plugin, with | Feature | Claude Code | Codex | |---------|-------------|-------| | Skills | 164 specialized + 17 routers | 164 specialized (Codex has native routing) | -| Agents | 38 autonomous auditors | Not yet supported in Codex plugins | -| Commands | 12 `/axiom:*` commands | Not yet supported in Codex plugins | +| Agents | 38 autonomous auditors | Not supported in Codex plugins | +| Commands | 12 `/axiom:*` commands | Not supported in Codex plugins | | Installation | `/plugin marketplace add` | Local marketplace | -As the Codex plugin system matures, we'll add support for additional features. +## Troubleshooting + +### `deno: command not found` + +Install Deno from [deno.com](https://deno.com): + +```bash +curl -fsSL https://deno.land/install.sh | sh +``` + +### `axiom-codex/` directory not found + +Run the build step first: + +```bash +cd /path/to/Axiom +npm run build:codex +``` + +### Skills not appearing in Codex + +Verify the path in your `marketplace.json` points to the `axiom-codex/` directory (not the repo root), and that the directory contains `.codex-plugin/plugin.json`. ## Also Available -- **[Claude Code](/guide/quick-start)** — Native plugin with full agent and command support -- **[MCP Server](/guide/mcp-install)** — Works with VS Code, Cursor, Gemini CLI, and more -- **[Xcode Integration](/guide/xcode-setup)** — Direct Xcode MCP bridge setup +- **[Claude Code](/guide/quick-start)** — Full Axiom experience with 38 autonomous agents and 12 commands +- **[MCP Server](/guide/mcp-install)** — Skills in VS Code, Cursor, Gemini CLI, and any MCP-compatible tool; no build step required +- **[Xcode Integration](/guide/xcode-setup)** — Direct Xcode MCP bridge for in-editor assistance diff --git a/scripts/build-codex.ts b/scripts/build-codex.ts index 142f1dfc..a9742128 100644 --- a/scripts/build-codex.ts +++ b/scripts/build-codex.ts @@ -48,10 +48,10 @@ fs.mkdirSync(OUTPUT_MANIFEST, { recursive: true }); // Parse SKILL.md frontmatter (name, description) without external dependencies function parseFrontmatter(content: string): Record { - const match = content.match(/^---\n([\s\S]*?)\n---/); + const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/); if (!match) return {}; const fields: Record = {}; - for (const line of match[1].split('\n')) { + for (const line of match[1].split(/\r?\n/)) { const m = line.match(/^(\w+):\s*(.+)/); if (m) fields[m[1]] = m[2]; } @@ -91,8 +91,8 @@ function toShortDescription(description: string): string { const end = short.search(/\.\s|—|\s-\s/); if (end >= 20) short = short.slice(0, end); if (short.length > 120) short = short.slice(0, 117) + '...'; - // Escape quotes for YAML and trim - short = short.replace(/"/g, '\\"').trim(); + // Escape for YAML double-quoted string (backslashes first, then quotes) and trim + short = short.replace(/\\/g, '\\\\').replace(/"/g, '\\"').trim(); return short.charAt(0).toUpperCase() + short.slice(1); } @@ -117,11 +117,13 @@ for (const dir of skillDirs) { fs.mkdirSync(agentsDir, { recursive: true }); const yaml = [ 'interface:', - ` display_name: "${toDisplayName(fm.name)}"`, + ` display_name: "${toDisplayName(dir.name)}"`, ` short_description: "${toShortDescription(fm.description)}"`, '', ].join('\n'); fs.writeFileSync(path.join(agentsDir, 'openai.yaml'), yaml); + } else { + console.warn(` warn: skipped openai.yaml for ${dir.name} (missing name or description in frontmatter)`); } copied++; @@ -163,5 +165,6 @@ fs.writeFileSync( ); // Summary -const skipped = EXCLUDE_SKILLS.size; +const allDirs = fs.readdirSync(SOURCE_SKILLS, { withFileTypes: true }).filter(d => d.isDirectory()); +const skipped = allDirs.filter(d => EXCLUDE_SKILLS.has(d.name)).length; console.log(`axiom-codex built: ${copied} skills (${skipped} routers excluded), v${version}`);