Codex review: needs maintainer review before merge. Reviewed July 9, 2026, 3:17 PM ET / 19:17 UTC.

Summary
The PR changes compact skills prompt formatting to keep name/location/version identities first, allocate remaining prompt budget to bounded descriptions, bump the skills prompt format version, and update tests/docs.

PR surface: Source +52, Tests +24, Docs +3. Total +79 across 4 files.

Reproducibility: yes. Current main source shows compact fallback omits all descriptions when full formatting exceeds the prompt budget, and the PR proof exercises the changed compact prompt path with live agent runs.

Review metrics: 1 noteworthy metric.

• Prompt format marker: 1 changed. Changing WORKSPACE_SKILLS_PROMPT_FORMAT_VERSION intentionally refreshes persisted skills snapshots after upgrade.

Root-cause cluster
Relationship: partial_overlap
Canonical: #50677
Summary: This PR addresses the compact-description part of the broader silent skills truncation problem; another open PR handles omitted-key visibility.

Members:

• canonical: Skills silently truncated - user-created skills invisible with no warning or prioritization #50677 - The open issue tracks the broader skills prompt truncation problem and includes description loss, omitted visibility, and prioritization remedies.
• partial_overlap: fix(skills): list omitted skill names when prompt is truncated #42637 - The other open PR addresses omitted skill key visibility rather than compact description preservation.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Risk before merge

• [P1] Existing tight skills.limits.maxSkillsPromptChars or per-agent skillsLimits.maxSkillsPromptChars setups will receive a changed compact prompt shape after merge.
• [P1] The prompt format marker bump intentionally refreshes persisted skills snapshots, so this is session-state-sensitive even though the refresh path is covered.
• [P1] The live PR is mergeable but behind current main, so the final merge result should still pass normal maintainer gates before landing.

Maintainer options:

1. Land After Exact-Head Gates (recommended)
   Accept the changed compact prompt shape once the final merge result passes normal maintainer checks.
2. Rebase Or Queue First
   Refresh the branch against current main if maintainers want CI and review evidence on the exact final merge base before landing.
3. Pause For Broader Skills Policy
   Hold the PR if maintainers want compact descriptions decided together with omitted-skill keys, priority, pinning, or smart indexing.

Next step before merge

• Maintainer should decide whether to accept the compatibility/session refresh risk and land after exact-head gates; no automated repair is needed.

Maintainer decision needed

• Question: Should maintainers accept the compact skills prompt shape and session snapshot refresh risk now, or hold this for broader skills truncation policy?
• Rationale: The implementation is narrow and proven, but it changes model-visible prompt bytes and refreshes persisted skills snapshots for existing users with tight skill prompt budgets.
• Likely owner: steipete — steipete authored the maintainer rewrite/proof commit and is the current assignee for the PR.
• Options:
  • Land Narrow Formatter Fix (recommended): Accept the compatibility/session refresh risk because the patch preserves identity coverage first and has focused, changed-surface, and live prompt proof.
  • Refresh Exact-Head Gates First: Require a rebase or merge-queue run if maintainers want current-main CI on the final merge result before accepting the prompt change.
  • Pause For Broader Skills Policy: Hold this PR only if compact descriptions should be bundled with omitted-key recovery, priority, pinning, or smart skill indexing decisions.

Security
Cleared: Security review cleared: the diff changes skills prompt formatting, tests, docs, and a format-version constant only, with no dependency, workflow, secret, package, or code-execution surface added.

The adaptive compact-description sizing is a nice idea. One tiny edge case to think about: truncateSkillDescription() slices UTF-16 code units, so a description containing emoji / some non-BMP characters could get split mid-surrogate when the compact budget lands in the middle of one. Probably rare, but if skill descriptions are user-authored it may be worth truncating on code points/graphemes instead of raw .slice().

@abel-zer0 thanks for the PR. ClawSweeper is still waiting on real behavior proof before this can move forward.

Useful proof can be a screenshot, short video, terminal output, copied live output, linked artifact, or redacted logs that show the changed behavior after the fix. Please redact private tokens, phone numbers, private endpoints, customer data, and anything else sensitive.

Once proof is added to the PR body or a comment, ClawSweeper or a maintainer can re-check it.

Maintainer takeover is complete at exact head 3bf7b9967330af23b8db52c175192442da3cf178.

Best-fix review: the rewritten patch keeps current main's version markers and session refresh, preserves the prior compact identity set before allocating description budget, accounts for the complete rendered notice, and uses the shared UTF-16-safe truncator. No sibling compact-prompt path needs a parallel change.

Proof:

• Focused sanitized AWS run run_3ff6ad25c73e:
  pnpm test src/skills/loading/compact-format.test.ts src/skills/runtime/session-snapshot.test.ts
  — 2 files, 31 tests passed.
• Changed-surface sanitized AWS run run_1eeb815a2313:
  pnpm check:changed -- docs/tools/skills.md src/skills/loading/compact-format.test.ts src/skills/loading/workspace.ts src/skills/types.ts
  — core, core-tests, and docs lanes passed, including core/core-test tsgo and changed-file lint.
• Real behavior sanitized AWS run run_b4518917d9ec: two openclaw agent --local turns reached the repository mock /v1/responses provider. The roomy compact turn rendered 29 identities, 29 versions, and 29 bounded descriptions in 11,459/18,000 chars; all 12 long fixtures retained descriptions and the deliberate emoji boundary remained UTF-16-safe. The exact-tight turn rendered the same 29 identity/version records in 6,107/6,107 chars, zero descriptions, and byte-identical XML after removing only the roomy description lines.
• Source-blind behavior validation against the captured artifact: 6/6 contract clauses and 5/5 anti-cheat probes passed.
• Touched files formatted; git diff --check passed.
• Fresh autoreview and independent final review: clean, no accepted/actionable findings.

Known proof gaps: none. The source head is frozen; failed earlier live attempts were assertion-harness calibration only, while every underlying real agent/provider turn completed successfully.

@clawsweeper re-review

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Merged via squash.

• Prepared head SHA: 3bf7b9967330af23b8db52c175192442da3cf178
• Landed commit: b47405954e1b8e4506554f0337f55383694ecf87