Skip to content

fix(codex): suppress structured skill handoff blocks in normal console output #375

Description

@pitimon

Context

The structured-output protocol currently asks producer skills such as /requirements, /design, /breakdown, and /review-ai to append blocks like:

[/requirements] COMPLETE SKILL_OUTPUT:requirements
<!-- SKILL_OUTPUT:requirements
...
END_SKILL_OUTPUT -->

This is reasonable for downstream skill handoff: cross-verify can parse the metadata.

Codex integration problem

When these skills are used through Codex, the console/transcript exposes the raw HTML comment and the visible attribution line to the end user. Markdown comments are not hidden in that surface, so every requirements/review interaction can emit a large YAML-like internal metadata block.

This is not sensitive data by itself, but it is noisy, confuses users, and weakens the intended concise output of the Significance profile.

Reproduction

  1. Use /requirements through Codex on a multi-file change.
  2. Observe the skill response in the Codex console/transcript.
  3. The SKILL_OUTPUT:requirements attribution and HTML-comment payload are rendered as ordinary output instead of remaining invisible metadata.

Expected

  • Normal Codex user-facing output should contain the concise human summary only.
  • Structured handoff metadata should remain available to a real consumer such as /cross-verify, but should not be printed when no consumer needs it.

Suggested compatibility-safe options

  1. Emit SKILL_OUTPUT only when a consumer is explicitly requested or artifacts are persisted.
  2. Add a Codex-aware output mode that stores handoff metadata in a local artifact/session channel rather than response text.
  3. At minimum, make the visible attribution line optional and document the renderer limitation.

Please preserve the existing Claude/Markdown workflow where HTML comments are actually hidden. This looks like a cross-runtime output-contract mismatch rather than a defect in the requirements content itself.

Evidence

  • skills/requirements/SKILL.md requires the structured output block at the end of the result.
  • guides/structured-output-protocol.md says the HTML comment is invisible when rendered.
  • In Codex console it is visibly rendered verbatim.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions