Fix root skill loading and Codex setup layout

[bitfoundry-ai]

Summary

This PR fixes two related Codex install/load regressions in gstack:

1. The umbrella gstack skill can be skipped by Codex-compatible loaders because its front-matter description exceeds the 1024-character limit enforced by those loaders.
2. ./setup --host codex can overwrite ~/.codex/skills/gstack with the generated wrapper skill directory from .agents/skills/gstack, which breaks access to repo-backed runtime assets such as bin/ and browse/dist/.

Issue 1: root SKILL.md description is too long

What happens

Codex-compatible loaders may reject the root gstack skill with an error like:

invalid description: exceeds maximum length of 1024 characters

That means the umbrella skill is skipped entirely even though the actual skill body is valid.

Why it happens

The root SKILL.md.tmpl front matter embeds a long multi-paragraph description intended to explain routing behavior, proactive suggestions, and opt-out behavior. After generation, the description is about 1972 characters, which exceeds the loader limit.

Repro

1. Clone the repo.
2. Run bun run gen:skill-docs.
3. Install or load the root gstack skill in a Codex-compatible loader.
4. Observe the loader warning that SKILL.md has an invalid description because it exceeds 1024 characters.

Issue 2: Codex setup can replace the repo-backed gstack install with the generated wrapper

What happens

./setup --host codex currently installs generated Codex skills from .agents/skills/gstack* into ~/.codex/skills/. That set includes .agents/skills/gstack, so ~/.codex/skills/gstack can end up pointing at the generated wrapper directory instead of the full repo.

When that happens, paths like these stop being valid:

• ~/.codex/skills/gstack/bin/gstack-config
• ~/.codex/skills/gstack/browse/dist/browse

Why it happens

The helper that links generated Codex skills iterates over gstack*, which includes the umbrella gstack wrapper. That collides with the reserved ~/.codex/skills/gstack location that must point at the full repo for runtime assets.

Repro

1. Clone the repo.
2. Run ./setup --host codex.
3. Inspect readlink ~/.codex/skills/gstack.
4. If it points into .agents/skills/gstack, runtime assets are no longer available from the expected repo-backed path.
5. ls ~/.codex/skills/gstack/bin/gstack-config may fail even though setup reported success.

Fix

Description-limit mitigation

• Shorten the umbrella gstack front-matter description to a concise loader-safe summary.
• Regenerate both the Claude-format and Codex-format root skill files.
• Add a generator guard that fails fast if any generated skill description exceeds the 1024-character loader limit.
• Add regression tests for both Claude and Codex generated skill descriptions.

Codex setup mitigation

• Skip the umbrella gstack wrapper inside link_codex_skill_dirs() so it never claims ~/.codex/skills/gstack.
• Always relink ~/.codex/skills/gstack to the full repo after generated skill links are installed.
• Add regression tests that lock in both of those setup behaviors.

Why this does not reduce effectiveness

• The shortened text is only the front-matter description, which acts as loader metadata.
• The actual skill body, routing logic, preamble, and operational instructions are unchanged.
• Focused child skills such as /qa, /review, /investigate, /office-hours, and /ship retain their detailed trigger descriptions.
• Net effect: better compatibility, no meaningful loss in behavior.

Validation

• bun run scripts/gen-skill-docs.ts --dry-run
• bun run scripts/gen-skill-docs.ts --host codex --dry-run
• bun test test/gen-skill-docs.test.ts
• bun run skill:check

Implementation prompt

Fix two upstream issues in gstack: (1) the root SKILL.md front-matter description exceeds Codex-compatible loaders' 1024-character limit and causes the umbrella skill to be skipped; (2) ./setup --host codex can overwrite ~/.codex/skills/gstack with .agents/skills/gstack, which breaks access to bin/ and browse/dist/. Implement the smallest universal fix that preserves Claude/Cursor behavior, add regression tests for both issues, regenerate generated skill docs, and document exact repro steps plus mitigation in the PR body.

[bitfoundry-ai]

Closing this PR — both fixes are already covered by earlier submissions:

• Issue 1 (root SKILL.md description exceeds 1024-char Codex loader limit): covered by fix: cap gstack skill descriptions for codex #251 and fix(gen-skill-docs): cap Codex skill descriptions at 1024 characters #248
• Issue 2 (setup --host codex overwrites ~/.codex/skills/gstack with generated wrapper): covered by fix: avoid duplicate Codex skill discovery #236

Thanks to @cweill, @amit221, and @shichangs for getting there first. 🤝