From c163f1af390a87a75fa4771e83156ffaf2418d0c Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 12:27:22 -0500 Subject: [PATCH] Add "How do Agent Skills work?" section to `home.mdx` landing page Adapted from the "How skills work" section of `what-are-skills.mdx`, with the heading reworded as a question to match the sibling sections, and the closing sentence rewritten to emphasize the payoff of progressive disclosure. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/home.mdx | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/home.mdx b/docs/home.mdx index 2345ad0..97263d1 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -30,6 +30,18 @@ Agents are increasingly capable, but often don't have the context they need to d - **Repeatable workflows**: Turn multi-step tasks into consistent, auditable procedures. - **Cross-product reuse**: Build a skill once and use it across any skills-compatible agent. +## How do Agent Skills work? + +Agents load skills through **progressive disclosure**, in three stages: + +1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant. + +2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context. + +3. **Execution**: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed. + +Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint. + ## Adoption Agent Skills are supported by leading AI development tools.