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>
How-to guide covering the full description optimization workflow:
writing effective descriptions, designing trigger eval queries
(should-trigger and should-not-trigger with near-miss examples), testing
trigger rates with a bash eval script, train/validation splits to avoid
overfitting, and the iterative optimization loop.
The guide is client-agnostic by default but includes a working Claude
Code example in the `check_triggered` function using
`--output-format json` and `jq` to detect `Skill` tool calls.
Adds the page to the "For skill creators" navigation group in
`docs.json`.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Jonathan Hefner ·