Load only as much information as needed, at the moment it is needed, to use the context window efficiently.
Why It Is Needed
The LLM's context window is a limited resource. If all information is loaded at once:
- Core content is diluted
- Performance degrades due to irrelevant information
- Token cost increases
Progressive Disclosure divides information into three stages and loads it only when needed.
Three-Stage Loading Model
| Stage | Load Timing | Tokens | Content |
|---|---|---|---|
| Stage 1 | Always | ~100 | name, description, trigger keywords |
| Stage 2 | On activation | <5000 | Core rules, essential instructions |
| Stage 3 | On request | Unlimited | Examples, detailed documentation, scripts |
Applicable Targets
| Target | Stage 1 | Stage 2 | Stage 3 |
|---|---|---|---|
| Skills | frontmatter | SKILL.md body | references/, scripts/ |
| Agents | frontmatter | AGENT.md body | references/, hooks |
| Prompts | Role definition | Core instructions | Examples, reference documentation |
Rule → Skill Conversion
Using Skills instead of Rules is recommended.
Converting existing Rules into Skills allows you to leverage more flexible and powerful features.
| Intended Rule Usage | Skill Configuration |
|---|---|
| Automatically applied every session | user-invocable: false |
| Applied only under specific conditions | Specify trigger conditions in description |
| Need to prevent omission | Group with core-skills and trigger at session start |
Conversion example:
# Before: Rule (rules/code-style.md)
---
description: 코드 스타일 규칙
paths:
- "**/*.ts"
---
# After: Skill (skills/code-style/SKILL.md)
---
name: code-style
description: >
TypeScript 코드 작성 시 적용되는 스타일 가이드.
코드 작성, 리뷰, 리팩토링 시 자동 참조.
user-invocable: false
---
Standard Directory Structure
asset-name/
├── AGENTS.md # 진입점 - 개요 (Claude 자동 인식)
├── [TYPE].md # 2단계 - 핵심 지침
├── CLAUDE.md # AGENTS.md 참조 (선택적, 호환성)
└── references/ # 3단계 - 상세 문서
└── *.md
Role by File
| File | Role | Size Limit |
|---|---|---|
| AGENTS.md | Entry point, automatically recognized by Claude | Minimize |
| CLAUDE.md | AGENTS.md reference (optional) | Minimize |
| SKILL.md / RULE.md / AGENT.md | Core instructions | <5000 tokens, <500 lines |
| references/*.md | Detailed documentation, examples | Unlimited |
Frontmatter Required Fields
---
name: asset-name # 1-64자, 소문자/숫자/하이픈
description: > # 무엇 + 언제 사용하는지
무엇을 하는지 설명.
어떤 상황에서 사용하는지 트리거 키워드 포함.
---
Core Principles
1. Decidable with Stage 1 alone
By reading only the description, it must be possible to decide "is this asset needed?"
# 좋은 예
description: >
코드 리뷰 시 적용되는 품질 기준.
PR 리뷰, 코드 검토, 품질 점검 요청 시 활성화.
# 나쁜 예
description: 코드 리뷰 규칙
2. Stage 2 contains only the core
- 500 lines / 5000 tokens or fewer
- Focus on a single concern
- Separate detailed examples into references/
3. Stage 3 is on-demand
- Load only upon explicit request
- Separate files by topic
- Avoid deep nesting (1 level deep)
Checklist
When creating assets, check:
□ 1단계: description이 무엇+언제를 명확히 설명하는가?
□ 1단계: name이 디렉토리명과 일치하는가?
□ 2단계: 본문이 5000 토큰 이하인가?
□ 2단계: 하나의 관심사에 집중하는가?
□ 3단계: 상세 내용이 references/로 분리되었는가?
□ 3단계: 참조 경로가 1단계 깊이인가?
Detailed guide
Detailed application method for each asset type: