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

Codex skill descriptions are automatically truncated to 1024 characters by the sanitizeDescription helper in 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, 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.

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:

// 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:

// 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 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 (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 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 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, 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 at lines 75–102.

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