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/home.mdx b/docs/home.mdx index 06ee8dd..9c39d88 100644 --- a/docs/home.mdx +++ b/docs/home.mdx @@ -1,33 +1,50 @@ --- -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? -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. +- **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. -**For compatible agents**: Support for skills lets end users give agents new capabilities out of the box. +## How do Agent Skills work? -**For teams and enterprises**: Capture organizational knowledge in portable, version-controlled packages. +Agents load skills through **progressive disclosure**, in three stages: -## What can Agent Skills enable? +1. **Discovery**: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant. -- **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. +2. **Activation**: When a task matches a skill's description, the agent reads the full `SKILL.md` instructions into context. -## Adoption +3. **Execution**: The agent follows the instructions, optionally executing bundled code or loading referenced files as needed. -Agent Skills are supported by leading AI development tools. +Full instructions load only when a task calls for them, so agents can keep many skills on hand with only a small context footprint. + +## Where can I use Agent Skills? + +Agent Skills are supported by a large number of AI tools and agentic clients — see the [Client Showcase](/clients) to explore some of them! @@ -37,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. 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/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 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/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 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; } 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.