Learned Progressive Disclosure

Progressive Disclosure for Skills

Context

When a skill becomes too large, it contaminates the LLM context and becomes harder to maintain. Skills with multiple phases or variants are especially prone to bloat.

Problem

• Skills >300 lines load unnecessary context
• Multi-phase skills require different instructions at different times
• Mixing orchestration with details creates maintenance burden
• Evals/workspace in skill directory add noise

Solution

Structure

~/.pi/agent/skills/<skill-name>/
├── SKILL.md           # Orchestrator (~150 lines max)
├── resources/         # Detailed instructions (loaded as needed)
│   ├── phase-1.md
│   ├── phase-2.md
│   └── variant-a.md
└── scripts/           # Optional executable helpers