feat: Codex-compatible skills distribution (spike)

[adunn08]

Summary

Spike: a repeatable, dependency-free build step that produces a Codex-compatible distribution of the skills catalog under dist/codex/, plus a feasibility writeup. Lane was limited to scripts/build-codex.mjs and dist/codex/**; nothing else was touched.

Skill count

• 102 skills in source (skills/<name>/SKILL.md); 102 emitted to dist/codex/.agents/skills/.
• 488 reference files copied byte for byte (nested ref subtrees preserved).

Validation results

Run node scripts/build-codex.mjs -- all checks PASS:

• [PASS] A. every emitted SKILL.md has non-empty name + description (102 ok)
• [PASS] B. emitted skill count equals source (source=102 emitted=102)
• [PASS] C. every source references file has an emitted counterpart
• [PASS] D. no emitted frontmatter has keys beyond name/description

Frontmatter normalization

Every source skill carries 5 uniform keys. The build keeps the portable core (name, description) on each emitted SKILL.md and moves the rest -- category, catalog_summary, display_order -- into a per-skill sidecar references/_claude-frontmatter-extras.yaml. Fully reversible; SKILL.md bodies are left byte-identical.

MCP template note

dist/codex/agents/openai.yaml is a commented template listing detected MCP servers with placeholder url/name/transport fields for the operator to fill in. No real server config is fabricated. Detected: Ahrefs MCP (7 skills, the SEO audit suite), Similarweb, plus Chrome/Playwright/Windows/Linear/GitHub (integration-orchestrator examples), and 7 generic MCP mentions flagged for operator review.

Feasibility

Mechanically straightforward and low risk: a reversible, dependency-free transform yields a clean .agents/skills/ tree for all 102 skills, with the only real integration work being operator-supplied MCP server config.

See dist/codex/PORT_NOTES.md for the full writeup.

🤖 Generated with Claude Code

[adunn08]

Phase 2: verification + hardening (automated results)

New commit e467201 extends the build and verifies discovery. Nothing outside the lane (scripts/build-codex.mjs, dist/codex/**) was touched.

Gating checks: all PASS

node scripts/build-codex.mjs:

• Validation A-E PASS: name/description present, count 102 == 102, all references present, frontmatter clean, and (new) every emitted description within Codex's 1024-char cap.
• Determinism PASS: building twice yields byte-identical generated output.
• openai.yaml sanity PASS: file present; all 7 detected MCP servers (Ahrefs, Similarweb, Chrome, Playwright, Windows, Linear, GitHub) appear as commented entries; no uncommented urls/keys/tokens.

node scripts/build-codex.mjs --check PASS: committed dist/codex is in sync with a fresh rebuild (drift guard).

Real Codex CLI discovery (best effort, done)

Verified against installed codex-cli 0.118.0 (logged in). Loaded the emitted .agents/ tree via codex exec --cd <scratch> --skip-git-repo-check -s read-only with RUST_LOG=info:

• Found a real blocker: 3 skills (creative-direction, integration-orchestrator, logo-design) originally failed to load with invalid description: exceeds maximum length of 1024 characters.
• Fixed in-lane: the build now truncates over-cap descriptions at a sentence boundary and preserves the full original in the sidecar (description_full), fully reversible. After the fix, all 102 skills load with zero parse errors.
• The subsequent model turn errored on an account/model mismatch (gpt-5.3-codex not allowed on a ChatGPT account) - unrelated to discovery, which completed first.

Discovery audit (heuristic)

dist/codex/SKILL_DISCOVERY_AUDIT.md: 6/8 fixture prompts place the expected skill in the top 3. 2 low-confidence (brand-archetype-system, experiment-design) from overlapping vocabulary; 3 skills lack an explicit "use when / triggers on" cue. Labeled heuristic throughout - it is a token-overlap proxy, not a runtime test.

One remaining gate before merge

The authoritative check is the owner's live smoke test (recipe in dist/codex/PORT_NOTES.md): drop .agents into a scratch Codex workspace, prompt "write a creative brief", and confirm creative-brief loads and shapes the output. Leaving this PR as a draft pending that.