bug: suite skill layout does not reduce Codex context because nested SKILL.md files are registered recursively

[wangjinwen1]

Summary

lark-cli update --skills-layout suite successfully switches the installed
filesystem layout, but it does not achieve the context-reduction goal described
in #1392 when used with Codex Desktop.

The generated suite still contains one SKILL.md for every nested domain:

lark-suite/
  SKILL.md
  references/
    lark-doc/
      SKILL.md
    lark-im/
      SKILL.md
    lark-calendar/
      SKILL.md
    ...

Codex discovers these nested SKILL.md files as separate skills. As a result,
the session registers lark-suite in addition to the original domain skills,
rather than registering only one umbrella skill.

This means the suite layout can consume slightly more always-loaded skill
metadata than the separate layout.

Environment

• OS: Windows
• Agent: Codex Desktop
• lark-cli: 1.0.92
• Skills root: ~/.agents/skills
• Layout command:

lark-cli update --skills-layout suite

Steps to reproduce

1. Start with the separate layout:

lark-cli update --skills-layout separate

2. Start a fresh Codex session and inspect the registered Lark skills.

3. Switch to the suite layout:

lark-cli update --skills-layout suite

4. Confirm that the top-level standalone official skill directories were
   removed.

5. List the nested skill entrypoints:

Get-ChildItem "$HOME\.agents\skills\lark-suite" `
  -Recurse `
  -Filter SKILL.md |
  Select-Object -ExpandProperty FullName

6. Start a fresh Codex session and inspect the registered skills again.

Actual behavior

The layout switch itself succeeds and the old top-level official skill
directories are removed.

However, Codex registers the nested files under paths such as:

lark-suite/references/lark-doc/SKILL.md
lark-suite/references/lark-im/SKILL.md
lark-suite/references/lark-calendar/SKILL.md

The resulting catalog contains:

• lark-suite
• the nested Lark domain skills
• any unrelated user-installed skills

In my measurement:

Layout	Registered skill entries	Frontmatter name + description
separate	29, including one unrelated user skill	9,307 characters
suite	30, including one unrelated user skill	10,049 characters

Therefore, switching to suite increased the always-loaded metadata by
approximately 8% in this Codex installation.

The exact character count may change as skill descriptions evolve, but the
structural problem is that the nested domain entrypoints are still registered.

Expected behavior

The suite layout should expose only one registered Lark skill:

lark-suite

Domain guides should be loaded only after the suite router selects a domain.
They should not contribute separate name and description entries to every
session.

Regression from the original proposal

Issue #1392 explicitly proposed renaming nested domain entrypoints from
SKILL.md to GUIDE.md:

SKILL.md renamed to GUIDE.md so harnesses that scan recursively never
re-register the nested copies as standalone skills.

The implementation merged in #2211 instead keeps nested files named
SKILL.md. This defeats that compatibility measure for recursive skill
discovery.

#2211 tests layout installation, switching, cleanup, rollback, state
persistence, and archive handling, but its test plan does not appear to verify
the final skill catalog seen by Codex or the resulting always-loaded metadata.

Suggested fix

Generate the suite using non-entrypoint filenames for nested domains, for
example:

lark-suite/
  SKILL.md
  references/
    lark-doc/
      GUIDE.md
    lark-im/
      GUIDE.md
    lark-calendar/
      GUIDE.md

Update router and cross-domain references accordingly.

Alternatively, place the domain guides somewhere that supported agent
harnesses cannot interpret as independently registered skills.

Acceptance criteria

• After lark-cli update --skills-layout suite, Codex registers exactly one
  official Lark skill: lark-suite.
• No nested domain guide is registered as an independent skill.
• The suite router can still load every domain guide and its references.
• Switching between separate and suite remains reversible.
• User-deleted official skills and user-owned skills remain preserved according
  to the existing behavior.
• An automated test verifies the discoverable skill catalog, not only the
  installed directory layout.
• A regression test confirms that suite metadata is materially smaller than
  separate-layout metadata.

Related

• Proposal: ship a single umbrella skill (router + on-demand domain guides) to cut the always-on agent context cost of 26 skills #1392
• feat: support separate and suite skill layouts #2211
• Feature request: minimal / selective skill install mode #772
• Skills 全局注入 27 个 skill 挤占 agent 上下文空间，建议改为渐进式披露 #1848