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

> Discover how the Compound Engineering Plugin truncates Codex skill descriptions to 1024 characters and preserves prompt bodies when converting Claude Code plugins. Understand the mechanics for optimal performance.

- Repository: [Every/compound-engineering-plugin](https://github.com/everyinc/compound-engineering-plugin)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) |
| Prompt generation | [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) (function `renderPrompt`) |
| Generic output truncation (PI only) | [`src/templates/pi/compat-extension.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/templates/pi/compat-extension.ts) |
| Codex specification reference | [`docs/specs/codex.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts):

```typescript
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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()`:
  ```typescript
  const description = sanitizeDescription(
    agent.description ?? `Converted from Claude agent ${agent.name}`,
  )
  ```

- **Command-skill conversion** in `convertCommandSkill()`:
  ```typescript
  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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/SKILL.md) file.

### Example Output

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

```markdown
---
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) generates a Markdown file with frontmatter and the full command text:

```typescript
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/templates/pi/compat-extension.ts), but it plays **no role** in Codex conversion:

```typescript
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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/targets/codex.ts) |
| Codex type definitions | [`src/types/codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/types/codex.ts) |
| Claude-to-Codex conversion logic | [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) |
| Pi compatibility truncation (unused for Codex) | [`src/templates/pi/compat-extension.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/templates/pi/compat-extension.ts) |
| Codex specification (500-char limit) | [`docs/specs/codex.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/specs/codex.md) |

## Summary

- **Skill descriptions** are automatically truncated to **1,024 characters** by `sanitizeDescription()` in [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts). However, remember that the official Codex specification documented in [`docs/specs/codex.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/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.