From 2a439b80e5f5e877c2d3bdfd9b8f764e99fc1583 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 11:32:42 -0500 Subject: [PATCH 1/8] Merge "Why" and "What" sections on `home.mdx` landing page The "Why Agent Skills?" audience bullets and the "What can Agent Skills enable?" capability bullets were two angles on the same material, with direct duplicates between them (e.g. "For skill authors" vs. "Interoperability", "For compatible agents" vs. "New capabilities"). Collapse both into a single "Why Agent Skills?" section: keep the problem statement, fold "portable, version-controlled" into the opener, drop the circular "new capabilities" bullet (absorbing its examples into "Domain expertise"), and rename "Interoperability" to "Cross-product reuse". The new "This gives agents:" transition leads into three non-overlapping bullets. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/home.mdx | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/docs/home.mdx b/docs/home.mdx index 06ee8dd..51b64c1 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -10,20 +10,11 @@ Agent Skills are folders of instructions, scripts, and resources that agents can ## Why Agent Skills? -Agents are increasingly capable, but often don't have the context they need to do real work reliably. Skills solve this by giving agents access to procedural knowledge and company-, team-, and user-specific context they can load on demand. Agents with access to a set of skills can extend their capabilities based on the task they're working on. +Agents are increasingly capable, but often don't have the context they need to do real work reliably. Skills solve this by packaging procedural knowledge and company-, team-, and user-specific context into portable, version-controlled folders that agents load on demand. This gives agents: -**For skill authors**: Build capabilities once and deploy them across multiple agent products. - -**For compatible agents**: Support for skills lets end users give agents new capabilities out of the box. - -**For teams and enterprises**: Capture organizational knowledge in portable, version-controlled packages. - -## What can Agent Skills enable? - -- **Domain expertise**: Package specialized knowledge into reusable instructions, from legal review processes to data analysis pipelines. -- **New capabilities**: Give agents new capabilities (e.g. creating presentations, building MCP servers, analyzing datasets). -- **Repeatable workflows**: Turn multi-step tasks into consistent and auditable workflows. -- **Interoperability**: Reuse the same skill across different skills-compatible agent products. +- **Domain expertise**: Capture specialized knowledge — from legal review processes to data analysis pipelines to presentation formatting — as reusable instructions and resources. +- **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. ## Adoption From f86c6bbc009796c18037a1cb745055b713c5442c Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 11:55:58 -0500 Subject: [PATCH 2/8] Add "What are Agent Skills?" section to `home.mdx` landing page Pulls the lightweight-open-format intro, the `SKILL.md` folder description, and the directory tree from `what-are-skills.mdx` onto the landing page. Also retitles the page to "Agent Skills Overview" (with `sidebarTitle: "Overview"`) and refreshes the frontmatter description. This works toward letting `home.mdx` stand on its own so that `what-are-skills.mdx` can be phased out in the future. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/home.mdx | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/home.mdx b/docs/home.mdx index 51b64c1..2345ad0 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -1,12 +1,26 @@ --- -title: "Overview" -description: "A simple, open format for giving agents new capabilities and expertise." +title: "Agent Skills Overview" +sidebarTitle: "Overview" +description: "A standardized way to give AI agents new capabilities and expertise." --- import { clients } from '/snippets/clients.jsx'; import { LogoCarousel } from '/snippets/LogoCarousel.jsx'; -Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. +## What are Agent Skills? + +Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows. + +At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, reference materials, templates, and other resources. + +``` +my-skill/ +├── SKILL.md # Required: metadata + instructions +├── scripts/ # Optional: executable code +├── references/ # Optional: documentation +├── assets/ # Optional: templates, resources +└── ... # Any additional files or directories +``` ## Why Agent Skills? From c163f1af390a87a75fa4771e83156ffaf2418d0c Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 12:27:22 -0500 Subject: [PATCH 3/8] 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. From 278196525d3dcfcc205bdd91c922e4f2792983f1 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 13:07:38 -0500 Subject: [PATCH 4/8] Simplify `LogoCarousel` and rework "Adoption" section on `home.mdx` Collapse the two-row `LogoCarousel` into a single row and compute its scroll duration from the total cycle width using a fixed `PX_PER_SECOND`, so scroll speed stays consistent regardless of how many logos appear or how they are scaled. Drop the now-unneeded vertical padding on `.logo-carousel-track`. Rename the "Adoption" heading to "Where can I use Agent Skills?" and rewrite its blurb to point readers at the Client Showcase page, matching the question-led style of the neighboring sections. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/home.mdx | 4 +-- docs/snippets/LogoCarousel.jsx | 45 ++++++++++++++-------------------- docs/style.css | 1 - 3 files changed, 21 insertions(+), 29 deletions(-) diff --git a/docs/home.mdx b/docs/home.mdx index 97263d1..72fa165 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -42,9 +42,9 @@ Agents load skills through **progressive disclosure**, in three stages: 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 +## Where can I use Agent Skills? -Agent Skills are supported by leading AI development tools. +Agent Skills are supported by a large number of AI tools and agentic clients — see the [Client Showcase](/clients) to explore some of them! diff --git a/docs/snippets/LogoCarousel.jsx b/docs/snippets/LogoCarousel.jsx index 10d541f..36030c1 100644 --- a/docs/snippets/LogoCarousel.jsx +++ b/docs/snippets/LogoCarousel.jsx @@ -3,10 +3,9 @@ Shuffles clients on each page load for fair exposure. */} export const LogoCarousel = ({clients}) => { - - /* Shuffle clients on component mount */ const [shuffled, setShuffled] = useState(clients); + /* Shuffle clients on component mount */ useEffect(() => { const shuffle = (items) => { const copy = [...items]; @@ -19,6 +18,16 @@ export const LogoCarousel = ({clients}) => { setShuffled(shuffle(clients)); }, []); + const doubled = [...shuffled, ...shuffled]; + + const GAP_PX = 48; // 3rem at the default 16px base + const PX_PER_SECOND = 40; + const cycleWidth = shuffled.reduce( + (sum, client) => sum + 150 * (client.scale || 1) + GAP_PX, + 0, + ); + const cycleDuration = cycleWidth / PX_PER_SECOND; + const Logo = ({ client }) => ( {client.name} @@ -26,31 +35,15 @@ export const LogoCarousel = ({clients}) => { ); - const row1 = shuffled.filter((_, i) => i % 2 === 0); - const row2 = shuffled.filter((_, i) => i % 2 === 1); - const row1Doubled = [...row1, ...row1]; - const row2Doubled = [...row2, ...row2]; - return ( - <> -
-
- {row1Doubled.map((client, i) => ( -
- -
- ))} -
+
+
+ {doubled.map((client, i) => ( +
+ +
+ ))}
-
-
- {row2Doubled.map((client, i) => ( -
- -
- ))} -
-
- +
); }; diff --git a/docs/style.css b/docs/style.css index bc76b93..93b542d 100644 --- a/docs/style.css +++ b/docs/style.css @@ -94,7 +94,6 @@ body:has(#enable-section-numbers) { align-items: center; width: max-content; gap: 3rem; - padding: 0.75rem 0; will-change: transform; } From 092659e3ec0e9e54cb03c16fdda01df818141676 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 14:16:05 -0500 Subject: [PATCH 5/8] Reduce "Get started" cards on `home.mdx` to Quickstart and Specification Pare the `CardGroup` from five cards across three columns down to two cards across two columns, keeping only Quickstart (pointing at `/skill-creation/quickstart`) and Specification. The "What are skills?" card is now redundant with the "What are Agent Skills?", "Why Agent Skills?", and "How do Agent Skills work?" sections above, and the "Add skills support", "Example skills", and "Reference library" links serve smaller audiences that can reach them through the sidebar. Also rename the section heading to "Get started with Agent Skills" to match the neighboring sections, and reword the Specification blurb to reference Agent Skills rather than `SKILL.md` files. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/home.mdx | 35 +++++++---------------------------- 1 file changed, 7 insertions(+), 28 deletions(-) diff --git a/docs/home.mdx b/docs/home.mdx index 72fa165..9c39d88 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -54,42 +54,21 @@ The Agent Skills format was originally developed by [Anthropic](https://www.anth Come join the discussion on [GitHub](https://github.com/agentskills/agentskills) or [Discord](https://discord.gg/MKPE9g8aUy)! -## Get started +## Get started with Agent Skills - + - Learn about skills, how they work, and why they matter. + Create your first Agent Skill and see it in action. - The complete format specification for SKILL.md files. - - - Add skills support to your agent or tool. - - - Browse example skills on GitHub. - - - Validate skills and generate prompt XML. + The complete format specification for Agent Skills. From 8aeff476971ff1d4eb87a49568678c3f71c38f68 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 14:25:01 -0500 Subject: [PATCH 6/8] Remove link to `what-are-skills.mdx` from `quickstart.mdx` The quickstart's "How it works" section already explains progressive disclosure in concrete, tutorial-specific terms, so the follow-up link to `what-are-skills.mdx` adds little. Drop it in preparation for phasing out that page. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/skill-creation/quickstart.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/skill-creation/quickstart.mdx b/docs/skill-creation/quickstart.mdx index 8947828..0d41a87 100644 --- a/docs/skill-creation/quickstart.mdx +++ b/docs/skill-creation/quickstart.mdx @@ -68,7 +68,7 @@ Here's what happened behind the scenes: 3. **Execution** — The agent followed the instructions in the body, adapting the terminal command to the number of sides in your request. -This process uses **progressive disclosure** to let the agent access many skills without loading all their instructions up front. For more detail, see [How skills work](/what-are-skills#how-skills-work). +This process uses **progressive disclosure** to let the agent access many skills without loading all their instructions up front. ## Next steps From b8d2613ac050aa4aa8bfb2cf28380d81cdfcd1ca Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 15:08:24 -0500 Subject: [PATCH 7/8] 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 From c33d0c7f1fff13414d0fa0861788eb84587a6910 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Sun, 19 Apr 2026 15:25:28 -0500 Subject: [PATCH 8/8] Remove redundant `what-are-skills.mdx` The content of this page is now adequately represented elsewhere: - The intro, directory structure, and progressive disclosure sections are covered by `home.mdx` and `specification.mdx`. - The `SKILL.md` format details are covered by `quickstart.mdx` and `specification.mdx`. - The "key advantages" framing (self-documenting, extensible, portable) is either self-evident, conveyed by the directory trees in `home.mdx` and `specification.mdx`, or demonstrated by the Client Showcase. Also adds a redirect from `/what-are-skills` to the home page so existing inbound links don't break. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/docs.json | 5 ++- docs/what-are-skills.mdx | 71 ---------------------------------------- 2 files changed, 4 insertions(+), 72 deletions(-) delete mode 100644 docs/what-are-skills.mdx diff --git a/docs/docs.json b/docs/docs.json index f70663f..8145589 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -21,7 +21,6 @@ "navigation": { "pages": [ "home", - "what-are-skills", "specification", "clients", { @@ -58,6 +57,10 @@ { "source": "/integrate-skills", "destination": "/client-implementation/adding-skills-support" + }, + { + "source": "/what-are-skills", + "destination": "/" } ] } diff --git a/docs/what-are-skills.mdx b/docs/what-are-skills.mdx deleted file mode 100644 index 0f80ba0..0000000 --- a/docs/what-are-skills.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "What are skills?" -description: "Agent Skills are a lightweight, open format for extending AI agent capabilities with specialized knowledge and workflows." ---- - -At its core, a skill is a folder containing a `SKILL.md` file. This file includes metadata (`name` and `description`, at minimum) and instructions that tell an agent how to perform a specific task. Skills can also bundle scripts, templates, and reference materials. - -```directory -my-skill/ -├── SKILL.md # Required: instructions + metadata -├── scripts/ # Optional: executable code -├── references/ # Optional: documentation -└── assets/ # Optional: templates, resources -``` - -## How skills work - -Skills use **progressive disclosure** to manage context efficiently: - -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 loading referenced files or executing bundled code as needed. - -This approach keeps agents fast while giving them access to more context on demand. - -## The SKILL.md file - -Every skill starts with a `SKILL.md` file containing YAML frontmatter and Markdown instructions: - -```mdx ---- -name: pdf-processing -description: Extract PDF text, fill forms, merge files. Use when handling PDFs. ---- - -# PDF Processing - -## When to use this skill -Use this skill when the user needs to work with PDF files... - -## How to extract text -1. Use pdfplumber for text extraction... - -## How to fill forms -... -``` - -The following frontmatter is required at the top of `SKILL.md`: - -- `name`: A short identifier -- `description`: When to use this skill - -The Markdown body contains the actual instructions and has no specific restrictions on structure or content. - -This simple format has some key advantages: - -- **Self-documenting**: A skill author or user can read a `SKILL.md` and understand what it does, making skills easy to audit and improve. - -- **Extensible**: Skills can range in complexity from just text instructions to executable code, assets, and templates. - -- **Portable**: Skills are just files, so they're easy to edit, version, and share. - -## Next steps - -- [View the specification](/specification) to understand the full format. -- [Add skills support to your agent](/client-implementation/adding-skills-support) to build a compatible client. -- [See example skills](https://github.com/anthropics/skills) on GitHub. -- [Read authoring best practices](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) for writing effective skills. -- [Use the reference library](https://github.com/agentskills/agentskills/tree/main/skills-ref) to validate skills and generate prompt XML.