D5: Progressive Disclosure (15 points)

Purpose: Structure content for on-demand loading, not front-loading everything.

Scoring:

Components

1. Navigation Hub Approach (5 points)

• SKILL.md is <100 lines
• Overview + when-to-use + reference guide — NOT full content
• Example: supabase-postgres-best-practices (65 lines)

2. References Directory (4 points)

• Detailed content in references/*.md
• Each reference 100–500 lines, focused on ONE topic

3. Category Organisation (3 points)

• Files organised by prefix (principles-, patterns-, etc.)
• Priority labels (CRITICAL, HIGH, MEDIUM, LOW)

4. Lazy Loading Guidance (3 points) — REQUIRED

• References table includes a concrete “When to Use” column that tells agents exactly which task triggers loading each reference
• AGENTS.md explicitly instructs agents to load only the minimum references needed for the current task
• Each reference entry states a specific, actionable condition rather than a generic description
• WHY: Without explicit lazy-load guidance, agents default to loading all references eagerly, wasting context on irrelevant content
• IMPACT: Skills without lazy-load guidance consume 3–10× more context than necessary

References Section Standard

Every SKILL.md with references MUST end with a ## References section using a 3-column Markdown table:

## References

| Topic | Reference | When to Use |
| --- | --- | --- |
| Security patterns, caching, and trigger configuration | [Best Practices](#best-practices) | Every time you generate a workflow |
| Pinned action versions and input/output specs | [Common Actions](#common-actions) | When using any public action |
| Official workflow syntax and expression reference | [GitHub Actions Docs](https://docs.github.com/en/actions) | For syntax lookup |

Lazy Loading Anti-Patterns

❌ NEVER list references without “When to Use” conditions — forces agents to load everything or guess.

❌ NEVER use vague “When to Use” entries ("For scoring" is not actionable — it does not say when NOT to load).

✅ Explicit lazy-load conditions:

| Topic | Reference | When to Use |
| --- | --- | --- |
| Per-dimension criteria and bonus rules | [Dimensions](#dimensions) | Evaluating any individual dimension or understanding the rubric |
| Score thresholds and grade bands | [Scoring Rubric](#scoring) | Calculating a total score or assigning a grade — skip if only auditing structure |

Examples

Excellent Progressive Disclosure (15/15):

bdd-testing/
├── SKILL.md (64 lines — navigation hub with actionable "When to Use" per reference)
├── AGENTS.md (explicit: "load only references needed for current task")
└── references/
    ├── principles-three-amigos.md (CRITICAL, 250 lines)
    ├── gherkin-syntax.md (HIGH, 180 lines)
    └── practices-tags.md (MEDIUM, 120 lines)

Poor Progressive Disclosure (6/15):

bdd-testing/
└── SKILL.md (1,800 lines — everything front-loaded)

Missing Lazy Loading (10/15 — loses 3 points):

bdd-testing/
├── SKILL.md (80 lines — good hub, but no "When to Use" column in references table)
├── AGENTS.md (says "load all references before starting")
└── references/
    ├── principles-three-amigos.md
    └── gherkin-syntax.md

Academic References

@article{springer2018progressive,
  title         = {Progressive Disclosure: Designing for Effective Transparency},
  author        = {Springer and Whittaker},
  year          = {2018},
  journal       = {arXiv preprint arXiv:1811.02164},
  eprint        = {1811.02164},
  archivePrefix = {arXiv},
  url           = {<https://arxiv.org/abs/1811.02164}>
}

@inproceedings{anik2026progressive,
  title         = {Designing Effective Training Dataset Explanations: The Impact of Information Depth and Progressive Disclosure},
  author        = {A. I. Anik and A. Bunt},
  year          = {2026},
  booktitle     = {Proceedings of the 31st International Conference on Intelligent User Interfaces (IUI 2026)},
  publisher     = {ACM},
  url           = {<https://dl.acm.org/doi/10.1145/3742413.3789087>}
}

@article{timileyin2024cognitiveload,
  title         = {The Role of Cognitive Load in Shaping Web Usability Requirements},
  author        = {A. Timileyin},
  year          = {2024},
  journal       = {SSRN},
  url           = {<https://papers.ssrn.com/sol3/papers.cfm?abstract_id=5247018>}
}

@article{pastrakis2026aiarchitecture,
  title         = {AI-Enhanced Modular Information Architecture for Cultural Heritage: Designing Cognitive-Efficient and User-Centered Experiences},
  author        = {F. Pastrakis and M. Konstantakis and G. Caridakis},
  year          = {2026},
  journal       = {Information},
  volume        = {17},
  number        = {1},
  pages         = {92},
  publisher     = {MDPI},
  url           = {<https://www.mdpi.com/2078-2489/17/1/92>}
}