Progressive Disclosure Model
Relevant source files
The following files were used as context for generating this wiki page:
The Progressive Disclosure Model is a three-level loading system that manages the context window of AI assistants efficiently. It ensures that the AI only consumes the most relevant information at any given time, preventing context overflow and reducing token costs. This architecture organizes domain-specific guidance into modular components that trigger based on user intent and session context.
Sources: dev/knowledges/architecture.md:46-48, dev/guides/adding-a-skill.md:20-22
Loading Hierarchy
The model organizes information into three distinct layers. Each layer provides increasing levels of detail, starting from metadata and moving toward specialized reference files.
| Level | Component | Visibility/Loading | Approximate Size |
|---|---|---|---|
| Level 1 | Metadata (Frontmatter) | Always visible | ~100 words |
| Level 2 | SKILL.md body | Loaded on skill activation | < 500 lines |
| Level 3 | Supporting Files | Loaded on demand | No size limit |
Sources: dev/knowledges/architecture.md:48-60, dev/guides/adding-a-skill.md:24-34
Level 1: Metadata and Triggering
The metadata layer consists of the name and description fields found in the YAML frontmatter of each skill's SKILL.md file. This layer is the primary mechanism for skill activation. The AI assistant monitors the user's input and matches it against these descriptions to decide which skill to trigger.
Sources: dev/knowledges/architecture.md:50-53, dev/guidelines/skill-authoring.md:12-14
Level 2: Skill Navigation
Once activated, the AI loads the body of the SKILL.md file. This file serves as a navigator rather than a comprehensive manual. It contains high-level overviews, standard workflows (numbered steps), and pointers to more detailed Level 3 files.
Sources: dev/knowledges/architecture.md:54-56, dev/guidelines/skill-authoring.md:32-35
Level 3: Specialized Detail
Supporting files contain granular details, specific rules, and concrete examples. These files are only loaded when the AI identifies a specific task or question that requires deeper context. Level 3 files include:
- Rules (
rules/*.md): Individual best practices or requirements organized by category. - Examples (
examples.md): Ready-to-use patterns and worked solutions. - References (
reference.md): Technical property tables and format specifications. - Common Resources (
../infrahub-common/): Shared guidance for cross-cutting concerns like GraphQL queries or project configuration.
Sources: dev/knowledges/architecture.md:57-60, dev/guides/adding-a-skill.md:31-34
Component Flow
The following diagram illustrates how a user request traverses the progressive disclosure layers to activate specific domain knowledge.
This diagram shows the transition from initial user intent to the granular loading of supporting technical files.
Sources: dev/knowledges/architecture.md:49-60, dev/guides/adding-a-skill.md:23-34
Information Source Priority
The progressive disclosure model enforces a specific priority order for information sources to ensure technical accuracy and version consistency. The AI must exhaust internal skill resources before seeking external documentation.
- Active Skill Files: The AI first consults the
rules/,reference.md,examples.md, andvalidation.mdof the currently active skill. - Shared Common References: If the active skill does not contain the answer, the AI looks in
infrahub-common/for GraphQL queries or project-wide rules. - External Documentation: The official
docs.infrahub.appsite serves as a last resort for topics not covered by internal skills, such as deleting nodes or specific git-integration semantics.
Sources: skills/infrahub-common/rules/workflow-information-priority.md:25-33
Structural Implementation
Each skill implements this model through a standardized directory structure that supports modular rule loading.
The directory structure enables the AI to navigate from the central skill file to specific modular rules based on task categories defined in _sections.md.
Sources: dev/knowledges/architecture.md:24-44, dev/guides/adding-a-skill.md:12-19
Rule Modularity
Rules are designed to be independently addressable. Instead of one large prompt, skills use _sections.md to define category prefixes. This allows the AI to load only the rules relevant to the current task, further saving context window space.
Sources: dev/knowledges/architecture.md:69-76, skills/infrahub-common/rules/_sections.md:1-2
Summary
The Progressive Disclosure Model maintains AI efficiency by categorizing information into three tiers of depth. By using metadata for triggering, navigation files for workflows, and modular supporting files for detail, the system provides accurate domain-specific guidance while minimizing context window consumption. This structure ensures that AI assistants prioritize curated, version-matched rules over generic training data or external documentation.
Sources: dev/knowledges/architecture.md:62-67, skills/infrahub-common/rules/workflow-information-priority.md:12-21