How Prompt and Skill Truncation Works for Codex in the Compound Engineering Plugin

When converting Claude Code plugins to Codex bundles, the Compound Engineering Plugin automatically truncates skill descriptions to 1,024 characters while leaving prompt bodies completely untouched.

The EveryInc/compound-engineering-plugin bridges Claude Code extensions and OpenAI's Codex CLI format. Understanding how prompt and skill truncation for Codex operates is essential when migrating large agent descriptions or lengthy command prompts, as the plugin applies selective size limits only to specific metadata fields.

Where the Truncation Logic Lives

Purpose	File Path
Skill description limit	src/converters/claude-to-codex.ts
Prompt generation	src/converters/claude-to-codex.ts (function renderPrompt)
Generic output truncation (PI only)	src/templates/pi/compat-extension.ts
Codex specification reference	docs/specs/codex.md

Skill Description Truncation

The Core Sanitization Function

The plugin enforces a 1,024-character ceiling on all skill descriptions through the sanitizeDescription() function in src/converters/claude-to-codex.ts:

const CODEX_DESCRIPTION_MAX_LENGTH = 1024

function sanitizeDescription(value: string, maxLength = CODEX_DESCRIPTION_MAX_LENGTH): string {
  const normalized = value.replace(/\s+/g, " ").trim()
  if (normalized.length <= maxLength) return normalized
  const ellipsis = "..."
  return normalized
    .slice(0, Math.max(0, maxLength - ellipsis.length))
    .trimEnd() + ellipsis
}

This utility first collapses whitespace runs into single spaces, then truncates with an ellipsis if the content exceeds the limit. The 1,024-character default acts as a safety margin above Codex's official 500-character specification limit documented in docs/specs/codex.md.

Where Descriptions Are Sanitized

The plugin invokes sanitizeDescription() during the conversion of both agents and command skills:

• Agent conversion in convertAgent():

  const description = sanitizeDescription(
    agent.description ?? `Converted from Claude agent ${agent.name}`,
  )

• Command-skill conversion in convertCommandSkill():

  description: sanitizeDescription(
    command.description ?? `Converted from Claude command ${command.name}`,
  ),

In both cases, the resulting string is injected into the frontmatter of the generated SKILL.md file.

Example Output

A Claude agent with a 1,500-character description would yield a Codex skill file containing:

---
description: "Lorem ipsum dolor sit amet...(first 1021 chars)..."
---

The ellipsis clearly indicates truncation occurred, preventing silent data loss while respecting the provider's constraints.

Prompt Handling – No Truncation Applied

Unlike skill metadata, prompt bodies are never truncated by the plugin. The renderPrompt() function in src/converters/claude-to-codex.ts generates a Markdown file with frontmatter and the full command text:

const prompts = invocableCommands.map((command) => {
  const promptName = uniqueName(normalizeName(command.name), promptNames)
  const commandSkill = convertCommandSkill(command, usedSkillNames)
  const content = renderPrompt(command, commandSkill.name)
  return { name: promptName, content }
})

The content string is written directly to prompts/<name>.md without length checks. If a prompt exceeds Codex's internal limits, the failure occurs at runtime during Codex CLI execution, not during bundle generation. This design preserves the integrity of complex prompts that users may manually optimize after conversion.

The Unrelated truncate() Helper

The repository contains a generic truncation utility in src/templates/pi/compat-extension.ts, but it plays no role in Codex conversion:

function truncate(value: string): string {
  const input = value ?? ""
  if (Buffer.byteLength(input, "utf8") <= MAX_BYTES) return input
  const head = input.slice(0, MAX_BYTES)
  return head + "\n\n[Output truncated to 50KB]"
}

This function caps sub-agent stdout/stderr at 50 KB for the Pi compatibility layer. It is never imported or invoked by the Claude-to-Codex converter, so developers should not expect it to affect skill or prompt truncation.

Quick Reference – Key Files

Purpose	File Path
Codex bundle writer	src/targets/codex.ts
Codex type definitions	src/types/codex.ts
Claude-to-Codex conversion logic	src/converters/claude-to-codex.ts
Pi compatibility truncation (unused for Codex)	src/templates/pi/compat-extension.ts
Codex specification (500-char limit)	docs/specs/codex.md

Summary

• Skill descriptions are automatically truncated to 1,024 characters by sanitizeDescription() in src/converters/claude-to-codex.ts, ensuring compatibility with Codex's official 500-character limit.
• Prompt bodies are emitted verbatim without length checks; any size constraints are enforced by the Codex CLI at runtime.
• The truncate() function in src/templates/pi/compat-extension.ts is reserved for Pi sub-agent output and does not affect Codex conversion.
• Conversion logic resides primarily in src/converters/claude-to-codex.ts, which handles both agent and command-skill metadata sanitization.

Frequently Asked Questions

What is the maximum length for skill descriptions in the Codex bundle?

The plugin enforces a 1,024-character ceiling during conversion, which serves as a safety buffer above Codex's official 500-character specification limit. If a Claude agent or command description exceeds this threshold, sanitizeDescription() truncates it and appends an ellipsis.

Are prompt files ever truncated during the Claude-to-Codex conversion?

No. The renderPrompt() function writes prompt bodies to prompts/<name>.md without any length validation. If a prompt exceeds Codex's internal limits, the error will surface at runtime when the Codex CLI attempts to load the file, not during the build process.

Does the truncate() function in compat-extension.ts affect Codex skills or prompts?

No. That utility is specific to the Pi compatibility layer and caps sub-agent stdout/stderr at 50 KB. It is never imported by the Codex converter and therefore has no impact on skill descriptions or prompt generation.

Where can I adjust the description length limit if Codex changes its specification?

You can modify the CODEX_DESCRIPTION_MAX_LENGTH constant in src/converters/claude-to-codex.ts. However, remember that the official Codex specification documented in docs/specs/codex.md currently limits descriptions to 500 characters, so raising the plugin's internal ceiling above 1,024 is not recommended without verifying provider constraints.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}