garrytan/gstack · error · Error

Codex description for "${name}" is ${description.length} cha

Error message

Codex description for "${name}" is ${description.length} chars (max ${MAX_DESC}). Compress the description in the .tmpl file.

What it means

The Codex-specific frontmatter emitter in scripts/resolvers/codex-helpers.ts:92 enforces a 1024-char description limit (Codex's hard cap). When a .tmpl description exceeds MAX_DESC the build throws rather than shipping a broken skill.

Source

Thrown at scripts/resolvers/codex-helpers.ts:92

 * Strips allowed-tools, hooks, version, and all other fields.
 * Handles multiline block scalar descriptions (YAML | syntax).
 */
export function transformFrontmatter(content: string, host: Host): string {
  if (host === 'claude') return content;

  // Find frontmatter boundaries
  const fmStart = content.indexOf('---\n');
  if (fmStart !== 0) return content; // frontmatter must be at the start
  const fmEnd = content.indexOf('\n---', fmStart + 4);
  if (fmEnd === -1) return content;

  const body = content.slice(fmEnd + 4); // includes the leading \n after ---
  const { name, description } = extractNameAndDescription(content);

  // Codex 1024-char description limit — fail build, don't ship broken skills
  const MAX_DESC = 1024;
  if (description.length > MAX_DESC) {
    throw new Error(
      `Codex description for "${name}" is ${description.length} chars (max ${MAX_DESC}). ` +
      `Compress the description in the .tmpl file.`
    );
  }

  // Re-emit Codex frontmatter (name + description only)
  const indentedDesc = description.split('\n').map(l => `  ${l}`).join('\n');
  const codexFm = `---\nname: ${name}\ndescription: |\n${indentedDesc}\n---`;
  return codexFm + body;
}

/**
 * Extract hook descriptions from frontmatter for inline safety prose.
 * Returns a description of what the hooks do, or null if no hooks.
 */
export function extractHookSafetyProse(tmplContent: string): string | null {
  if (!tmplContent.match(/^hooks:/m)) return null;

View on GitHub (pinned to 94993f7401)

Solutions

1. Compress the description in the .tmpl to a single lead sentence
2. Move detail into body sections (use catalog-mode=trim to auto-shorten)
3. Run a Codex build locally before committing description changes

const MAX_DESC = 1024;
const desc = extractNameAndDescription(content).description;
if (desc.length > MAX_DESC) {
  console.error(`Codex description is ${desc.length} chars (max ${MAX_DESC}); trim the .tmpl`);
  process.exit(2);
}

When it happens

Trigger: Building for the Codex host with a verbose .tmpl description. Adding examples or routing detail into the description field.

Common situations: Multi-host build where Claude tolerates the length but Codex rejects it. Description bloat accumulating across versions. Single-host skill later promoted to multi-host.

Related errors

• ${hostConfig.displayName} description for "${name}" is ${des
• gen-llms-txt: ${t.tmpl} is missing name or description in fr
• Unknown placeholder {{${resolverName}}} in ${relTmplPath}
• Unresolved placeholders in ${relTmplPath}: ${remaining.join(
• diagram-render bundle not found. Tried: ${candidates.map((c)

AI-assisted analysis of garrytan/gstack@94993f7401 (2026-08-12). Data as JSON: /api/errors/246bfe79a9f591e9. Report an issue: GitHub.