# How Codex Skill Descriptions Are Truncated to 1024 Characters in Claude-to-Codex Conversion

> Learn how Codex skill descriptions are truncated to 1024 characters using the sanitizeDescription helper in Claude-to-Codex conversion. Discover whitespace normalization and ellipsis appending.

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

---

**Codex skill descriptions are automatically truncated to 1024 characters by the `sanitizeDescription` helper in [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts), which normalizes whitespace and appends an ellipsis when text exceeds the limit.**

When converting Claude plugins to Codex skills in the **EveryInc/compound-engineering-plugin** repository, description fields must comply with Codex's strict 1024-character single-line requirement. The conversion process handles this automatically through a dedicated sanitization function that ensures no generated skill exceeds the platform's limits.

## The 1024-Character Limit and sanitizeDescription Function

The truncation logic centers on a single helper function that enforces the Codex specification. According to the source code in [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts), the constant `CODEX_DESCRIPTION_MAX_LENGTH` is hardcoded to **1024**, representing the maximum allowed characters for any skill description.

### Whitespace Normalization

Before length checking occurs, `sanitizeDescription` collapses all whitespace sequences—including newlines, tabs, and multiple spaces—into single spaces. This guarantees the final output is always a single line, as required by the Codex front-matter specification documented in [`docs/specs/codex.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/specs/codex.md).

### Truncation Logic

If the normalized text exceeds 1024 characters, the function calculates the truncation point as `maxLength - ellipsis.length` (1021 characters) and appends `"..."`. This ensures the final string never exceeds the limit while clearly indicating content was removed.

## Implementation in src/converters/claude-to-codex.ts

The `sanitizeDescription` function is implemented as a pure utility that operates on string inputs:

```typescript
// src/converters/claude-to-codex.ts
const CODEX_DESCRIPTION_MAX_LENGTH = 1024;   // ← limit

function sanitizeDescription(
  value: string,
  maxLength = CODEX_DESCRIPTION_MAX_LENGTH,
): string {
  // 1️⃣ Collapse whitespace & trim
  const normalized = value.replace(/\s+/g, " ").trim();

  // 2️⃣ Return as‑is if under limit
  if (normalized.length <= maxLength) return normalized;

  // 3️⃣ Truncate and add ellipsis
  const ellipsis = "...";
  return (
    normalized.slice(0, Math.max(0, maxLength - ellipsis.length)).trimEnd() +
    ellipsis
  );
}

```

The function uses `Math.max(0, maxLength - ellipsis.length)` to prevent negative slice indices in edge cases, then calls `trimEnd()` to remove any trailing spaces before appending the ellipsis.

## Usage During Claude-to-Codex Conversion

During the conversion process, the `sanitizeDescription` helper is invoked for every agent and command description to ensure compliance before writing the skill file:

```typescript
// Example usage inside the converter
const description = sanitizeDescription(
  agent.description ?? `Converted from Claude agent ${agent.name}`,
);

```

This pattern appears throughout [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts) whenever processing description fields from Claude plugin manifests, ensuring that even user-provided descriptions that exceed the limit are safely handled without breaking the Codex skill format.

## Testing the Truncation Behavior

The truncation logic is verified in [`tests/codex-converter.test.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/tests/codex-converter.test.ts) (lines 75–102), which contains unit tests specifically targeting the description sanitization. These tests confirm that:

- Descriptions exceeding 1024 characters are reduced to exactly 1024 characters including the ellipsis
- No newline characters survive the normalization process
- The output always terminates with `"..."` when truncation occurs

## Summary

- **Hard limit**: Codex skill descriptions are capped at **1024 characters** by the `CODEX_DESCRIPTION_MAX_LENGTH` constant.
- **Sanitization**: 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) normalizes whitespace and enforces the limit.
- **Truncation pattern**: Text exceeding 1024 characters is sliced to 1021 characters and appended with `"..."`.
- **Single-line guarantee**: All whitespace including newlines is collapsed to single spaces before length checking.

## Frequently Asked Questions

### Why is the Codex skill description limit set to 1024 characters?

According to the specification documented in [`docs/specs/codex.md`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/docs/specs/codex.md) at line 45, this limit ensures skill descriptions remain concise and display properly within the Codex interface without causing rendering issues or truncation artifacts in the front-matter header.

### What happens if a description is exactly 1024 characters long?

The `sanitizeDescription` function returns the normalized text unchanged if its length is less than or equal to `CODEX_DESCRIPTION_MAX_LENGTH`. Therefore, an exact 1024-character description passes through without modification, provided it contains no newlines (which would be collapsed to spaces, potentially reducing the length).

### Does the truncation process preserve newlines or formatting?

No. Before any length checking occurs, the function executes `value.replace(/\s+/g, " ")` which collapses all whitespace characters—including newlines, tabs, and carriage returns—into single spaces. This guarantees the final description is always a single line, as required by the Codex skill specification.

### Where can I find the implementation and tests for this truncation logic?

The core implementation resides in [`src/converters/claude-to-codex.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/src/converters/claude-to-codex.ts), specifically the `sanitizeDescription` function and the `CODEX_DESCRIPTION_MAX_LENGTH` constant. Comprehensive unit tests verifying the truncation behavior, whitespace normalization, and ellipsis appending are located in [`tests/codex-converter.test.ts`](https://github.com/EveryInc/compound-engineering-plugin/blob/main/tests/codex-converter.test.ts) at lines 75–102.