From b8d2613ac050aa4aa8bfb2cf28380d81cdfcd1ca Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 15:08:24 -0500 Subject: [PATCH] Point "progressive disclosure" links at `specification.mdx` Two links in `best-practices.mdx` and `optimizing-descriptions.mdx` pointed at `/what-are-skills#how-skills-work`, blocking the eventual removal of `what-are-skills.mdx`. Redirect them to the existing `## Progressive disclosure` section in `specification.mdx`, which is a more natural reference target for the concept. Also expand that section's lead-in from "Skills should be structured for efficient use of context:" to a sentence that names progressive disclosure as a loading mechanism, so readers who follow the link land on a definition rather than a bare set of structural guidelines. The original three-level list and `SKILL.md` line-count guidance are preserved unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/skill-creation/best-practices.mdx | 2 +- docs/skill-creation/optimizing-descriptions.mdx | 2 +- docs/specification.mdx | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/skill-creation/best-practices.mdx b/docs/skill-creation/best-practices.mdx index 33d228d..cfe9188 100644 --- a/docs/skill-creation/best-practices.mdx +++ b/docs/skill-creation/best-practices.mdx @@ -87,7 +87,7 @@ Overly comprehensive skills can hurt more than they help — the agent struggles The [specification](/specification#progressive-disclosure) recommends keeping `SKILL.md` under 500 lines and 5,000 tokens — just the core instructions the agent needs on every run. When a skill legitimately needs more content, move detailed reference material to separate files in `references/` or similar directories. -The key is telling the agent *when* to load each file. "Read `references/api-errors.md` if the API returns a non-200 status code" is more useful than a generic "see references/ for details." This lets the agent load context on demand rather than up front, which is how [progressive disclosure](/what-are-skills#how-skills-work) is designed to work. +The key is telling the agent *when* to load each file. "Read `references/api-errors.md` if the API returns a non-200 status code" is more useful than a generic "see references/ for details." This lets the agent load context on demand rather than up front, which is how [progressive disclosure](/specification#progressive-disclosure) is designed to work. ## Calibrating control diff --git a/docs/skill-creation/optimizing-descriptions.mdx b/docs/skill-creation/optimizing-descriptions.mdx index 67175e2..8bb2a2f 100644 --- a/docs/skill-creation/optimizing-descriptions.mdx +++ b/docs/skill-creation/optimizing-descriptions.mdx @@ -10,7 +10,7 @@ This guide covers how to systematically test and improve your skill's descriptio ## How skill triggering works -Agents use [progressive disclosure](/what-are-skills#how-skills-work) to manage context. At startup, they load only the `name` and `description` of each available skill — just enough to decide when a skill might be relevant. When a user's task matches a description, the agent reads the full `SKILL.md` into context and follows its instructions. +Agents use [progressive disclosure](/specification#progressive-disclosure) to manage context. At startup, they load only the `name` and `description` of each available skill — just enough to decide when a skill might be relevant. When a user's task matches a description, the agent reads the full `SKILL.md` into context and follows its instructions. This means the description carries the entire burden of triggering. If the description doesn't convey when the skill is useful, the agent won't know to reach for it. diff --git a/docs/specification.mdx b/docs/specification.mdx index 83e6026..a45ead3 100644 --- a/docs/specification.mdx +++ b/docs/specification.mdx @@ -213,7 +213,7 @@ Contains static resources: ## Progressive disclosure -Skills should be structured for efficient use of context: +Agents load skills *progressively*, pulling in more detail only as a task calls for it. Skills should be structured to take advantage of this: 1. **Metadata** (~100 tokens): The `name` and `description` fields are loaded at startup for all skills 2. **Instructions** (< 5000 tokens recommended): The full `SKILL.md` body is loaded when the skill is activated