From 5562fbe7d71e321aa6b6502e330696b9ae07f0c1 Mon Sep 17 00:00:00 2001
From: Jiang Bohan <bhjiang@outlook.com>
Date: Fri, 30 Jan 2026 17:26:49 +0800
Subject: [PATCH] docs(skill-creator): add progressive disclosure section

---
 skills/skill-creator/SKILL.md | 43 ++++++++++++++++++++++++++++++-----
 1 file changed, 37 insertions(+), 6 deletions(-)

diff --git a/skills/skill-creator/SKILL.md b/skills/skill-creator/SKILL.md
index 3c6607d4..b96ce8e3 100644
--- a/skills/skill-creator/SKILL.md
+++ b/skills/skill-creator/SKILL.md
@@ -178,14 +178,45 @@ Or use the CLI:
 pnpm skills:cli remove <skill-name>
 ```
 
+### Progressive Disclosure
+
+Skills use a multi-level loading system to manage context efficiently:
+
+1. **Metadata** (name + description) - Always loaded for skill selection (~50-100 tokens)
+2. **SKILL.md body** - Loaded when skill is invoked or relevant
+3. **Bundled resources** - Loaded on-demand when referenced
+
+**Design principle**: Keep SKILL.md concise. The context window is shared with conversation history and other skills. Only include information that the agent doesn't already know.
+
+**For large skills**, split content into separate files:
+
+```
+my-skill/
+├── SKILL.md              # Core workflow and navigation
+├── references/
+│   ├── api-docs.md       # Detailed API documentation
+│   └── examples.md       # Extended examples
+└── scripts/
+    └── helper.py         # Reusable scripts
+```
+
+In SKILL.md, reference them with clear guidance:
+```markdown
+## Advanced Features
+
+- **API Reference**: See `references/api-docs.md` for complete method documentation
+- **Examples**: See `references/examples.md` for common patterns
+```
+
 ### Best Practices
 
-1. **Clear Instructions**: Write specific, actionable instructions
-2. **Examples**: Include usage examples in your skill
-3. **Requirements**: Specify binaries/env vars if needed
-4. **Versioning**: Update version when making changes
-5. **Tags**: Use descriptive tags for organization
-6. **Single Responsibility**: Each skill should do one thing well
+1. **Concise Instructions**: Keep SKILL.md under 500 lines; split larger content into references
+2. **Clear Triggers**: Write descriptions that help the agent know when to use the skill
+3. **Examples**: Include usage examples in your skill
+4. **Requirements**: Specify binaries/env vars if needed
+5. **Versioning**: Update version when making changes
+6. **Tags**: Use descriptive tags for organization
+7. **Single Responsibility**: Each skill should do one thing well
 
 ### Including Scripts