mirror of
https://github.com/agentskills/agentskills.git
synced 2026-06-18 15:54:06 +08:00
Merge pull request #325 from jonathanhefner/evolve-landing-page
Flesh out landing page
This commit is contained in:
Jonathan Hefner
GitHub
+4
-1
@@ -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": "/"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
+38
-42
@@ -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!
|
||||
|
||||
<LogoCarousel clients={clients} />
|
||||
|
||||
@@ -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
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<CardGroup cols={2}>
|
||||
<Card
|
||||
title="What are skills?"
|
||||
icon="lightbulb"
|
||||
href="/what-are-skills"
|
||||
title="Quickstart"
|
||||
icon="rocket"
|
||||
href="/skill-creation/quickstart"
|
||||
>
|
||||
Learn about skills, how they work, and why they matter.
|
||||
Create your first Agent Skill and see it in action.
|
||||
</Card>
|
||||
<Card
|
||||
title="Specification"
|
||||
icon="file-code"
|
||||
href="/specification"
|
||||
>
|
||||
The complete format specification for SKILL.md files.
|
||||
</Card>
|
||||
<Card
|
||||
title="Add skills support"
|
||||
icon="gear"
|
||||
href="/client-implementation/adding-skills-support"
|
||||
>
|
||||
Add skills support to your agent or tool.
|
||||
</Card>
|
||||
<Card
|
||||
title="Example skills"
|
||||
icon="code"
|
||||
href="https://github.com/anthropics/skills"
|
||||
>
|
||||
Browse example skills on GitHub.
|
||||
</Card>
|
||||
<Card
|
||||
title="Reference library"
|
||||
icon="wrench"
|
||||
href="https://github.com/agentskills/agentskills/tree/main/skills-ref"
|
||||
>
|
||||
Validate skills and generate prompt XML.
|
||||
The complete format specification for Agent Skills.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 }) => (
|
||||
<a href={client.url} className="block no-underline border-none w-full h-full">
|
||||
<img className="block dark:hidden object-contain w-full h-full !my-0" src={client.lightSrc} alt={client.name} noZoom />
|
||||
@@ -26,31 +35,15 @@ export const LogoCarousel = ({clients}) => {
|
||||
</a>
|
||||
);
|
||||
|
||||
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 (
|
||||
<>
|
||||
<div className="logo-carousel">
|
||||
<div className="logo-carousel-track" style={{ animation: 'logo-scroll 50s linear infinite' }}>
|
||||
{row1Doubled.map((client, i) => (
|
||||
<div key={`${client.name}-${i}`} style={{ width: 150 * (client.scale || 1), maxWidth: "100%" }}>
|
||||
<Logo client={client} />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
<div className="logo-carousel">
|
||||
<div className="logo-carousel-track" style={{ animation: `logo-scroll ${cycleDuration}s linear infinite` }}>
|
||||
{doubled.map((client, i) => (
|
||||
<div key={`${client.name}-${i}`} style={{ width: 150 * (client.scale || 1), maxWidth: "100%" }}>
|
||||
<Logo client={client} />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
<div className="logo-carousel">
|
||||
<div className="logo-carousel-track" style={{ animation: 'logo-scroll 60s linear infinite reverse' }}>
|
||||
{row2Doubled.map((client, i) => (
|
||||
<div key={`${client.name}-${i}`} style={{ width: 150 * (client.scale || 1), maxWidth: "100%" }}>
|
||||
<Logo client={client} />
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
</>
|
||||
</div>
|
||||
);
|
||||
};
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -94,7 +94,6 @@ body:has(#enable-section-numbers) {
|
||||
align-items: center;
|
||||
width: max-content;
|
||||
gap: 3rem;
|
||||
padding: 0.75rem 0;
|
||||
will-change: transform;
|
||||
}
|
||||
|
||||
|
||||
@@ -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.
|
||||
Reference in New Issue
Block a user