agent/agentskills
1
0
Fork 0
mirror of https://github.com/agentskills/agentskills.git synced 2026-06-18 15:54:06 +08:00
Code Issues Packages Projects Releases Wiki Activity

Point "progressive disclosure" links at specification.mdx

Browse Source 
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) <noreply@anthropic.com>
This commit is contained in:
Jonathan Hefner
2026-04-19 15:08:24 -05:00
Unverified
parent 8aeff47697
commit b8d2613ac0
3 changed files with 3 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/skill-creation/best-practices.mdx
+1 -1
View File
@@ -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
docs/skill-creation/optimizing-descriptions.mdx
+1 -1
View File
@@ -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.
docs/specification.mdx
+1 -1
View File
@@ -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