Subagent designs and progressive disclosure

[TomLucidor]

Something I observed in BOTH the SKILLS.md trend as well as how Oh-My-OpenAgent operates, is that often times, long prompts are inappropriate if there are ways of doing "progressive disclosure", separating designers and devs from QA https://github.com/code-yeongyu/oh-my-openagent
Progressive disclosure as a design pattern for both humans and LLMs https://en.wikipedia.org/wiki/Progressive_disclosure https://www.nngroup.com/articles/progressive-disclosure/ https://thedecisionlab.com/reference-guide/design/progressive-disclosure
Context management best practices exists I guess for unified-software-engineering https://docs.claude-mem.ai/progressive-disclosure https://medium.com/@martia_es/progressive-disclosure-the-technique-that-helps-control-context-and-tokens-in-ai-agents-8d6108b09289 https://agentskills.io/skill-creation/optimizing-descriptions https://www.humanlayer.dev/blog/writing-a-good-claude-md https://www.decodingai.com/p/llm-knowledge-base-obsidian-readwise-notebooklm https://www.augmentcode.com/blog/how-to-write-good-agents-dot-md-files https://archive.fo/lo9ch https://platform.claude.com/cookbook/skills-notebooks-01-skills-introduction

[TomLucidor]

Some of the mega-pack designs https://github.com/wshobson/agents

[caioribeiroclw-pixel]

Progressive disclosure feels like the right axis here, but I’d separate it from “shorter prompt” alone.

A pattern that has worked well for multi-tool rule bundles:

1. keep a tiny always-loaded kernel: project purpose, safety constraints, escalation/stop rules;
2. keep domain/book-specific rules on demand, with explicit trigger conditions;
3. for every exported target (AGENTS.md, CLAUDE.md, Cursor rules, skills), record what semantic got preserved vs flattened.

The third point matters because portability can become self-attestation. A rule can be “portable” in Markdown but still lossy if one target supports scoped/glob activation, another only has a flat always-on file, and another maps tools/permissions differently.

I’d probably label bundles with something like:

portability:
  tier: portable-with-adapters
  requiredCapabilities:
    - load repository instructions before planning
    - preserve safety/escalation constraints
    - support on-demand domain guidance, or clearly mark it as always-on
  knownLossyTargets:
    - target: flat markdown outputs
      loss: scoped activation and progressive-disclosure triggers become advisory text
  evidence:
    - generated AGENTS.md smoke-reviewed
    - generated CLAUDE.md smoke-reviewed
    - generated Cursor output checked for scoped-rule loss

That gives users a practical answer to “can I drop this into my agent stack?” without pretending every agent loads skills/rules the same way.

I sketched a concrete example of this portability/fidelity-report shape here, if useful as a comparison point: https://github.com/caioribeiroclw-pixel/pluribus/blob/main/docs/portability-fidelity-report.md