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