From 10e0fbe1a47b1706686db4195eb49ef515c3484b Mon Sep 17 00:00:00 2001 From: Keith Lazuka Date: Thu, 16 Oct 2025 11:32:56 -0400 Subject: [PATCH] Add initial Agent Skills Spec (#2) --- agent_skills_spec.md | 55 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) create mode 100644 agent_skills_spec.md diff --git a/agent_skills_spec.md b/agent_skills_spec.md new file mode 100644 index 00000000..6b6972b1 --- /dev/null +++ b/agent_skills_spec.md @@ -0,0 +1,55 @@ +# 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. + +# 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. + +# Additional Information + +For a minimal example, see the `template-skill` example. + +# Version History + +- 1.0 (2025-10-16) Public Launch