mirror of
https://github.com/anthropics/skills.git
synced 2026-03-30 13:13:29 +08:00
Split agent-skills-spec into separate authoring and client integration guides (#148)
Reorganize the spec documentation: - agent-skills-spec.md now serves as an index linking to the guides - skill-authoring.md covers skill creation and SKILL.md format - skill-client-integration.md provides guidance for Skill Client implementors 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Keith Lazuka
1
.gitignore
vendored
1
.gitignore
vendored
@@ -1,2 +1,3 @@
|
||||
.DS_Store
|
||||
__pycache__/
|
||||
|
||||
|
||||
@@ -1,55 +1,13 @@
|
||||
# Agent Skills Spec
|
||||
|
||||
A skill is a folder of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. In order for the folder to be recognized as a skill, it must contain a `SKILL.md` file.
|
||||
A skill is a folder of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks. In order for the folder to be recognized as a skill, it must contain a `SKILL.md` file.
|
||||
|
||||
# Skill Folder Layout
|
||||
## Guides
|
||||
|
||||
A minimal skill folder looks like this:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
- SKILL.md
|
||||
```
|
||||
|
||||
More complex skills can add additional directories and files as needed.
|
||||
|
||||
|
||||
# The SKILL.md file
|
||||
|
||||
The skill's "entrypoint" is the `SKILL.md` file. It is the only file required to exist. The file must start with a YAML frontmatter followed by regular Markdown.
|
||||
|
||||
## YAML Frontmatter
|
||||
|
||||
The YAML frontmatter has 2 required properties:
|
||||
|
||||
- `name`
|
||||
- The name of the skill in hyphen-case
|
||||
- Restricted to lowercase Unicode alphanumeric + hyphen
|
||||
- Must match the name of the directory containing the SKILL.md
|
||||
- `description`
|
||||
- Description of what the skill does and when Claude should use it
|
||||
|
||||
There are 3 optional properties:
|
||||
|
||||
- `license`
|
||||
- The license applied to the skill
|
||||
- We recommend keeping it short (either the name of a license or the name of a bundled license file)
|
||||
- `allowed-tools`
|
||||
- A list of tools that are pre-approved to run
|
||||
- Currently only supported in Claude Code
|
||||
- `metadata`
|
||||
- A map from string keys to string values
|
||||
- Clients can use this to store additional properties not defined by the Agent Skills Spec
|
||||
- We recommend making your key names reasonably unique to avoid accidental conflicts
|
||||
|
||||
## Markdown Body
|
||||
|
||||
The Markdown body has no restrictions on it.
|
||||
|
||||
# Additional Information
|
||||
|
||||
For a minimal example, see the `template-skill` example.
|
||||
- [Skill Authoring Guide](skill_authoring.md) — How to create skills, including folder layout and SKILL.md format
|
||||
- [Skill Client Integration Guide](skill_client_integration.md) — How to add Skills support to a new agent or product
|
||||
|
||||
# Version History
|
||||
|
||||
- 1.1 (2025-12-16) Added guidance for Skill Client implementors.
|
||||
- 1.0 (2025-10-16) Public Launch
|
||||
|
||||
47
spec/skill-authoring.md
Normal file
47
spec/skill-authoring.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Skill Authoring Guide
|
||||
|
||||
This guide describes how to create skills that agents can discover and use.
|
||||
|
||||
## Skill Folder Layout
|
||||
|
||||
A minimal skill folder looks like this:
|
||||
|
||||
```
|
||||
my-skill/
|
||||
- SKILL.md
|
||||
```
|
||||
|
||||
More complex skills can add additional directories and files as needed.
|
||||
|
||||
|
||||
## The SKILL.md File
|
||||
|
||||
The skill's "entrypoint" is the `SKILL.md` file. It is the only file required to exist. The file must start with a YAML frontmatter followed by regular Markdown.
|
||||
|
||||
### YAML Frontmatter
|
||||
|
||||
The YAML frontmatter has 2 required properties:
|
||||
|
||||
- `name`
|
||||
- The name of the skill in hyphen-case
|
||||
- Restricted to lowercase Unicode alphanumeric + hyphen
|
||||
- Must match the name of the directory containing the SKILL.md
|
||||
- `description`
|
||||
- Description of what the skill does and when Claude should use it
|
||||
|
||||
There are 3 optional properties:
|
||||
|
||||
- `license`
|
||||
- The license applied to the skill
|
||||
- We recommend keeping it short (either the name of a license or the name of a bundled license file)
|
||||
- `allowed-tools`
|
||||
- A list of tools that are pre-approved to run
|
||||
- Currently only supported in Claude Code
|
||||
- `metadata`
|
||||
- A map from string keys to string values
|
||||
- Clients can use this to store additional properties not defined by the Agent Skills Spec
|
||||
- We recommend making your key names reasonably unique to avoid accidental conflicts
|
||||
|
||||
### Markdown Body
|
||||
|
||||
The Markdown body has no restrictions on it.
|
||||
58
spec/skill-client-integration.md
Normal file
58
spec/skill-client-integration.md
Normal file
@@ -0,0 +1,58 @@
|
||||
# Skill Client Integration Guide
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This guide is intended for developers looking to add Skills support to a new agent or product.
|
||||
|
||||
There are two ways to integrate skills into your agent:
|
||||
|
||||
1. Filesystem-based
|
||||
2. Tool-based
|
||||
|
||||
**Filesystem-based** Skill Clients have a computer environment (e.g., bash + unix) and are the most capable type of Skill Client since they can natively support skills that bundle scripts, code, and other resources. In this type of client, skills are "triggered" by the model issuing a shell command like `cat /path/to/my-skill/SKILL.md`. Similarly, when a skill refers to a bundled resource by relative path, the model uses shell commands to read or use the bundled asset.
|
||||
|
||||
**Tool-based** Skill Clients do not rely on a computer environment but instead define one or more tools that the model can use to trigger the skill and read or use bundled assets. The implementation details are left to the developer.
|
||||
|
||||
## Skill Installation
|
||||
|
||||
Skill installation depends on your agent architecture. For filesystem-based agents, a skill can be installed simply by copying the skill directory into the filesystem. For tool-based agents, the installation mechanism will depend on your specific architecture.
|
||||
|
||||
## Including Skills in the Agent's System Prompt
|
||||
|
||||
For the model to "trigger" a skill, it needs to know which skills are available. The progressive disclosure system starts by including a short list of information about each available skill in the context window (typically the system prompt). At a minimum, this must include the skill name and description. For filesystem-based Skill Clients, you must also include the absolute path to the skill's installed location.
|
||||
|
||||
The formatting of the list is up to you, but here is the format currently used at Anthropic:
|
||||
|
||||
```
|
||||
<available_skills>
|
||||
<skill>
|
||||
<name>
|
||||
my-skill
|
||||
</name>
|
||||
<description>
|
||||
the skill's description
|
||||
</description>
|
||||
<location>
|
||||
/path/to/my-skill/SKILL.md
|
||||
</location>
|
||||
</skill>
|
||||
<skill>
|
||||
...
|
||||
</skill>
|
||||
<skill>
|
||||
...
|
||||
</skill>
|
||||
</available_skills>
|
||||
```
|
||||
|
||||
The `<skill>` element repeats for each available skill.
|
||||
|
||||
**Fields**
|
||||
|
||||
- `name`
|
||||
- The name of the skill
|
||||
- Obtained from the `name` property in the SKILL.md file
|
||||
- `description`
|
||||
- Describes what the skill does and when the model should consider using it
|
||||
- Obtained from the `description` property in the SKILL.md file
|
||||
- `location`
|
||||
- The absolute filesystem path to the installed skill's SKILL.md file
|
||||
Reference in New Issue
Block a user