Skip to main content

Progressive Disclosure

An agent that knows everything up front has a bloated system prompt and a worse signal-to-noise ratio. Distri skills avoid that with progressive disclosure: a small always-loaded summary, and details the agent pulls in only when a task actually calls for them.

How it works​

A skill is a folder:

skills/refunds/
  SKILL.md              # short, always available to the agent
  references/
    policy.md           # loaded on demand
    edge-cases.md       # loaded on demand
  • SKILL.md is a few lines: what the skill is for and the handful of things the agent reaches for most. Its description is what the agent matches against to decide the skill is relevant at all.
  • references/ hold the depth: full policies, formats, and examples. The agent reads a reference file only when the task in front of it needs that detail.

So a passing mention of refunds costs a sentence of context; a genuine refund task pulls in the policy. Nothing else loads.

Why it matters​

  • Reliable activation: a tight description means the skill triggers when it should and stays quiet when it shouldn't.
  • Smaller prompts: the model isn't carrying reference material it isn't using this turn.
  • One skill, many references beats a dozen fragmented skills competing to activate.

This is the same shape whether the skill teaches your agent a capability at runtime or teaches your coding agent how to work with Distri. See Distri skill for coding agents.